OpenAI 聊天补全

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/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 请求必须来自已配置的受信任代理来源；同主机回环代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
• 如果配置了 gateway.auth.rateLimit 且认证失败次数过多，端点会返回带有 Retry-After 的 429。

​

安全边界（重要）

• 这里的 HTTP bearer 认证不是细粒度的按用户范围模型。
• 用于此端点的有效 Gateway token/password 应视为 owner/operator 凭据。
• 通过该端点的请求会走与受信任运维操作相同的控制平面 agent 路径。
• 此端点没有单独的非 owner/按用户工具边界；一旦调用方通过了 Gateway 认证，OpenClaw 就会将其视为该 gateway 的受信任运维者。
• 对于共享密钥认证模式（token 和 password），即使调用方发送了更窄的 x-openclaw-scopes 头，端点也会恢复正常的完整运维者默认值。
• 可信、携带身份的 HTTP 模式（例如 trusted proxy 认证或 gateway.auth.mode="none"）在存在 x-openclaw-scopes 时会予以尊重，否则回退到正常的运维者默认 scope 集。
• 如果目标 agent 策略允许敏感工具，此端点可以使用它们。
• 请仅在 loopback/tailnet/private ingress 上保留此端点；不要将其直接暴露给公共互联网。

• gateway.auth.mode="token" 或 "password" + Authorization: Bearer ...
  • 证明持有共享的 gateway 运维者密钥
  • 忽略更窄的 x-openclaw-scopes
  • 恢复完整的默认运维者 scope 集： operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • 将此端点上的聊天轮次视为 owner-sender 轮次
• 可信、携带身份的 HTTP 模式（例如 trusted proxy 认证，或私有入口上的 gateway.auth.mode="none"）
  • 认证某个外层受信任身份或部署边界
  • 当头部存在时，尊重 x-openclaw-scopes
  • 当头部不存在时，回退到正常的运维者默认 scope 集
  • 只有当调用方显式缩窄 scopes 且省略 operator.admin 时，才会失去 owner 语义

​

以 agent 为先的模型契约

• 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> 为感知 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 开始。
• 越来越多更偏 agent 原生的客户端开始更喜欢 /v1/responses。

​

模型列表与 agent 路由

​

流式传输（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 token
• Model: openclaw/default

• GET /v1/models 应该列出 openclaw/default
• Open WebUI 应使用 openclaw/default 作为聊天模型 id
• 如果你希望该 agent 使用特定的后端 provider/model，请设置该 agent 的正常默认模型，或发送 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 agent 目标，而不是原始 provider 目录。
• openclaw/default 始终存在，因此同一个稳定 id 可以跨环境工作。
• 后端 provider/model 覆盖应放在 x-openclaw-model 中，而不是 OpenAI 的 model 字段里。
• /v1/embeddings 支持 input 为字符串或字符串数组。

​

相关

• Configuration reference
• OpenAI