OpenAI Chat Completions (HTTP)

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

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

- ''POST /v1/chat/completions''

- Same port as the Gateway (WS + HTTP multiplex): ''http://<gateway-host>:<port>/v1/chat/completions''

Under the hood, requests are executed as a normal Gateway agent run (same codepath as ''openclaw agent''), so routing/permissions/config match your Gateway.

Uses the Gateway auth configuration. Send a bearer token:

- ''Authorization: Bearer <token>''

Notes:

- When ''gateway.auth.mode="token"'', use ''gateway.auth.token'' (or ''OPENCLAW_GATEWAY_TOKEN'').

- When ''gateway.auth.mode="password"'', use ''gateway.auth.password'' (or ''OPENCLAW_GATEWAY_PASSWORD'').

No custom headers required: encode the agent id in the OpenAI ''model'' field:

- ''model: "openclaw:<agentId>"'' (example: ''"openclaw:main"'', ''"openclaw:beta"'')

- ''model: "agent:<agentId>"''（Aliases）

Or target a specific OpenClaw agent by header:

- ''x-openclaw-agent-id: <agentId>''（Defaults:''main''）

Advanced:

- ''x-openclaw-session-key: '''' to fully control session routing.

Set ''gateway.http.endpoints.chatCompletions.enabled'' to ''true'':

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

Set ''gateway.http.endpoints.chatCompletions.enabled'' to ''false'':

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

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

If the request includes an OpenAI ''user'' string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.

Set ''stream: true'' to receive Server-Sent Events (SSE):

- ''Content-Type: text/event-stream''

- Each event line is ''data: <json>''

- Stream ends with ''data: [DONE]''

Non-streaming:

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

Streaming:

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