OpenAI 聊天补全

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 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

​

身份验证

• 共享密钥身份验证（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 请求必须来自 已配置的受信任代理来源；同主机 local loopback 代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
• 如果配置了 gateway.auth.rateLimit 且身份验证失败次数过多，端点会返回带有 Retry-After 的 429。

​

安全边界（重要）

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

• gateway.auth.mode="token" 或 "password" + Authorization: Bearer ...
  • 证明持有共享的 Gateway 网关操作员密钥
  • 忽略范围更窄的 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 时，才会失去所有者语义

​

智能体优先的模型契约

• 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>"

​

启用端点

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

​

禁用端点

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

​

会话行为

​

为什么这个接口重要

• 大多数 Open WebUI、LobeChat 和 LibreChat 设置都期望 /v1/models。
• 许多 RAG 系统期望 /v1/embeddings。
• 现有 OpenAI 聊天客户端通常可以从 /v1/chat/completions 开始。
• 更多原生智能体客户端越来越偏好 /v1/responses。

​

模型列表和智能体路由

​

流式传输（SSE）

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

​

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 令牌
• Model：openclaw/default

• GET /v1/models 应列出 openclaw/default
• Open WebUI 应使用 openclaw/default 作为聊天模型 ID
• 如果你想为该智能体使用特定后端提供商/模型，请设置该智能体的正常默认模型或发送 x-openclaw-model

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

​

示例

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

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

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

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

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 智能体目标，而不是原始提供商目录。
• openclaw/default 始终存在，因此一个稳定 ID 可以跨环境工作。
• 后端提供商/模型覆盖应放在 x-openclaw-model 中，而不是 OpenAI model 字段中。
• /v1/embeddings 支持将 input 作为字符串或字符串数组。

​

相关

• 配置参考
• OpenAI