OpenAI chat completions

OpenClaw’s Gateway can serve a small OpenAI-compatible Chat Completions endpoint.

This endpoint is disabled by default. Enable it in config first.

• text

  Copy

  POST /v1/chat/completions
• Same port as the Gateway (WS + HTTP multiplex):
  text

  Copy

  http://<gateway-host>:<port>/v1/chat/completions

When the Gateway’s OpenAI-compatible HTTP surface is enabled, it also serves:

• text

  Copy

  GET /v1/models
• text

  Copy

  GET /v1/models/{id}
• text

  Copy

  POST /v1/embeddings
• text

  Copy

  POST /v1/responses

Under the hood, requests are executed as a normal Gateway agent run (same codepath as

), so routing/permissions/config match your Gateway.

Authentication

Uses the Gateway auth configuration.

Common HTTP auth paths:

• shared-secret auth (
  text

  Copy

  gateway.auth.mode="token"
  or
  text

  Copy

  "password"
  ):
  text

  Copy

  Authorization: Bearer <token-or-password>
• trusted identity-bearing HTTP auth (
  text

  Copy

  gateway.auth.mode="trusted-proxy"
  ): route through the configured identity-aware proxy and let it inject the required identity headers
• private-ingress open auth (
  text

  Copy

  gateway.auth.mode="none"
  ): no auth header required

Notes:

• When
  text

  Copy

  gateway.auth.mode="token"
  , use
  text

  Copy

  gateway.auth.token
  (or
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  ).
• When
  text

  Copy

  gateway.auth.mode="password"
  , use
  text

  Copy

  gateway.auth.password
  (or
  text

  Copy

  OPENCLAW_GATEWAY_PASSWORD
  ).
• When
  text

  Copy

  gateway.auth.mode="trusted-proxy"
  , the HTTP request must come from a configured trusted proxy source; same-host loopback proxies require explicit
  text

  Copy

  gateway.auth.trustedProxy.allowLoopback = true
  .
• If
  text

  Copy

  gateway.auth.rateLimit
  is configured and too many auth failures occur, the endpoint returns
  text

  Copy

  429
  with
  text

  Copy

  Retry-After
  .

Security boundary (important)

Treat this endpoint as a full operator-access surface for the gateway instance.

• HTTP bearer auth here is not a narrow per-user scope model.
• A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
• Requests run through the same control-plane agent path as trusted operator actions.
• There is no separate non-owner/per-user tool boundary on this endpoint; once a caller passes Gateway auth here, OpenClaw treats that caller as a trusted operator for this gateway.
• For shared-secret auth modes (
  text

  Copy

  token
  and
  text

  Copy

  password
  ), the endpoint restores the normal full operator defaults even if the caller sends a narrower
  text

  Copy

  x-openclaw-scopes
  header.
• Trusted identity-bearing HTTP modes (for example trusted proxy auth or
  text

  Copy

  gateway.auth.mode="none"
  ) honor
  text

  Copy

  x-openclaw-scopes
  when present and otherwise fall back to the normal operator default scope set.
• If the target agent policy allows sensitive tools, this endpoint can use them.
• Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.

Auth matrix:

• text

  Copy

  gateway.auth.mode="token"
  or
  text

  Copy

  "password"
  +
  text

  Copy

  Authorization: Bearer ...
  • proves possession of the shared gateway operator secret
  • ignores narrower
    text

    Copy

    x-openclaw-scopes
  • restores the full default operator scope set:
    text

    Copy

    operator.admin
    ,
    text

    Copy

    operator.approvals
    ,
    text

    Copy

    operator.pairing
    ,
    text

    Copy

    operator.read
    ,
    text

    Copy

    operator.talk.secrets
    ,
    text

    Copy

    operator.write
  • treats chat turns on this endpoint as owner-sender turns
• trusted identity-bearing HTTP modes (for example trusted proxy auth, or
  text

  Copy

  gateway.auth.mode="none"
  on private ingress)
  • authenticate some outer trusted identity or deployment boundary
  • honor
    text

    Copy

    x-openclaw-scopes
    when the header is present
  • fall back to the normal operator default scope set when the header is absent
  • only lose owner semantics when the caller explicitly narrows scopes and omits
    text

    Copy

    operator.admin

See Security and Remote access.

Agent-first model contract

OpenClaw treats the OpenAI

field as an agent target, not a raw provider model id.

• text

  Copy

  model: "openclaw"
  routes to the configured default agent.
• text

  Copy

  model: "openclaw/default"
  also routes to the configured default agent.
• text

  Copy

  model: "openclaw/<agentId>"
  routes to a specific agent.

Optional request headers:

• text

  Copy

  x-openclaw-model: <provider/model-or-bare-id>
  overrides the backend model for the selected agent.
• text

  Copy

  x-openclaw-agent-id: <agentId>
  remains supported as a compatibility override.
• text

  Copy

  x-openclaw-session-key: <sessionKey>
  fully controls session routing.
• text

  Copy

  x-openclaw-message-channel: <channel>
  sets the synthetic ingress channel context for channel-aware prompts and policies.

Compatibility aliases still accepted:

• text

  Copy

  model: "openclaw:<agentId>"
• text

  Copy

  model: "agent:<agentId>"

Enabling the endpoint

Set

to :

json5
Copy
{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: true },
      },
    },
  },
}

Disabling the endpoint

Set

to :

json5
Copy
{
  gateway: {
    http: {
      endpoints: {
        chatCompletions: { enabled: false },
      },
    },
  },
}

Session behavior

By default the endpoint is stateless per request (a new session key is generated each call).

If the request includes an OpenAI

string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.

Why this surface matters

This is the highest-leverage compatibility set for self-hosted frontends and tooling:

• Most Open WebUI, LobeChat, and LibreChat setups expect
  text

  Copy

  /v1/models
  .
• Many RAG systems expect
  text

  Copy

  /v1/embeddings
  .
• Existing OpenAI chat clients can usually start with
  text

  Copy

  /v1/chat/completions
  .
• More agent-native clients increasingly prefer
  text

  Copy

  /v1/responses
  .

Model list and agent routing

What does `/v1/models` return?

Does `/v1/models` list agents or sub-agents?

Why is `openclaw/default` included?

How do I override the backend model?

How do embeddings fit this contract?

Streaming (SSE)

Set

to receive Server-Sent Events (SSE):

• text

  Copy

  Content-Type: text/event-stream
• Each event line is
  text

  Copy

  data: <json>
• Stream ends with
  text

  Copy

  data: [DONE]

Open WebUI quick setup

For a basic Open WebUI connection:

• Base URL:
  text

  Copy

  http://127.0.0.1:18789/v1
• Docker on macOS base URL:
  text

  Copy

  http://host.docker.internal:18789/v1
• API key: your Gateway bearer token
• Model:
  text

  Copy

  openclaw/default

Expected behavior:

• text

  Copy

  GET /v1/models
  should list
  text

  Copy

  openclaw/default
• Open WebUI should use
  text

  Copy

  openclaw/default
  as the chat model id
• If you want a specific backend provider/model for that agent, set the agent's normal default model or send
  text

  Copy

  x-openclaw-model

Quick smoke:

bash
Copy
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

If that returns

, most Open WebUI setups can connect with the same base URL and token.

Examples

Non-streaming:

bash
Copy
curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openclaw/default",
    "messages": [{"role":"user","content":"hi"}]
  }'

Streaming:

bash
Copy
curl -N http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/gpt-5.4' \
  -d '{
    "model": "openclaw/research",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'

List models:

bash
Copy
curl -sS http://127.0.0.1:18789/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

Fetch one model:

bash
Copy
curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \
  -H 'Authorization: Bearer YOUR_TOKEN'

Create embeddings:

bash
Copy
curl -sS http://127.0.0.1:18789/v1/embeddings \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-openclaw-model: openai/text-embedding-3-small' \
  -d '{
    "model": "openclaw/default",
    "input": ["alpha", "beta"]
  }'

Notes:

• text

  Copy

  /v1/models
  returns OpenClaw agent targets, not raw provider catalogs.
• text

  Copy

  openclaw/default
  is always present so one stable id works across environments.
• Backend provider/model overrides belong in
  text

  Copy

  x-openclaw-model
  , not the OpenAI
  text

  Copy

  model
  field.
• text

  Copy

  /v1/embeddings
  supports
  text

  Copy

  input
  as a string or array of strings.

Related

• Configuration reference
• OpenAI