OpenAI 聊天补全
The Gateway can serve a small OpenAI-compatible Chat Completions surface. It is disabled by default.
启用后,它会在与 Gateway 相同的端口上提供以下所有服务(WS + HTTP 多路复用):
| 方法 | 路径 |
|---|---|
| POST | /v1/chat/completions |
| GET | /v1/models |
| GET | /v1/models/{id} |
| POST | /v1/embeddings |
POST /v1/responses 通过 gateway.http.endpoints.responses.enabled 单独启用。参见 OpenResponses API。
请求作为正常的 Gateway 代理运行执行(与 openclaw agent 相同的代码路径),因此路由、权限和配置与你的 Gateway 一致。
启用端点¶
设置 enabled: false(或省略它)以禁用。
安全边界(重要)¶
将此端点视为对 gateway 实例的完整操作员访问权限:
- 针对此端点的有效 Gateway token/password 等同于所有者/操作员凭据,而不是狭窄的按用户作用域。
- 请求通过可信操作员操作相同的控制平面代理路径运行,因此如果目标代理的策略允许敏感工具,此端点可以使用它们。
- 仅将其保留在 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(trusted-proxy 身份验证,或在私有入口上 gateway.auth.mode="none") |
存在时遵循 x-openclaw-scopes;缺失时回退到默认操作员作用域集合。仅当调用者显式缩小作用域并省略 operator.admin 时,才会失去所有者语义。对于 x-openclaw-model 等所有者级别控制,需要 operator.admin。 |
身份验证¶
使用 Gateway 身份验证配置(有关该模式的详细信息,参见 可信代理身份验证):
| 模式 | 身份验证方式 |
|---|---|
gateway.auth.mode="token" |
Authorization: Bearer <token>。通过 gateway.auth.token 或 OPENCLAW_GATEWAY_TOKEN 设置。 |
gateway.auth.mode="password" |
Authorization: Bearer <password>。通过 gateway.auth.password 或 OPENCLAW_GATEWAY_PASSWORD 设置。 |
gateway.auth.mode="trusted-proxy" |
通过配置的身份感知代理路由;它会注入所需的身份头。同主机 loopback 代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。 |
gateway.auth.mode="none" |
无需身份验证头(仅限私有入口)。 |
说明:
- 在
trusted-proxygateway 上绕过代理的同主机调用者可以直接回退到gateway.auth.password/OPENCLAW_GATEWAY_PASSWORD。任何Forwarded、X-Forwarded-*或X-Real-IP头证据都会使请求继续走 trusted-proxy 路径。 - 如果配置了
gateway.auth.rateLimit且身份验证尝试失败次数过多,端点将返回带有Retry-After头的429。
何时使用此端点¶
- 如果你的集成只是同一 gateway 的另一个操作员/客户端界面,请优先使用此端点,而不是添加新的内置通道。
- 对于直接连接到远程 gateway 的原生移动客户端,请优先使用 WebChat 或采用配对设备引导/设备 token 流程的 Gateway Protocol,这样设备就不需要共享 HTTP token/password。
- 当集成具有自己的用户、房间、webhook 投递或出站传输的外部消息网络时,请改为构建通道插件。参见 构建插件。
代理优先的模型契约¶
OpenClaw 将 OpenAI 的 model 字段视为代理目标,而不是原始提供商模型 id。
model 值 |
路由到 |
|---|---|
model 值 |
路由到 |
|---|---|
openclaw |
已配置的默认代理 |
openclaw/default |
已配置的默认代理(稳定别名;即使真实默认代理 id 在不同环境之间变化,也可以安全地硬编码) |
openclaw/<agentId> 或 openclaw:<agentId> |
特定代理 |
agent:<agentId> |
特定代理(兼容性别名) |
可选请求头:
| 请求头 | 效果 |
|---|---|
x-openclaw-model: <provider/model-or-bare-id> |
覆盖所选代理的后端模型。共享密钥 bearer 调用方可以直接使用此请求头;携带身份的调用方(trusted-proxy,或带有 x-openclaw-scopes 的私有无认证入口)需要 operator.admin,否则返回 403 missing scope: operator.admin。 |
x-openclaw-agent-id: <agentId> |
用于代理选择的兼容性覆盖。 |
x-openclaw-session-key: <sessionKey> |
显式会话路由。如果使用了保留的内部命名空间(subagent:、cron:、acp:),会以 400 invalid_request_error 拒绝。 |
x-openclaw-message-channel: <channel> |
为支持通道的提示/策略设置合成入口通道上下文。 |
/v1/models 列出顶层代理目标(openclaw、openclaw/default、openclaw/<agentId>),而不是后端提供商模型,也不是子代理;子代理保持为内部执行拓扑。如果省略 x-openclaw-model,所选代理将使用其正常配置的模型运行。
模型列表和详情端点需要 operator.read 或包含它的 scope,因为它们会暴露全局代理目标清单。
/v1/embeddings 使用相同的代理目标 model id。发送 x-openclaw-model(来自共享密钥调用方,或具有 operator.admin 的携带身份调用方)以选择特定嵌入模型;否则请求使用所选代理的正常嵌入配置。
嵌入模型覆盖保持在代理已配置的嵌入提供商内。可识别的提供商前缀必须与该提供商匹配;其他包含斜杠的值,例如 library/bge-m3 或 hf:org/model,仍保持为完整模型 ID。这也适用于显式配置的嵌入模型名称。
会话行为¶
默认情况下,端点是每个请求无状态的(每次调用都会生成新的会话密钥)。
如果请求包含 OpenAI user 字符串,Gateway 会从中派生稳定的会话密钥,以便重复调用可以共享一个代理会话。对于自定义应用,请在每个对话线程中复用相同的 user 值;除非你希望多个对话/设备共享同一个 OpenClaw 会话,否则避免使用账户级标识符。仅当需要跨多个客户端/线程进行显式路由控制时,才使用 x-openclaw-session-key,并使用应用拥有的密钥,避免上述保留命名空间。
显式隐身会话延续¶
通过 x-openclaw-session-key(即 sessionKey 覆盖)显式选择或继续隐身对话,需要有效的 operator.admin 权限。此规则遵循权限,而不是入口:它拒绝没有 owner/admin 权限的 trusted-proxy 调用方,以及显式将 x-openclaw-scopes 缩小到 admin 以下的私有 gateway.auth.mode="none" 调用方(例如缩小到 operator.write)。两者都会收到带有 forbidden 错误的 HTTP 403。在此路径上,无 profile 的私有无认证调用方会得到 missing scope: operator.admin;对于有 profile 支持的调用方,响应会以这种错误格式隐藏私有目标(其中 <sessionKey> 是请求的覆盖值):
{
"error": {
"message": "Incognito session \"<sessionKey>\" was not found.",
"type": "forbidden"
}
}
Owner/admin 调用方保留显式隐身会话延续。没有 x-openclaw-scopes 的私有无认证请求会收到默认 operator scopes,包括 operator.admin,因此被视为 owner/admin。保留的内部命名空间覆盖(subagent:、cron:、acp:)仍然是单独的验证失败,并仍返回带有 invalid_request_error 的 HTTP 400。
请求限制¶
该端点使用内置限制:每个请求体 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,
},
},
},
},
},
}
图像设置默认为:
| 键 | 默认值 |
|---|---|
images.allowUrl |
false(未启用时,URL 来源的 image_url 部分会被拒绝) |
images.maxBytes |
每张图像 10MB |
images.maxRedirects |
3 |
images.timeoutMs |
10s |
HEIC/HEIF image_url 来源会被接受,并在通过共享的 OpenClaw 图像处理器(Rastermill)交付给提供方之前规范化为 JPEG;对于需要外部编解码器支持的格式,它会回退到系统转换器(sips、ImageMagick、GraphicsMagick 或 ffmpeg)。
安全说明:将主机名加入允许列表不会绕过私有/内部 IP 阻止。对于暴露在互联网上的网关,除应用层防护外,还应应用网络出站控制。参见 安全。
聊天工具契约¶
/v1/chat/completions 支持一个与常见 OpenAI Chat 客户端兼容的函数工具子集。
支持的请求字段¶
| 字段 | 说明 |
|---|---|
tools |
{ "type": "function", "function": { ... } } 数组 |
tool_choice |
"auto"、"none"、"required" 或 { "type": "function", "function": { "name": "..." } } |
messages[*].role: "tool" |
后续轮次 |
messages[*].tool_call_id |
将工具结果绑定回先前的工具调用 |
max_completion_tokens |
正的安全整数;每次调用中总 completion Token 的上限(包含推理 Token)。当前字段名;当两个字段均非 null 时使用。为 null 或省略时保持未设置。 |
max_tokens |
正的安全整数;旧版别名。当 max_completion_tokens 非 null 时仍会进行校验,然后在优先级上被忽略。为 null 或省略时保持未设置。 |
temperature |
0-2 的数字;尽力而为,并转发到上游提供方。超出范围时返回 400 invalid_request_error。 |
top_p |
0-1 的数字;尽力而为。超出范围时返回 400 invalid_request_error。 |
frequency_penalty |
-2.0 到 2.0 的数字;尽力而为。超出范围时返回 400 invalid_request_error。 |
presence_penalty |
-2.0 到 2.0 的数字;尽力而为。超出范围时返回 400 invalid_request_error。 |
seed |
整数;尽力而为。非整数值时返回 400 invalid_request_error。 |
stop |
字符串或最多 4 个字符串的数组;尽力而为。超过 4 个序列或包含非字符串/空条目时返回 400 invalid_request_error。 |
所有采样和 Token 上限字段都通过同一 agent 流参数通道传输,并尽力转发:
- Token 上限:传输字段名由提供方传输层选择:OpenAI 系端点使用
max_completion_tokens,仅接受旧名称的提供方(Mistral、Chutes)使用max_tokens。 stop映射到传输层的 stop 字段:Chat Completions 后端使用stop,Anthropic 使用stop_sequences。OpenAI Responses API 没有 stop 参数,因此stop不会应用于 Responses 支持的模型。- 基于 ChatGPT 的 Codex Responses 后端使用固定的服务端采样,并在请求到达该后端之前移除
temperature/top_p(以及max_output_tokens、metadata、prompt_cache_retention、service_tier)。
不支持的变体¶
以下情况会返回 400 invalid_request_error:
- 非数组的
tools、非 function 的工具条目,或缺少tool.function.name tool_choice的变体,例如allowed_tools和customtool_choice.function.name的值与提供的工具不匹配
对于 tool_choice: "required" 和固定函数的 tool_choice,端点会缩小暴露给客户端的函数工具集,指示运行时在响应之前调用客户端工具,并在 agent 响应中没有匹配的、结构化的客户端工具调用时返回错误。这适用于调用方提供的 HTTP tools 列表,而不是每个内部 OpenClaw agent 工具。
非流式工具响应结构¶
当智能体调用工具时,响应使用:
choices[0].finish_reason = "tool_calls"choices[0].message.tool_calls[]条目,包含id、type: "function"、function.name、function.arguments(JSON 字符串)- 工具调用前的助手评论,位于
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" 消息。这会继续同一智能体推理循环,以生成最终答案。
如果工具没有产生文本,仍应使用 content: "" 或空文本部分数组包含其结果。空结果会完成该调用;省略结果则不会。旧版 role: "function" 结果可以使用其函数 name 和 content: null。
流式(SSE)¶
流式会保留来自不同助手消息的重复内容。如果更正无法通过追加到已发送文本来表示,流会报告错误,而不是以不一致的内容完成。
设置 stream: true 以接收 Server-Sent Events:
Content-Type: text/event-stream- 每个事件行都是
data: <json> - 流以
data: [DONE]结束
失败的智能体运行,包括整个智能体超时,会返回错误,而不是成功完成。流式失败会发出 error 对象,随后是 [DONE];部分内容可能已经到达客户端。超时设置遵循 智能体循环。
断开 HTTP 客户端会取消活动的源 URL 下载和智能体运行。如果取消发生在准备输入期间,Gateway 会释放该下载,并且不会开始另一个输入下载或智能体运行。这适用于流式和非流式请求。如果 Gateway 本身在客户端仍连接时取消智能体运行,请求会以 500 api_error 和消息 agent run was cancelled 失败,而不是作为提供商超时。
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 的携带身份调用方)。
快速冒烟测试:
如果它返回 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":"Summarize my tasks for today"}]
}'
对于该对话的后续调用,重用相同的 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":"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/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 作为字符串或字符串数组。
响应包含 usage.prompt_tokens 和 usage.total_tokens。原生 Ollama 和 OpenAI 兼容的嵌入提供商会透传其报告的 token 计数,包括零。没有用量报告的提供商对这两个字段都返回零;OpenClaw 不会估算 token 用量。
提供商失败使用与聊天补全相同的错误映射:缺少提供商凭据会返回 401 authentication_error 并附带设置指导,未知提供商模型会返回 404 invalid_request_error,提供商过载会返回 503 api_error。凭据值会被脱敏。意外失败会返回 500 api_error 和 internal error。
对于支持该功能的模型,正整数 dimensions 用于请求输出向量大小。它会覆盖所选智能体当前生效的 memory.search.outputDimensionality,并且在禁用记忆搜索时也适用。省略它会保留已配置或提供商默认大小。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw