OpenAI Chat Completions (HTTP)

OpenClaw 网关可以提供一个兼容 OpenAI 的 Chat Completions 端点。

这个端点默认关闭，需要先在配置中启用。

POST /v1/chat/completions
与网关共用同一端口（WS + HTTP 复用）：http://<gateway-host>:<port>/v1/chat/completions

底层实现上，请求走的是和 openclaw agent 完全相同的网关 agent 执行路径，路由、权限、配置都一致。

认证

使用网关认证配置，发送 bearer token：

Authorization: Bearer <token>

说明：

当 gateway.auth.mode="token" 时，使用 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
当 gateway.auth.mode="password" 时，使用 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
如果配置了 gateway.auth.rateLimit，认证失败次数过多时端点返回 429 并带 Retry-After 头。

安全边界（重要）

请将此端点视为对网关实例的完整操作员级访问。

这里的 HTTP bearer 认证不是细粒度的用户隔离模型。
能通过此端点认证的 token/密码，应当作操作员级凭证对待。
请求走的是和可信操作员操作相同的控制面 agent 路径。
此端点没有独立的非管理员/用户工具边界——一旦通过认证，OpenClaw 将调用者视为该网关的可信操作员。
如果目标 agent 策略允许敏感工具，此端点也能使用。
仅在回环/tailnet/私有入口上暴露此端点；不要直接面向公网。

详见安全和远程访问。

选择 agent

无需自定义请求头——在 OpenAI 的 model 字段中编码 agent id 即可：

model: "openclaw:<agentId>"（例如："openclaw:main"、"openclaw:beta"）
model: "agent:<agentId>"（别名）

也可以通过请求头指定：

x-openclaw-agent-id: <agentId>（默认：main）

高级用法：

x-openclaw-session-key: <sessionKey> 完全控制会话路由。

启用端点

将 gateway.http.endpoints.chatCompletions.enabled 设为 true：

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

禁用端点

将 gateway.http.endpoints.chatCompletions.enabled 设为 false：

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

会话行为

默认情况下，端点每次请求无状态（每次调用生成新的 session key）。

如果请求中包含 OpenAI 的 user 字段，网关会从中派生稳定的 session key，这样多次调用可以共享同一个 agent 会话。

流式传输（SSE）

设置 stream: true 以接收 Server-Sent Events (SSE)：

Content-Type: text/event-stream
每行事件格式为 data: <json>
流结束标记为 data: [DONE]

示例

非流式：

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

流式：

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