古法编程

Appearance

OpenClaw Gateway 提供与 OpenAI 兼容的 HTTP API 端点（/v1/chat/completions、/v1/models 等），默认关闭。启用后在配置中设置 gateway.http.endpoints.chatCompletions.enabled = true，认证方式由 Gateway 的 auth.mode 决定（token / password / trusted-proxy / none）。注意：该端点的有效令牌等同于全操作员权限，不要直接暴露到公网。Agent 选择通过 model 字段指定，例如 openclaw/default 路由到默认 Agent，后端模型覆盖用 x-openclaw-model 头。用 curl http://127.0.0.1:18789/v1/models -H 'Authorization: Bearer YOUR_TOKEN' 可快速验证。

OpenClaw OpenAI Chat Completions 接口：启用、认证与 Agent 路由 ​

OpenClaw 的 Gateway 可暴露出一个小型 OpenAI 兼容的 Chat Completions HTTP 端点。

该端点默认禁用，需要先在配置中显式开启。

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

开启后还会提供以下端点：

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

底层逻辑与 openclaw agent 命令走同一代码路径，因此路由、权限、配置均与当前 Gateway 实例一致。

认证方式 ​

使用 Gateway 的认证配置。常见的方式：

  • 共享密钥认证（gateway.auth.mode="token" 或 "password"）
    Authorization: Bearer <token-or-password>
  • 可信代理认证（gateway.auth.mode="trusted-proxy"）
    请求必须通过配置的可信代理转发，代理负责注入身份头。
  • 公开无认证（gateway.auth.mode="none"）
    无需任何认证头，但只建议在私有网络内使用。

注意事项：

  • mode="token" 时，使用 gateway.auth.token 或环境变量 OPENCLAW_GATEWAY_TOKEN。
  • mode="password" 时，使用 gateway.auth.password 或 OPENCLAW_GATEWAY_PASSWORD。
  • mode="trusted-proxy" 时，同一主机上的环回代理也需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
  • 信任代理模式下，本地直连（绕过代理）的调用者可使用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 作为回落认证。但如果请求携带了 Forwarded、X-Forwarded-* 或 X-Real-IP 头，仍走代理认证逻辑。
  • 若配置了 gateway.auth.rateLimit 且认证失败次数超过限制，返回 429，响应头含 Retry-After。

安全边界（重要） ​

把该端点视为 Gateway 实例的全操作员访问入口。

  • HTTP Bearer 认证在这里不是细粒度的用户级权限模型。
  • 有效的 Gateway 令牌/密码应视为 owner/operator 凭据。
  • 请求通过控制平面 agent 路径执行，与受信操作员操作一致。
  • 该端点没有独立的非 owner 或基于用户的工具边界；一旦调用者通过 Gateway 认证，OpenClaw 将其视为该 Gateway 的可信操作员。
  • 对于共享密钥认证模式（token 和 password），即使调用者发送了更窄的 x-openclaw-scopes 头，端点也会恢复完整的 operator 默认作用域。
  • 信任身份模式的认证（如 trusted-proxy 或 mode="none"）会尊重 x-openclaw-scopes 头（如果存在），否则回退到完整的 operator 默认作用域。
  • 如果目标 agent 策略允许敏感工具，该端点可以使用它们。
  • 务必将该端点放在 loopback、tailnet 或私有网络入口内，不要直接暴露到公网。

认证矩阵 ​

gateway.auth.mode 值认证方式x-openclaw-scopes 处理默认作用域（scope）
"token" 或 "password"Authorization: Bearer <token>忽略该头，恢复全 operator 默认operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
信任身份模式（trusted-proxy 或 "none" 在私有入口）外部信任的身份如果存在则认可；否则回退全 operator 默认同上（除非调用者主动收窄作用域并去掉 operator.admin）

参见 安全文档 和 远程访问。

Agent 优先的模型约定 ​

OpenClaw 将 OpenAI 调用中的 model 字段视为 agent 目标，而不是原始的 provider 模型 ID。

  • model: "openclaw" → 路由到配置的默认 agent。
  • model: "openclaw/default" → 同上。
  • 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: &lt;channel&gt; 设置合成入站渠道上下文（影响渠道感知的 prompt 和策略）。

仍支持的兼容别名：

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

启用端点 ​

在 Gateway 配置中将 gateway.http.endpoints.chatCompletions.enabled 设为 true：

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

禁用端点 ​

设为 false 即可：

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

会话行为 ​

默认每次请求无状态（每次生成新的会话 key）。

如果请求中包含 OpenAI 的 user 字符串，Gateway 会从中派生稳定的会话 key，使重复调用能共享同一个 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 的稳定别名。即使不同环境下默认 agent ID 不同，客户端也能一直使用同一个可预测的 id。

如何覆盖后端模型？

使用 x-openclaw-model 头。例如： x-openclaw-model: openai/gpt-5.4 或 x-openclaw-model: gpt-5.5。不提供时，选中的 agent 使用其正常的配置模型。

嵌入（embeddings）怎么工作？

/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: &lt;json&gt;
  • 流以 data: [DONE] 结束

聊天工具契约 ​

/v1/chat/completions 支持兼容常见 OpenAI 聊天客户端的函数工具子集。

支持的请求字段 ​

  • tools: 数组 { "type": "function", "function": { ... } }
  • tool_choice: "auto", "none"
  • messages[*].role: "tool" 后续消息
  • messages[*].tool_call_id 绑定工具结果到之前的工具调用
  • max_completion_tokens: 数字；总 completion token 上限（包括 reasoning tokens）。OpenAI Chat Completions 的当前字段名，如果同时出现 max_completion_tokens 和 max_tokens，优先使用前者。
  • max_tokens: 数字；向后兼容的旧别名，当 max_completion_tokens 存在时被忽略。
  • temperature: 数字；尽力转发到上游 provider（通过 agent stream-param 通道）。
  • top_p: 数字；尽力转发到上游 provider（通过 agent stream-param 通道）。

当设置了 token 上限字段时，值会通过 agent stream-param 通道转发给上游 provider。实际发送的字段名由 provider 传输层决定：OpenAI 系列端点用 max_completion_tokens，仅接受旧名称的 provider（如 Mistral、Chutes）用 max_tokens。采样参数（temperature、top_p）也走同样的 stream-param 通道；基于 ChatGPT 的 Codex Responses 后端会在服务端丢弃它们（使用固定采样）。

不支持的变体 ​

对于不支持的 tool 变体，端点返回 400 invalid_request_error，包括：

  • 非数组的 tools
  • 非 function 类型的 tool 条目
  • 缺少 tool.function.name
  • tool_choice 变体如 allowed_tools 和 custom
  • tool_choice: "required"（目前还未强制，未来会硬性实施）
  • tool_choice: { "type": "function", "function": { "name": "..." } }（同上）
  • tool_choice.function.name 与提供的 tools 不匹配

非流式工具响应格式 ​

当 agent 决定调用工具时，响应使用：

  • choices[0].finish_reason = "tool_calls"
  • choices[0].message.tool_calls[] 条目包含：
    • id
    • type: "function"
    • function.name
    • function.arguments（JSON 字符串）

agent 在调用工具前的文本回复出现在 choices[0].message.content（可能为空）。

流式工具响应格式 ​

当 stream: true 时，工具调用以增量 SSE 块发出：

  • 初始 assistant role delta
  • 可选的 assistant 文本 delta
  • 一个或多个 delta.tool_calls 块，携带工具身份和参数片段
  • 最后一块的 finish_reason: "tool_calls"
  • data: [DONE]

如果设置了 stream_options.include_usage=true，会在 [DONE] 前多一个 usage chunk。

工具后续循环 ​

收到 tool_calls 后，客户端应执行请求的函数，然后发送后续请求，包含：

  • 之前的 assistant tool-call 消息
  • 一个或多个 role: "tool" 消息，每个带上对应的 tool_call_id

这样 gateway agent 才能继续同一个推理循环，最终给出 assistant 的最终回答。

Open WebUI 快速设置 ​

基本配置：

  • Base URL: http://127.0.0.1:18789/v1
  • macOS 上 Docker：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 支持字符串或字符串数组。

相关文档 ​

常见问题 ​

OpenClaw 的 OpenAI 兼容接口默认是关闭的吗？怎么开启？ ​

是的，默认关闭。 在 Gateway 配置中设置 gateway.http.endpoints.chatCompletions.enabled = true 即可开启。无需重启 Gateway，重载配置后立即生效。

调用 /v1/chat/completions 时 model 字段填什么？ ​

填 OpenClaw 的 Agent 目标，例如 openclaw/default 或 openclaw/<agentId>。不是原始模型 ID。如需指定后端模型，使用 x-openclaw-model 头，例如 x-openclaw-model: openai/gpt-4o。

这个接口安全吗？能直接暴露到公网吗？ ​

不安全，千万别直接暴露到公网。 该端点上的有效令牌等同于全操作员权限，可以访问敏感工具。务必将其放在 loopback、tailnet 或私有网络入口内。如果必须远程访问，请使用 SSH 隧道或 VPN。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策