OpenAI 聊天补全

Gateway 网关可以提供一个小型的 OpenAI 兼容 Chat Completions 接口。它默认禁用。

启用后，它会在与 Gateway 网关相同的端口上提供以下所有接口（WS + HTTP 多路复用）：

请求会作为普通的 Gateway 网关智能体运行来执行（与 openclaw agent 使用相同的代码路径），因此路由、权限和配置均与你的 Gateway 网关一致。

启用端点

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

将 enabled: false 设为禁用值（或省略它）即可禁用。

安全边界（重要）

应将此端点视为对 Gateway 网关实例的完整操作员访问权限：

• 此端点的有效 Gateway 网关令牌/密码等同于所有者/操作员凭据，而非范围受限的单用户权限。
• 请求会通过与受信任操作员操作相同的控制平面智能体路径运行，因此，如果目标智能体的策略允许使用敏感工具，此端点也可以使用这些工具。
• 仅应将其部署在 local loopback、tailnet 或私有入口上。切勿将其暴露到公共互联网。

身份验证矩阵：

请参阅操作员权限范围、安全和远程访问。

身份验证

使用 Gateway 网关身份验证配置（有关该模式的详细信息，请参阅受信任代理身份验证）：

注意：

• 在 trusted-proxy Gateway 网关上绕过代理的同主机调用方可以直接回退到 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD。任何 Forwarded、X-Forwarded-* 或 X-Real-IP 请求头证据都会使请求继续使用受信任代理路径。
• 如果已配置 gateway.auth.rateLimit，且身份验证失败次数过多，端点将返回 429，并附带 Retry-After 请求头。

何时使用此端点

• 如果你的集成只是同一 Gateway 网关的另一个操作员/客户端接口，应优先使用此端点，而不是添加新的内置渠道。
• 对于直接连接远程 Gateway 网关的原生移动客户端，应优先使用 WebChat 或采用配对设备引导/设备令牌流程的 Gateway 协议，这样设备无需共享 HTTP 令牌/密码。
• 如果要集成拥有自身用户、房间、Webhook 投递或出站传输的外部消息网络，则应改为构建渠道插件。请参阅构建插件。

智能体优先的模型契约

OpenClaw 将 OpenAI 的 model 字段视为智能体目标，而非原始提供商模型 ID。

可选请求头：

/v1/models 列出顶层智能体目标（openclaw、openclaw/default、openclaw/<agentId>），而非后端提供商模型或子智能体；子智能体仍属于内部执行拓扑。如果省略 x-openclaw-model，所选智能体将使用其正常配置的模型运行。

/v1/embeddings 使用相同的智能体目标 model ID。发送 x-openclaw-model（调用方须使用共享密钥，或为具有 operator.admin 的携带身份调用方）以选择特定的嵌入模型；否则，请求将使用所选智能体的正常嵌入设置。

会话行为

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

如果请求包含 OpenAI user 字符串，Gateway 网关会据此派生稳定的会话键，使重复调用可以共享智能体会话。对于自定义应用，应为每个对话线程复用相同的 user 值；除非你希望多个对话/设备共享同一个 OpenClaw 会话，否则应避免使用账户级标识符。仅当需要跨多个客户端/线程进行显式路由控制时，才使用 x-openclaw-session-key，并使用由应用拥有且避开上述保留命名空间的键。

请求限制

该端点使用以下内置限制：每个请求正文 20 MB、最新用户消息中包含 8 个 image_url 部分，以及累计 20 MB 的已解码图像 数据。图像来源策略仍可通过 gateway.http.endpoints.chatCompletions.images 进行配置：

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

图像设置的默认值为：

系统接受 HEIC/HEIF image_url 来源，并在通过共享的 OpenClaw 图像处理器（Rastermill）传递给提供商之前将其标准化为 JPEG；对于需要外部编解码器支持的格式，该处理器会回退到系统转换器（sips、ImageMagick、GraphicsMagick 或 ffmpeg）。

安全说明：将主机名加入允许列表不会绕过私有/内部 IP 屏蔽。对于暴露在互联网中的 Gateway 网关，除应用级防护外，还应实施网络出口控制。请参阅安全。

聊天工具契约

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

支持的请求字段

所有采样和 token 上限字段都通过同一个智能体流参数渠道传递，并以尽力而为的方式转发：

• Token 上限：传输字段名由提供商传输层选择：OpenAI 系列端点使用 max_completion_tokens，仅接受旧版名称的提供商（Mistral、Chutes）使用 max_tokens。
• stop 映射到传输层的停止字段：Chat Completions 后端使用 stop，Anthropic 使用 stop_sequences。OpenAI Responses API 没有停止参数，因此 stop 不会应用于基于 Responses 的模型。
• 基于 ChatGPT 的 Codex Responses 后端使用固定的服务端采样，并在请求到达该后端前移除 temperature/top_p（以及 max_output_tokens、metadata、prompt_cache_retention、service_tier）。

不支持的变体

以下情况返回 400 invalid_request_error：

• 非数组 tools、非函数工具条目或缺少 tool.function.name
• tool_choice 变体，例如 allowed_tools 和 custom
• 与所提供工具不匹配的 tool_choice.function.name 值

对于 tool_choice: "required" 和固定到函数的 tool_choice，该端点会缩小向客户端公开的函数工具集，指示运行时在响应前调用客户端工具，并在智能体响应中没有匹配的结构化客户端工具调用时报错。这适用于调用方提供的 HTTP tools 列表，而不是 OpenClaw 智能体的所有内部工具。

非流式工具响应结构

当智能体调用工具时，响应使用：

• choices[0].finish_reason = "tool_calls"
• 包含 id、type: "function"、function.name、function.arguments（JSON 字符串）的 choices[0].message.tool_calls[] 条目
• 工具调用前的助手注释，位于 choices[0].message.content 中（可能为空）

流式工具响应结构

当 stream: true 时，工具调用以增量 SSE 块到达：先是初始助手角色增量，然后是可选的助手注释增量，再是一个或多个携带工具标识和参数片段的 delta.tool_calls 块，最后是包含 finish_reason: "tool_calls" 和 data: [DONE] 的结束块。

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

工具后续循环

收到 tool_calls 后，执行所请求的函数，并发送后续请求，其中包含先前的助手工具调用消息以及一条或多条具有匹配 tool_call_id 的 role: "tool" 消息。这会继续同一个智能体推理循环，以生成最终答案。

流式传输（SSE）

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

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

Open WebUI 快速设置

• 基础 URL：http://127.0.0.1:18789/v1
• macOS 上 Docker 的基础 URL：http://host.docker.internal:18789/v1
• API 密钥：你的 Gateway 网关 bearer token
• 模型：openclaw/default

预期行为：GET /v1/models 会列出 openclaw/default，Open WebUI 会将其用作聊天模型 ID。对于特定的后端提供商/模型，请设置智能体的常规默认模型，或发送 x-openclaw-model（使用共享密钥的调用方，或具有 operator.admin 的身份调用方）。

快速冒烟测试：

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

如果返回 openclaw/default，大多数 Open WebUI 设置都可以使用相同的基础 URL 和 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":"总结我今天的任务"}]  }'

在该对话的后续调用中复用相同的 user 值，以继续同一个智能体会话。

非流式：

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/embeddings 支持将 input 设为字符串或字符串数组。

相关内容

• 配置参考
• 操作员权限范围
• OpenAI