OpenAI Chat Completions (HTTP)

OpenClaw 的 Gateway 可以提供一个小型的兼容 OpenAI 的 Chat Completions 端点。

此端点默认禁用。请先在配置中启用它。

POST /v1/chat/completions
与 Gateway 使用相同端口(WS + HTTP 多路复用):http://<gateway-host>:<port>/v1/chat/completions

在底层,请求作为正常的 Gateway agent 运行执行(与 openclaw agent 相同的代码路径),因此路由/权限/配置与您的 Gateway 匹配。

身份验证

使用 Gateway 身份验证配置。发送 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)。

选择 agent

无需自定义请求头:在 OpenAI model 字段中编码 agent id:

model: "openclaw:<agentId>"(示例:"openclaw:main"、"openclaw:beta")
model: "agent:<agentId>"(别名)

或通过请求头指定特定的 OpenClaw agent:

x-openclaw-agent-id: <agentId>(默认:main)

高级:

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

启用端点

将 gateway.http.endpoints.chatCompletions.enabled 设置为 true:

json5

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

禁用端点

将 gateway.http.endpoints.chatCompletions.enabled 设置为 false:

json5

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

会话行为

默认情况下,端点每个请求都是无状态的(每次调用都会生成一个新的会话密钥)。

如果请求包含 OpenAI user 字符串,Gateway 将从中派生一个稳定的会话密钥,因此重复调用可以共享一个 agent 会话。

流式传输 (SSE)

设置 stream: true 以接收服务器发送事件 (SSE):

Content-Type: text/event-stream
每个事件行是 data: <json>
流以 data: [DONE] 结束

示例

非流式:

bash

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

流式:

bash

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

OpenAI Chat Completions (HTTP) ​

身份验证 ​

选择 agent ​

启用端点 ​

禁用端点 ​

会话行为 ​

流式传输 (SSE) ​

示例 ​