Skip to main content

OpenAI Chat Completions (HTTP)

WednesdayAI’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 wednesdayai agent), so routing/permissions/config match your Gateway.

Authentication

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).
  • If gateway.auth.rateLimit is configured and too many auth failures occur, the endpoint returns 429 with 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.
  • 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.
See Security and Remote access.

Choosing an agent

No custom headers required: encode the agent id in the OpenAI model field:
  • model: "openclaw:<agentId>" (example: "openclaw:main", "openclaw:beta")
  • model: "agent:<agentId>" (alias)
Or target a specific WednesdayAI agent by header:
  • x-openclaw-agent-id: <agentId> (default: main)
Advanced:
  • x-openclaw-session-key: <sessionKey> to fully control session routing.

Enabling the endpoint

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

Disabling the endpoint

Set gateway.http.endpoints.chatCompletions.enabled to 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 user string, the Gateway derives a stable session key from it, so repeated calls can share an agent session.

Workspace lane denial

If the target agent has workspace lanes enabled and the run cannot be attributed to a linked identity in session.identityLinks, the endpoint returns 403 with:
With stream: true, the denial arrives as a final content chunk containing Error: <message> (finish reason stop) instead of a 403 status. HTTP requests carry no paired device, so calls into lane-enabled agents are currently denied; the error message states the reason. See Workspace Lanes.

Streaming (SSE)

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]

Examples

Non-streaming:
Streaming: