跳转到内容
OpenClaw Docs

OpenAI chat completions

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(网关) 代理运行执行（与 openclaw agent 代码路径相同），因此路由/权限/配置与您的 Gateway(网关) 匹配。

身份验证

Section titled “身份验证”

使用 Gateway(网关) 身份验证配置。

常见的 HTTP 身份验证路径：

  • 共享密钥身份验证 (gateway.auth.mode="token" 或 "password"): Authorization: Bearer <token-or-password>
  • 受信任的承载身份的 HTTP 身份验证 (gateway.auth.mode="trusted-proxy"): 通过配置的感知身份代理进行路由，并让其注入 所需的身份标头
  • 私有入口开放身份验证 (gateway.auth.mode="none"): 不需要身份验证标头

注意：

  • 当使用 gateway.auth.mode="token" 时，使用 gateway.auth.token (或 OPENCLAW_GATEWAY_TOKEN)。
  • 当使用 gateway.auth.mode="password" 时，使用 gateway.auth.password (或 OPENCLAW_GATEWAY_PASSWORD)。
  • 当 gateway.auth.mode="trusted-proxy" 时，HTTP 请求必须来自 配置的受信任代理源；同主机回环代理需要显式 gateway.auth.trustedProxy.allowLoopback = true。
  • 绕过代理的内部同主机调用者可以使用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 作为本地直接 后备方案。任何 Forwarded、X-Forwarded-* 或 X-Real-IP 标头证据 都会将请求保留在受信任代理路径上。
  • 如果配置了 gateway.auth.rateLimit 并且发生了过多的身份验证失败，端点将返回 429 和 Retry-After。

安全边界（重要）

Section titled “安全边界（重要）”

应将此端点视为 Gateway 实例的完全操作员访问接口。

  • 此处的 HTTP 承载者认证并非狭义的每用户范围模型。
  • 此端点的有效 Gateway(网关) 令牌/密码应被视为所有者/操作员凭证。
  • 请求通过受信任操作员操作相同的控制平面代理路径运行。
  • 此端点上没有单独的非所有者/每用户工具边界；一旦调用者在此通过了 Gateway(网关) 身份验证，OpenClaw 就会将该调用者视为此网关的受信任操作员。
  • 对于共享密钥身份验证模式（token 和 password），即使调用者发送了较窄的 x-openclaw-scopes 标头，端点也会恢复正常的完全操作员默认值。
  • 受信任的承载身份的 HTTP 模式（例如受信任代理身份验证或 gateway.auth.mode="none"）在存在 x-openclaw-scopes 时会遵守它，否则回退到正常的操作员默认范围集。
  • 如果目标代理策略允许敏感工具，此端点可以使用它们。
  • 请将此端点保持在环回/tailnet/专用入口上；不要将其直接暴露给公共互联网。

身份验证矩阵：

  • gateway.auth.mode="token" 或 "password" + Authorization: Bearer ...
    • 证明拥有共享的网关操作员密钥
    • 忽略较窄的 x-openclaw-scopes
    • 恢复完整的默认操作员范围集： operator.admin、operator.approvals、operator.pairing、 operator.read、operator.talk.secrets、operator.write
    • 将此端点上的聊天轮次视为所有者-发送者轮次
  • 承载受信任身份的 HTTP 模式（例如受信任的代理认证，或专用入口上的 gateway.auth.mode="none"）
    • 对某个外层受信任身份或部署边界进行身份验证
    • 当存在该标头时，遵守 x-openclaw-scopes
    • 当该标头不存在时，回退到常规的操作员默认作用域集
    • 仅当调用方显式缩小作用域并省略 operator.admin 时，才会丢失所有者语义

请参阅 安全性 和 远程访问。

Agent-first 模型契约

Section titled “Agent-first 模型契约”

OpenClaw 将 OpenAI OpenClawOpenAImodel 字段视为代理目标，而非原始提供商模型 ID。

  • model: "openclaw" 路由至配置的默认代理。
  • model: "openclaw/default" 也路由至配置的默认代理。
  • model: "openclaw/<agentId>" 路由至特定的代理。

可选请求标头：

  • x-openclaw-model: <provider/model-or-bare-id> 覆盖所选代理的后端模型。
  • x-openclaw-agent-id: <agentId> 作为兼容性覆盖项仍受支持。
  • x-openclaw-session-key: <sessionKey> 完全控制会话路由。
  • x-openclaw-message-channel: <channel> 为感知渠道的提示词和策略设置合成入口渠道上下文。

仍接受的兼容性别名：

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

启用端点

Section titled “启用端点”

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

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

禁用端点

Section titled “禁用端点”

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

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

会话行为

Section titled “会话行为”

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

如果请求包含 OpenAI OpenAIuserGateway(网关) 字符串，Gateway 会据此派生一个稳定的会话密钥，以便重复调用可以共享一个代理会话。

为什么此接口很重要

Section titled “为什么此接口很重要”

这是针对自托管前端和工具的影响力最大的兼容性集合：

  • 大多数 Open WebUI、LobeChat 和 LibreChat 设置都期望使用 /v1/models。
  • 许多 RAG 系统期望 /v1/embeddings。
  • 现有的 OpenAI 聊天客户端通常可以从 /v1/chat/completions 开始。
  • 更多面向代理的客户端越来越倾向于 /v1/responses。

模型列表与代理路由

Section titled “模型列表与代理路由”
`/v1/models` 返回什么？

一个 OpenClaw 代理目标列表。

返回的 id 是 openclaw、openclaw/default 和 `openclaw/

条目。 将它们直接用作 OpenAImodel` 值。

`/v1/models` 列出的是代理还是子代理？

它列出的是顶层代理目标，而不是后端提供商模型，也不是子代理。

子代理保持内部执行拓扑。它们不会显示为伪模型。

为什么包含 `openclaw/default`？

openclaw/default 是配置的默认代理的稳定别名。

这意味着客户端可以继续使用一个可预测的 id，即使真实的默认代理 id 在环境之间发生了变化。

如何覆盖后端模型？

使用 x-openclaw-model。

示例： x-openclaw-model: openai/gpt-5.4 x-openclaw-model: gpt-5.5

如果省略它，所选代理将使用其正常配置的模型选择运行。

嵌入如何适应此合约？

/v1/embeddings 使用相同的代理目标 model id。

使用 model: "openclaw/default" 或 `model: “openclaw/

“。 当您需要特定的嵌入模型时，请在 x-openclaw-model` 中发送它。 如果没有该标头，请求将传递给所选代理的正常嵌入设置。

流式传输 (SSE)

Section titled “流式传输 (SSE)”

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

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

聊天工具契约

Section titled “聊天工具契约”

/v1/chat/completionsOpenAI 支持与通用 OpenAI 聊天客户端兼容的函数工具子集。

支持的请求字段

Section titled “支持的请求字段”
  • tools: { "type": "function", "function": { ... } } 数组
  • tool_choice: "auto", "none"
  • messages[*].role: "tool" 后续轮次
  • messages[*].tool_call_id 用于将工具结果绑定回先前的工具调用
  • max_completion_tokensOpenAI: 数字；总补全令牌（包括推理令牌）的每次调用上限。当前的 OpenAI 聊天补全字段名称；当同时发送 max_completion_tokens 和 max_tokens 时优先使用。
  • max_tokens: 数字；为向后兼容而接受的旧版别名。如果也存在 max_completion_tokens 则忽略。
  • temperature: 数字；通过代理流参数渠道尽力转发到上游提供商的采样温度。
  • top_p: 数字；通过代理流参数渠道尽力转发到上游提供商的核采样。

当设置了任一令牌上限字段时，该值会通过代理流参数渠道转发到上游提供商。发送到上游提供商的实际线字段名称由提供商传输选择：OpenAI 系列端点为 max_completion_tokensOpenAI，仅接受旧版名称的提供商（例如 Mistral 和 Chutes）为 max_tokens。采样字段（temperature, top_p）遵循相同的流参数渠道；基于 ChatGPT 的 Codex Responses 后端会在服务器端将其剥离，因为它使用固定采样。

不支持的变体

Section titled “不支持的变体”

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

  • 非数组 tools
  • 非函数工具条目
  • 缺少 tool.function.name
  • tool_choice 变体，例如 allowed_tools 和 custom
  • tool_choice: "required"（尚未在运行时强制执行；将在实施硬性强制执行后得到支持）
  • tool_choice: { "type": "function", "function": { "name": "..." } }（理由与 required 相同）
  • 与提供的 tools 不匹配的 tool_choice.function.name 值

非流式工具响应结构

Section titled “非流式工具响应结构”

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

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

工具调用之前的助手评语在 choices[0].message.content 中返回（可能为空）。

流式工具响应结构

Section titled “流式工具响应结构”

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

  • 初始助手角色增量
  • 可选的助手评语增量
  • 一个或多个 delta.tool_calls 块，携带工具标识和参数片段
  • 带有 finish_reason: "tool_calls" 的最后一个块
  • data: [DONE]

如果 stream_options.include_usage=true，则会在 [DONE] 之前发出一个尾部用量块。

工具后续循环

Section titled “工具后续循环”

收到 tool_calls 后，客户端应执行请求的函数并发送包含以下内容的后续请求：

  • 之前的助手工具调用消息
  • 一条或多条 role: "tool" 消息，具有匹配的 tool_call_id

这允许网关代理运行继续相同的推理循环并生成最终的助手回答。

Open WebUI 快速设置

Section titled “Open WebUI 快速设置”

对于基本的 Open WebUI 连接：

  • Base URL: http://127.0.0.1:18789/v1
  • macOS 上的 Docker Base URL: DockermacOShttp://host.docker.internal:18789/v1
  • API 密钥：您的 Gateway(网关) 持有者令牌
  • 模型: openclaw/default

预期行为：

  • GET /v1/models 应列出 openclaw/default
  • Open WebUI 应该使用 openclaw/default 作为聊天模型 ID
  • 如果您希望为该代理使用特定的后端提供商/模型，请设置代理的常规默认模型或发送 x-openclaw-model

快速测试：

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

如果返回 openclaw/default，大多数 Open WebUI 设置可以使用相同的基础 URL 和令牌进行连接。

示例

Section titled “示例”

非流式：

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

流式：

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

列出模型：

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

获取一个模型：

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

创建嵌入：

Terminal window
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/modelsOpenClaw 返回 OpenClaw 代理目标，而不是原始提供商目录。
  • openclaw/default 始终存在，因此一个稳定的 ID 可在不同环境中使用。
  • 后端提供商/模型覆盖属于 x-openclaw-modelOpenAI，而不是 OpenAI model 字段。
  • /v1/embeddings 支持 input 作为字符串或字符串数组。

相关内容

Section titled “相关内容”