OpenAI chat completions

The Gateway can serve a small OpenAI-compatible Chat Completions surface. It is disabled by default.

Once enabled, it serves all of these on the same port as the Gateway (WS + HTTP multiplex):

POST /v1/responses is enabled separately with gateway.http.endpoints.responses.enabled. See OpenResponses API.

Requests run as a normal Gateway agent run (same codepath as openclaw agent), so routing, permissions, and config match your Gateway.

Enabling the endpoint

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

Set enabled: false (or omit it) to disable.

Security boundary (important)

Treat this endpoint as full operator access to the gateway instance:

• A valid Gateway token/password for this endpoint is equivalent to an owner/operator credential, not a narrow per-user scope.
• Requests run through the same control-plane agent path as trusted operator actions, so if the target agent's policy allows sensitive tools, this endpoint can use them.
• Keep it on loopback/tailnet/private ingress only. Do not expose it to the public internet.

Auth matrix:

See Operator scopes, Security, and Remote access.

Authentication

Uses the Gateway auth configuration (see Trusted proxy auth for that mode's details):

Notes:

• Same-host callers that bypass the proxy on a trusted-proxy gateway can fall back to gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD directly. Any Forwarded, X-Forwarded-*, or X-Real-IP header evidence keeps the request on the trusted-proxy path instead.
• If gateway.auth.rateLimit is configured and too many auth attempts fail, the endpoint returns 429 with a Retry-After header.

When to use this endpoint

• Prefer this over adding a new built-in channel when your integration is just another operator/client surface for the same gateway.
• For native mobile clients that connect directly to a remote gateway, prefer WebChat or the Gateway Protocol with the paired-device bootstrap/device-token flow, so the device does not need a shared HTTP token/password.
• Build a channel plugin instead when integrating an external messaging network with its own users, rooms, webhook delivery, or outbound transport. See Building plugins.

Agent-first model contract

OpenClaw treats the OpenAI model field as an agent target, not a raw provider model id.

Optional request headers:

/v1/models lists top-level agent targets (openclaw, openclaw/default, openclaw/<agentId>), not backend provider models and not sub-agents; sub-agents stay internal execution topology. If you omit x-openclaw-model, the selected agent runs with its normal configured model.

/v1/embeddings uses the same agent-target model ids. Send x-openclaw-model (from a shared-secret caller, or an identity-bearing caller with operator.admin) to pick a specific embedding model; otherwise the request uses the selected agent's normal embedding setup.

Session behavior

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. For custom apps, reuse the same user value per conversation thread; avoid account-level identifiers unless you want multiple conversations/devices to share one OpenClaw session. Use x-openclaw-session-key only when you need explicit routing control across multiple clients/threads, with application-owned keys that avoid the reserved namespaces above.

Explicit incognito session continuation

Explicitly selecting or continuing an incognito conversation with x-openclaw-session-key (the sessionKey override) requires effective operator.admin authority. This rule follows authority, not ingress: it denies both trusted-proxy callers without owner/admin authority and private gateway.auth.mode="none" callers that explicitly narrow x-openclaw-scopes below admin (for example, to operator.write). Either receives HTTP 403 with a forbidden error. A profile-less private no-auth caller on this path gets missing scope: operator.admin; for a profile-backed caller, the response hides the private target with this error shape (where <sessionKey> is the requested override):

{  "error": {    "message": "Incognito session \"<sessionKey>\" was not found.",    "type": "forbidden"  }}

Owner/admin callers keep explicit incognito session continuation. A private no-auth request without x-openclaw-scopes receives the default operator scopes, including operator.admin, and is therefore treated as owner/admin. Reserved internal namespace overrides (subagent:, cron:, acp:) remain a separate validation failure and still return HTTP 400 with invalid_request_error.

Request limits

The endpoint uses built-in limits of 20 MB per request body, 8 image_url parts from the latest user message, and 20 MB of cumulative decoded image data. Image source policy remains configurable under gateway.http.endpoints.chatCompletions.images:

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

Image settings default to:

HEIC/HEIF image_url sources are accepted and normalized to JPEG before provider delivery through the shared OpenClaw image processor (Rastermill), which falls back to a system converter (sips, ImageMagick, GraphicsMagick, or ffmpeg) for formats needing external codec support.

Security note: allowlisting a hostname does not bypass private/internal IP blocking. For internet-exposed gateways, apply network egress controls in addition to app-level guards. See Security.

Chat tool contract

/v1/chat/completions supports a function-tool subset compatible with common OpenAI Chat clients.

Supported request fields

All sampling and token-cap fields ride the same agent stream-param channel and are forwarded best-effort:

• Token cap: the wire field name is chosen by the provider transport: max_completion_tokens for OpenAI-family endpoints, max_tokens for providers that only accept the legacy name (Mistral, Chutes).
• stop maps to the transport's stop field: stop for Chat Completions backends, stop_sequences for Anthropic. The OpenAI Responses API has no stop parameter, so stop is not applied on Responses-backed models.
• The ChatGPT-based Codex Responses backend uses fixed server-side sampling and strips temperature/top_p (along with max_output_tokens, metadata, prompt_cache_retention, service_tier) before the request reaches that backend.

Unsupported variants

Returns 400 invalid_request_error for:

• non-array tools, non-function tool entries, or missing tool.function.name
• tool_choice variants such as allowed_tools and custom
• tool_choice.function.name values that do not match a provided tool

For tool_choice: "required" and function-pinned tool_choice, the endpoint narrows the exposed client function-tool set, instructs the runtime to call a client tool before responding, and errors if the agent response has no matching structured client-tool call. This applies to the caller-supplied HTTP tools list, not every internal OpenClaw agent tool.

Non-streaming tool response shape

When the agent calls tools, the response uses:

• choices[0].finish_reason = "tool_calls"
• choices[0].message.tool_calls[] entries with id, type: "function", function.name, function.arguments (JSON string)
• Assistant commentary before the tool call, in choices[0].message.content (possibly empty)

Streaming tool response shape

When stream: true, tool calls arrive as incremental SSE chunks: an initial assistant role delta, optional assistant commentary deltas, one or more delta.tool_calls chunks carrying tool identity and argument fragments, then a final chunk with finish_reason: "tool_calls" and data: [DONE].

For required or function-pinned tool choices, prose is held until the matching call is confirmed. When the run returns finalized prose, the stream uses that text instead of provisional deltas.

If stream_options.include_usage=true, a trailing usage chunk is emitted before [DONE].

Tool follow-up loop

After receiving tool_calls, execute the requested function(s) and send a follow-up request that includes the prior assistant tool-call message plus one or more role: "tool" messages with matching tool_call_id. This continues the same agent reasoning loop to produce the final answer.

If a tool produces no text, still include its result with content: "" or an empty text-part array. An empty result completes the call; omitting the result does not. Legacy role: "function" results may use content: null with their function name.

Streaming (SSE)

Streaming preserves repeated content from separate assistant messages. If a correction cannot be represented by appending to text already sent, the stream reports an error rather than completing with inconsistent content.

Set stream: true to receive Server-Sent Events:

• Content-Type: text/event-stream
• Each event line is data: <json>
• Stream ends with data: [DONE]

Failed agent runs, including whole-agent timeouts, return an error instead of a successful completion. A streaming failure emits an error object followed by [DONE]; partial content may already have reached the client. Timeout settings follow the agent loop.

Disconnecting the HTTP client cancels active source-URL downloads and the agent run. If cancellation happens while preparing input, the Gateway releases that download and does not start another input download or the agent run. This applies to both streaming and non-streaming requests.

Open WebUI quick setup

• Base URL: http://127.0.0.1:18789/v1
• Docker on macOS base URL: http://host.docker.internal:18789/v1
• API key: your Gateway bearer token
• Model: openclaw/default

Expected behavior: GET /v1/models lists openclaw/default, and Open WebUI uses it as the chat model id. For a specific backend provider/model, set the agent's normal default model, or send x-openclaw-model (shared-secret caller, or identity-bearing caller with operator.admin).

Quick smoke test:

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

If that returns openclaw/default, most Open WebUI setups can connect with the same base URL and token.

Examples

Stable session for one app conversation:

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",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

Reuse the same user value on later calls for that conversation to continue the same agent session.

Non-streaming:

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:

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:

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

Fetch one model:

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

Create embeddings:

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"]  }'

/v1/embeddings supports input as a string or array of strings.

For models that support it, a positive integer dimensions requests the output vector size. It overrides the selected agent's active memory.search.outputDimensionality and also applies when memory search is disabled. Omitting it keeps the configured or provider default size.

Related

• Configuration reference
• Operator scopes
• OpenAI