OpenAI Chat Completions

• 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 请求必须来自 已配置的受信任代理来源；同主机 loopback 代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
• 本机同主机的内部调用如果绕过代理，可以使用 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD 作为本地直接 回退方案。任何 Forwarded、X-Forwarded-* 或 X-Real-IP 头的证据 都会让请求保持在 trusted-proxy 路径上。
• 如果配置了 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 语义

​

何时使用此端点

• 当你的集成只是同一个 gateway 的另一个运维者/客户端表面时，优先使用它，而不是新增一个内建通道。
• 对于直接连接远程 gateway 的原生移动客户端，优先使用 WebChat 或 Gateway Protocol，并实现配对设备启动/设备令牌流程，这样设备就不需要共享 HTTP token/password。
• 如果你是在把外部消息网络与其自身的用户、房间、webhook 投递或出站传输集成起来，那么应改为构建一个通道插件。参见 Building plugins。

​

以 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]

​

Chat 工具契约

​

支持的请求字段

• tools: array of { "type": "function", "function": { ... } }
• tool_choice: "auto", "none", "required", or { "type": "function", "function": { "name": "..." } }
• messages[*].role: "tool" follow-up turns
• messages[*].tool_call_id for binding tool results back to a prior tool call
• max_completion_tokens: number; per-call cap for total completion tokens (reasoning tokens included). Current OpenAI Chat Completions field name; preferred when both max_completion_tokens and max_tokens are sent.
• max_tokens: number; legacy alias accepted for backwards compatibility. Ignored when max_completion_tokens is also present.
• temperature: number; best-effort sampling temperature forwarded to the upstream provider via the agent stream-param channel.
• top_p: number; best-effort nucleus sampling forwarded to the upstream provider via the agent stream-param channel.
• frequency_penalty: number; best-effort frequency penalty forwarded to the upstream provider via the agent stream-param channel. Validated range: -2.0 to 2.0. Returns 400 invalid_request_error for out-of-range values.
• presence_penalty: number; best-effort presence penalty forwarded to the upstream provider via the agent stream-param channel. Validated range: -2.0 to 2.0. Returns 400 invalid_request_error for out-of-range values.
• seed: number (integer); best-effort seed forwarded to the upstream provider via the agent stream-param channel. Returns 400 invalid_request_error for non-integer values.
• stop: string or array of up to 4 strings; best-effort stop sequences forwarded to the upstream provider via the agent stream-param channel. Returns 400 invalid_request_error for more than 4 sequences or non-string/empty entries.

​

不支持的变体

• non-array tools
• non-function tool entries
• missing tool.function.name
• tool_choice variants such as allowed_tools and custom
• tool_choice.function.name values that do not match provided tools

​

Non-streaming tool response shape

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

​

流式工具响应形状

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

​

工具后续循环

• 先前的 assistant tool-call 消息
• 一条或多条 role: "tool" 消息，且 tool_call_id 匹配

​

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",
    "user": "conv:YOUR_CONVERSATION_ID",
    "messages": [{"role":"user","content":"请总结我今天的任务"}]
  }'

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

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

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 为字符串或字符串数组。

​

相关

• 配置参考
• OpenAI