#17577: feat: add GET /v1/models endpoint for OpenAI-compatible model listing
gateway
size: S
Cluster:
Model Management Enhancements
## Summary
Adds `GET /v1/models` and `GET /v1/models/<id>` endpoints to the OpenAI-compatible
HTTP API. This enables compatibility with clients that probe `/v1/models` before
using `/v1/chat/completions` — including n8n, Open WebUI, LibreChat, OneDev, and
any standard OpenAI SDK client.
- Each configured agent is exposed as a model with id `openclaw/<agentId>`
- The default agent is also exposed as the plain `openclaw` model
- Auth is optional on `/v1/models` (many clients don't send bearer tokens for
model listing)
- Gated by the existing `chatCompletions.enabled` config flag
- Returns proper error responses: 404 for unknown models, 405 for wrong method
## Changes
Only modifies `src/gateway/openai-http.ts`:
- Adds `handleModelsRequest()` function (~55 lines)
- Adds two imports: `loadConfig` from `config/io.js` and `listAgentsForGateway` from `session-utils.js`
- Adds dispatch call at the top of `handleOpenAiHttpRequest()`
## Example Response
```json
GET /v1/models → 200
{
"object": "list",
"data": [
{ "id": "openclaw", "object": "model", "created": 1771031029, "owned_by": "openclaw" },
{ "id": "openclaw/main", "object": "model", "created": 1771031029, "owned_by": "openclaw", "name": "Main Agent" }
]
}
GET /v1/models/openclaw → 200
{ "id": "openclaw", "object": "model", "created": 1771031029, "owned_by": "openclaw" }
GET /v1/models/nonexistent → 404
{ "error": { "message": "Model 'nonexistent' not found.", "type": "invalid_request_error" } }
POST /v1/models → 405
```
## Test Plan
- [x] `GET /v1/models` → 200 with model list
- [x] `GET /v1/models/openclaw` → 200 with single model object
- [x] `GET /v1/models` without auth → 200 (auth optional)
- [x] `GET /v1/models/nonexistent` → 404 with error
- [x] `POST /v1/models` → 405
- [x] `/v1/chat/completions` unaffected
- [x] Tested with OneDev (real client) via Nginx Proxy Manager
- [x] `pnpm build` passes with zero errors
- [x] Rebased onto current main
## Design Decisions
1. **Auth optional on /v1/models**: Many OpenAI-compatible clients (OneDev, some
n8n nodes) don't send bearer tokens when listing models. Making auth optional
here improves compatibility.
2. **Single file change**: The entire feature fits in `openai-http.ts` with no
new dependencies. Uses existing `loadConfig()` and `listAgentsForGateway()`.
3. **Gated by chatCompletions.enabled**: Reuses the existing config flag rather
than adding a new one, keeping the config surface small.
4. **Model ID format**: `openclaw/<agentId>` for agents, plain `openclaw` for
the default. This follows the `provider/model` convention used by other APIs.
## AI Disclosure 🤖
- **AI-assisted**: Yes — written with Claude (Opus), with human review and testing
- **Testing level**: Build-verified (`pnpm build` zero errors); endpoint tested with curl and OneDev client
- **Understanding**: The author understands the code — it adds a URL-matched handler that enumerates agents via existing `listAgentsForGateway()` and returns them as OpenAI model objects
Most Similar PRs
#20954: feat: per-agent model allowlist
by coletebou · 2026-02-19
70.0%
#13079: feat: Add OpenAI-compatible API option to CLI for self-hosted models
by MikeWang0316tw · 2026-02-10
68.9%
#20875: feat(gateway): Add /config HTTP endpoint for external dashboards
by abhiramee08b021 · 2026-02-19
68.0%
#16099: feat: add opencode-cli as CLI backend provider
by imwxc · 2026-02-14
67.5%
#19710: feat(nvidia): expand NIM model catalog from 3 to 38 models
by 88plug · 2026-02-18
66.3%
#18697: fix: include forward-compat models in model catalog for allowlist val…
by dmitry-orabey · 2026-02-17
66.0%
#21882: feat(gateway): filter models.list by agents.defaults.models allowlist
by kckylechen1 · 2026-02-20
65.9%
#20747: feat(copilot): support Claude models with correct context windows (...
by yuf1011 · 2026-02-19
65.7%
#15742: feat: add Edgee AI Gateway as provider
by manthis · 2026-02-13
65.6%
#21599: fix(xai): extend Grok model prefix support + add native Responses A...
by RonySpark · 2026-02-20
65.6%