Using the OpenAI Chat Completions Endpoint

OpenAI Chat Completions (HTTP)

Ever tried to connect a custom agent to a frontend like Open WebUI, only to find it only speaks “OpenAI”? It’s a common headache when you want to use your favorite tools with a specialized backend. OpenClaw makes this easy by providing an OpenAI-compatible endpoint directly in the Gateway.

OpenClaw’s Gateway provides a small OpenAI-compatible Chat Completions endpoint. This endpoint is disabled by default, so you’ll need to enable it in your config first.

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

When you enable the Gateway’s OpenAI-compatible HTTP surface, it also provides:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/responses

Under the hood, requests are executed as a normal Gateway agent run. This uses the same codepath as openclaw agent, so routing, permissions, config, and logic match your Gateway setup.

Authentication

This endpoint uses the Gateway auth configuration. You just need to 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.
• Always ensure your bearer token is sent correctly in the Authorization header.

Security boundary (important)

You should treat this endpoint as a full operator-access surface for your gateway instance.

• HTTP bearer auth here is not a narrow per-user scope model.
• You should treat a valid Gateway token or password as an owner credential.
• Requests run through the same control-plane agent path as trusted operator actions.
• There is no separate tool boundary for non-owners on this endpoint.
• Once a caller passes Gateway auth here, OpenClaw treats that caller as a trusted operator.
• If the target agent policy allows sensitive tools, this endpoint can use them.
• Keep this endpoint on loopback, tailnet, private ingress, or internal networks; do not expose it directly to the public internet.

See Security and Remote access.

Agent-first model contract

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

• model: "openclaw" or model: "openclaw/default" routes to the configured default agent.
• model: "openclaw/<agentId>" routes to a specific agent.

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

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

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

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

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

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

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

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