OpenAI Chat Completions（HTTP）

OpenClaw 的 Gateway 可提供小型的 OpenAI 兼容 Chat Completions 接口。

该接口默认禁用，需先在配置中启用。

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

启用 Gateway 的 OpenAI 兼容 HTTP 接口后，同时提供：

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

底层请求作为普通 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）。
若配置了 gateway.auth.rateLimit 且认证失败次数过多，接口返回 429 并附带 Retry-After。

安全边界（重要）

将此接口视为 Gateway 实例的完全操作员权限访问面。

此处的 HTTP Bearer 认证并非窄权限的单用户模型。
该接口的有效 Gateway token/password 应视为 owner/operator 凭据。
请求通过与可信操作员操作相同的控制面 Agent 路径执行。
该接口上无独立的非 owner/单用户工具边界；一旦调用者通过 Gateway 认证，OpenClaw 将其视为可信操作员。
若目标 Agent 策略允许敏感工具，该接口也可使用。
请将此接口保持在 loopback/tailnet/私有网络中；不要直接暴露到公网。

参见安全和远程访问。

Agent 优先的模型约定

OpenClaw 将 OpenAI 的 model 字段视为 Agent 目标，而非原始的 provider 模型 ID。

model: "openclaw" 路由到配置的默认 Agent。
model: "openclaw/default" 同样路由到配置的默认 Agent。
model: "openclaw/<agentId>" 路由到特定 Agent。

可选的请求头：

x-openclaw-model: <provider/model-or-bare-id> 覆盖选定 Agent 的后端模型。
x-openclaw-agent-id: <agentId> 作为兼容性覆盖继续支持。
x-openclaw-session-key: <sessionKey> 完全控制会话路由。
x-openclaw-message-channel: <channel> 为渠道感知的 Prompt 和策略设置合成入站渠道上下文。

仍支持的兼容别名：

model: "openclaw:<agentId>"
model: "agent:<agentId>"

启用接口

将 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 会话。

这套接口的价值

这是对自托管前端和工具集兼容性最高的接口组合：

大多数 Open WebUI、LobeChat 和 LibreChat 接入都需要 /v1/models。
许多 RAG 系统需要 /v1/embeddings。
现有的 OpenAI 聊天客户端通常能直接用 /v1/chat/completions 开始工作。
更多 Agent 原生客户端越来越倾向于使用 /v1/responses。

模型列表与 Agent 路由

/v1/models 返回什么？

OpenClaw Agent 目标列表。返回的 ID 是 openclaw、openclaw/default 和 openclaw/<agentId> 条目，可直接用作 OpenAI 的 model 值。

/v1/models 列出的是 Agent 还是子 Agent？

列出的是顶层 Agent 目标，不包括后端 provider 模型，也不包括子 Agent。子 Agent 是内部执行拓扑，不以伪模型形式出现。

为什么包含 openclaw/default？

openclaw/default 是配置的默认 Agent 的稳定别名。客户端可使用这个可预测的 ID，即使环境之间默认 Agent ID 发生变化也不受影响。

如何覆盖后端模型？

使用 x-openclaw-model。例如：x-openclaw-model: openai/gpt-5.4 或 x-openclaw-model: gpt-5.4。省略时，选定 Agent 使用其正常配置的模型。

嵌入如何融入这套约定？

/v1/embeddings 使用相同的 Agent 目标 model ID。使用 model: "openclaw/default" 或 model: "openclaw/<agentId>"。需要特定嵌入模型时，通过 x-openclaw-model 指定；否则请求传递给选定 Agent 的正常嵌入配置。

流式输出（SSE）

设置 stream: true 接收 Server-Sent Events：

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

Open WebUI 快速接入

基本的 Open WebUI 连接配置：

Base URL：http://127.0.0.1:18789/v1
macOS 上 Docker 的 Base URL：http://host.docker.internal:18789/v1
API key：你的 Gateway Bearer token
Model：openclaw/default

预期行为：

GET /v1/models 应列出 openclaw/default
Open WebUI 应使用 openclaw/default 作为聊天模型 ID
若需为该 Agent 指定特定后端 provider/model，设置 Agent 的默认模型或发送 x-openclaw-model

快速冒烟测试：

bash

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

若返回 openclaw/default，大多数 Open WebUI 接入可使用相同的 base URL 和 token。

示例

非流式：

bash

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

流式：

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-model: openai/gpt-5.4' \
  -d '{
    "model": "openclaw/research",
    "stream": true,
    "messages": [{"role":"user","content":"hi"}]
  }'

列出模型：

bash

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

查询单个模型：

bash

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

创建嵌入：

bash

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/models 返回 OpenClaw Agent 目标，而非原始 provider 目录。
openclaw/default 始终存在，可在各环境中使用同一稳定 ID。
后端 provider/model 覆盖应放在 x-openclaw-model 中，而非 OpenAI 的 model 字段。
/v1/embeddings 的 input 支持字符串或字符串数组。

OpenAI Chat Completions（HTTP） ​

认证 ​

安全边界（重要） ​

Agent 优先的模型约定 ​

启用接口 ​

禁用接口 ​

会话行为 ​

这套接口的价值 ​

模型列表与 Agent 路由 ​

流式输出（SSE） ​

Open WebUI 快速接入 ​

示例 ​

OpenAI Chat Completions（HTTP）

认证

安全边界（重要）

Agent 优先的模型约定

启用接口

禁用接口

会话行为

这套接口的价值

模型列表与 Agent 路由

流式输出（SSE）

Open WebUI 快速接入

示例