OpenClaw Gateway OpenAI 兼容 HTTP API 实战指南让 /v1/chat/completions 驱动你的 Agent【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw Gateway 内置了一个与 OpenAI Chat Completions 兼容的 HTTP 端点面默认关闭启用后可以让任何「只认 OpenAI 协议」的客户端、SDK 或工具直接驱动 OpenClaw Agent请求走的是与openclaw agent完全相同的控制平面运行路径。本文以 docs/gateway/openai-http-api.md 为主体结合 src/gateway/openai-http.ts 的源码实现完整讲解端点启用、认证与安全边界、Agent 优先的 model 契约、会话行为、工具调用function calling、SSE 流式、图片输入限制以及 Open WebUI 等场景的实战接入让你读完即可安全、正确地接入这一端点。端点概览一个端口四种 OpenAI 兼容路径Gateway 本身是 WS HTTP 多路复用multiplex的单一端口。启用 OpenAI 兼容端点后它会在与 Gateway 相同的端口上额外提供以下四个路径MethodPathPOST/v1/chat/completionsGET/v1/modelsGET/v1/models/{id}POST/v1/embeddings注意POST /v1/responses由独立的开关gateway.http.endpoints.responses.enabled控制对应 OpenResponses API见 docs/gateway/openresponses-http-api.md不在本端点范围内。从源码结构看src/gateway/openai-http.tshandleOpenAiHttpRequest将请求绑定到/v1/chat/completions路径并复用 Gateway 的通用 JSON POST 端点处理框架handleGatewayPostJsonEndpoint传入requiredOperatorMethod: chat.send。这意味着请求并非独立服务而是作为一个普通 Gateway agent run 被执行——路由、权限、配置均与你的 Gateway 完全一致。这一设计是理解本端点一切行为尤其是安全模型的出发点。启用端点一行配置端点默认关闭需要在 Gateway 配置中显式开启{ gateway: { http: { endpoints: { chatCompletions: { enabled: true }, }, }, }, }设置enabled: false或直接省略该字段即关闭。除此之外chatCompletions下还支持图片输入策略images子配置详见下文「请求限制与图片策略」。安全边界重要这是操作员级入口请把该端点视为对 Gateway 实例的完整操作员访问full operator access而不是一个窄范围的普通用户接口。具体含义持有该端点的有效 Gateway token/password等价于持有 owner/operator 凭证请求运行在与受信操作员动作相同的控制平面 Agent 路径上因此如果目标 Agent 的策略允许敏感工具该端点就能使用它们只应暴露在 loopback / tailnet / 私有入口private ingress上严禁暴露到公网。源码中的注释也印证了这一点src/gateway/openai-http.ts“Compat HTTP uses a different scope model from generic HTTP helpers: shared-secret bearer auth is treated as full operator access here”兼容 HTTP 使用与通用 HTTP 辅助不同的 scope 模型共享密钥 bearer 认证在此被视为完整操作员访问。认证矩阵Auth path行为gateway.auth.modetoken或passwordAuthorization: Bearer ...证明持有共享 Gateway 密钥。忽略任何x-openclaw-scopes头恢复完整默认操作员 scope 集operator.admin、operator.approvals、operator.pairing、operator.read、operator.talk.secrets、operator.write。聊天轮次按 owner-sender 轮次处理。受信身份 HTTPtrusted-proxy 认证或私有入口上的gateway.auth.modenone存在x-openclaw-scopes时予以尊重缺失时回退到默认操作员 scope 集。仅当调用方显式收窄 scopes 且省略operator.admin时才失去 owner 语义。owner 级控制如x-openclaw-model要求operator.admin。相关文档Operator scopes、Security、Remote access。认证方式复用 Gateway 认证配置该端点直接使用 Gateway 的认证配置trusted-proxy 模式的细节见 Trusted proxy auth模式认证方式gateway.auth.modetokenAuthorization: Bearer token。通过gateway.auth.token或OPENCLAW_GATEWAY_TOKEN设置。gateway.auth.modepasswordAuthorization: Bearer password。通过gateway.auth.password或OPENCLAW_GATEWAY_PASSWORD设置。gateway.auth.modetrusted-proxy通过配置的身份感知代理路由由代理注入所需身份头。同主机 loopback 代理需要显式设置gateway.auth.trustedProxy.allowLoopback true。gateway.auth.modenone无需认证头仅限私有入口。补充要点在trusted-proxyGateway 上绕过代理的同主机调用方可以直接回退使用gateway.auth.password/OPENCLAW_GATEWAY_PASSWORD而一旦出现任何Forwarded、X-Forwarded-*或X-Real-IP头证据请求会保持在 trusted-proxy 路径上。如果配置了gateway.auth.rateLimit且认证失败次数过多端点返回429并携带Retry-After头。什么时候用这个端点什么时候不该用推荐使用你的集成只是同一个 Gateway 的另一个 operator/client 表面时优先于新增一个内置 channel。原生移动客户端直连远程 Gateway优先使用 WebChat 或 Gateway Protocol 的 paired-device bootstrap / device-token 流程让设备无需共享 HTTP token/password。接入外部消息网络有独立用户、房间、webhook 投递或出站传输应构建 channel 插件参见 Building plugins。Agent-first 模型契约model不是提供商模型 IDOpenClaw 把 OpenAI 的model字段当作Agent 目标agent target而不是原始提供商模型 ID。这是理解本端点最关键的概念差异model值路由到openclaw已配置的默认 Agentopenclaw/default已配置的默认 Agent稳定别名即使真实默认 Agent ID 在不同环境间变化也可安全硬编码openclaw/agentId或openclaw:agentId指定 Agentagent:agentId指定 Agent兼容别名可选请求头Header效果x-openclaw-model: provider/model-or-bare-id覆盖所选 Agent 的后端模型。共享密钥 bearer 调用方可直接使用身份承载调用方trusted-proxy或私有 no-auth 入口且带x-openclaw-scopes需要operator.admin否则返回403 missing scope: operator.admin。x-openclaw-agent-id: agentIdAgent 选择的兼容性覆盖。x-openclaw-session-key: sessionKey显式会话路由。若使用保留内部命名空间subagent:、cron:、acp:返回400 invalid_request_error。x-openclaw-message-channel: channel设置合成入口 channel 上下文供 channel-aware 提示/策略使用。从源码看src/gateway/openai-http.ts请求上下文解析由resolveGatewayRequestContext完成其中sessionPrefix: openai、defaultMessageChannel: webchat并启用useMessageChannelHeader——也就是说请求头的解析、会话键前缀和默认 message channel 都在这一层落地模型覆盖则由resolveOpenAiCompatModelOverride在运行前解析src/gateway/openai-http.ts。/v1/models与/v1/embeddings的契约/v1/models列出顶层 Agent 目标openclaw、openclaw/default、openclaw/agentId不是后端提供商模型也不包含子 Agentsub-agents 属于内部执行拓扑。如果省略x-openclaw-model所选 Agent 使用其正常配置的模型运行。/v1/embeddings使用同样的 Agent 目标modelID。发送x-openclaw-model共享密钥调用方或带operator.admin的身份承载调用方可指定具体嵌入模型否则请求使用所选 Agent 的常规嵌入设置。/v1/embeddings支持input为字符串或字符串数组对支持的模型正整数dimensions可请求输出向量大小它会覆盖所选 Agent 的memory.search.outputDimensionality配置即使禁用 memory search 也生效省略则保持配置或提供商默认大小。会话行为默认无状态user派生稳定会话默认情况下端点是每请求无状态的每次调用都会生成一个新的 session key。若请求包含 OpenAI 的user字符串Gateway 会从中派生稳定会话键使重复调用可以共享同一 Agent 会话。自定义应用中同一个会话线程请复用相同的user值避免使用账户级标识符除非你确实希望多个会话/设备共享一个 OpenClaw 会话。仅当你需要在多个客户端/线程之间显式控制路由时才使用x-openclaw-session-key并确保使用应用自有键、避开上述保留命名空间。显式 incognito 会话续接权限收紧使用x-openclaw-session-key显式选择或续接一个 incognito 会话需要有效的operator.admin权限。该规则跟随权限而非入口trusted-proxy 调用方若没有 owner/admin 权限会被拒绝私有gateway.auth.modenone调用方若显式把x-openclaw-scopes收窄到低于 admin例如只给operator.write同样被拒绝。以上两种情况均返回 HTTP403与forbidden错误。无 profile 的私有 no-auth 调用方在此路径上得到missing scope: operator.admin对 profile 支持的调用方响应会隐藏私有目标错误形状如下sessionKey为请求的覆盖值{ error: { message: Incognito session \sessionKey\ was not found., type: forbidden } }Owner/admin 调用方可继续显式续接 incognito 会话。私有 no-auth 请求若不带x-openclaw-scopes会获得默认操作员 scopes含operator.admin因此被视为 owner/admin。保留内部命名空间覆盖subagent:、cron:、acp:属于另一类校验失败仍返回 HTTP400与invalid_request_error。请求限制与图片策略端点内置限制请求体 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, }, }, }, }, }, }图片设置默认值Key默认值images.allowUrlfalse除非启用否则拒绝 URL 来源的image_url部件images.maxBytes每张图片 10MBimages.maxRedirects3images.timeoutMs10sHEIC/HEIF 的image_url来源会被接受并在交给提供商前通过共享的 OpenClaw 图片处理器Rastermill归一化为 JPEG需要外部编解码器支持的格式会回退到系统转换器sips、ImageMagick、GraphicsMagick 或 ffmpeg。安全提示对主机名加白名单不会绕过私有/内网 IP 屏蔽。对于暴露在公网的 Gateway除应用层防护外还应施加网络出口egress控制参见 Security。Chat 工具契约function calling 子集/v1/chat/completions支持与常见 OpenAI Chat 客户端兼容的 function-tool 子集。支持的请求字段字段说明tools{ type: function, function: { ... } }数组tool_choiceauto、none、required或{ type: function, function: { name: ... } }messages[*].role: tool后续轮次messages[*].tool_call_id把工具结果绑定回先前的工具调用max_completion_tokens正整数安全整数每次调用的总完成 token 上限含推理 token。当前字段名两个字段都非空时使用它。Null 或省略则不设置。max_tokens正整数安全整数遗留别名。当max_completion_tokens非空时仍会校验但优先级被忽略。Null 或省略则不设置。temperature数值 0-2best-effort转发给上游提供商。越界返回400 invalid_request_error。top_p数值 0-1best-effort。越界返回400 invalid_request_error。frequency_penalty数值 -2.0 到 2.0best-effort。越界返回400 invalid_request_error。presence_penalty数值 -2.0 到 2.0best-effort。越界返回400 invalid_request_error。seed整数best-effort。非整数返回400 invalid_request_error。stop字符串或最多 4 个字符串的数组best-effort。超过 4 个序列或包含非字符串/空条目时返回400 invalid_request_error。源码中可以看到这些校验的具体实现src/gateway/openai-http.tsresolveStopSequences严格限制最多 4 条且条目必须为非空字符串resolveChatCompletionTokenCap通过asPositiveSafeInteger保证正安全整数随后validateOpenAiSamplingParams统一校验采样参数范围。所有采样与 token 上限字段走同一条 Agent stream-param 通道best-effort 转发Token 上限线字段名由提供商传输层决定——OpenAI 系端点用max_completion_tokens只接受旧名称的提供商Mistral、Chutes用max_tokens。stop映射到传输层的 stop 字段Chat Completions 后端用stopAnthropic 用stop_sequences。OpenAI Responses API 没有 stop 参数因此 Responses 支撑的模型不应用stop。基于 ChatGPT 的 Codex Responses 后端使用固定服务端采样会剥离temperature/top_p连同max_output_tokens、metadata、prompt_cache_retention、service_tier后再把请求送达该后端。不支持的变体以下情况返回400 invalid_request_error非数组tools、非 function 的工具条目或缺少tool.function.nametool_choice变体如allowed_tools和customtool_choice.function.name值与已提供的工具不匹配。对于tool_choice: required和 function 固定的tool_choice端点会收窄暴露给客户端的 function-tool 集、指示运行时在响应前先调用客户端工具并在 Agent 响应中没有匹配的结构化客户端工具调用时报错。注意这作用于调用方提供的 HTTPtools列表而非 OpenClaw 的每一个内部 Agent 工具。非流式工具响应形状Agent 调用工具时响应使用choices[0].finish_reason tool_callschoices[0].message.tool_calls[]条目包含id、type: function、function.name、function.argumentsJSON 字符串工具调用前的助手评论性文本位于choices[0].message.content可能为空源码中src/gateway/openai-http.tsresolveStopReasonAndPendingToolCalls从运行 meta 中提取stopReason与pendingToolCalls工具参数统一序列化为 JSON 字符串随后按上述形状组装chat.completion响应。一个值得注意的实现细节tool_choice约束在运行之后通过结构化pendingToolCalls强制执行而不是相信模型口头说调用了工具——约束未满足时返回 HTTP502、type: api_errorsrc/gateway/openai-http.ts这在源码注释中被明确解释为“tool_choiceis an HTTP client-tool contract. The provider may still ignore the prompt, so enforce after the run”。流式工具响应形状stream: true时工具调用以增量 SSE 块到达先是初始的 assistant role delta然后是可选助手评论 delta接着一个或多个携带工具身份与参数片段的delta.tool_calls块最后是携带finish_reason: tool_calls的收尾块与data: [DONE]。对 required 或 function 固定的 tool_choice评论性文本会暂缓直到匹配调用被确认。当运行返回最终确定的文本时流使用该文本而非临时 delta。如果stream_options.include_usagetrue会在[DONE]前发出一个 trailing usage 块。工具后续循环tool follow-up loop收到tool_calls后执行请求的函数并发送一个包含先前 assistant tool-call 消息 一个或多个带匹配tool_call_id的role: tool消息的后续请求从而继续同一 Agent 推理循环得到最终答案。如果工具无文本输出仍需用content: 或空文本部件数组包含其结果。空结果完成调用省略结果则不会。遗留的role: function结果可用content: null携带其函数name。流式SSE行为流式会保留来自不同 assistant 消息的重复内容。如果某个修正无法通过追加到已发送文本的方式表达流会报告错误而不是以不一致内容完成。设置stream: true即可接收 Server-Sent EventsContent-Type: text/event-stream每个事件行为data: json流以data: [DONE]结束失败语义Agent 运行失败包括整个 Agent 超时返回错误而非成功完成流式失败先发出error对象再发[DONE]此时部分内容可能已到达客户端。超时设置遵循 agent loop。HTTP 客户端断开会取消正在进行的源 URL 下载和 Agent 运行若取消发生在准备输入阶段Gateway 会释放该下载且不启动另一个输入下载或 Agent 运行。该行为对流式与非流式请求均适用。源码中流式实现的几个关键点src/gateway/openai-http.ts进入流式路径后先setSseHeaders(res)收尾阶段用resolveAssistantTextCompletion比较最终文本与已流式文本若最终文本不以已流式文本开头即无法用 append-only 方式表达则finishStreamWithError返回api_error工具调用以writeAssistantToolCallsIncrementalChunks增量写出正常收尾时writeAssistantFinishChunk带finish_reason工具场景为tool_calls。Open WebUI 快速接入Base URLhttp://127.0.0.1:18789/v1Docker on macOS Base URLhttp://host.docker.internal:18789/v1API key你的 Gateway bearer tokenModelopenclaw/default预期行为GET /v1/models列出openclaw/defaultOpen WebUI 将其作为聊天模型 ID。要为指定后端提供商/模型运行请设置 Agent 的常规默认模型或发送x-openclaw-model共享密钥调用方或带operator.admin的身份承载调用方。快速冒烟测试curl -sS http://127.0.0.1:18789/v1/models \ -H Authorization: Bearer YOUR_TOKEN如果返回openclaw/default大多数 Open WebUI 环境即可用相同 Base URL 和 token 连接。完整示例单应用会话的稳定会话同一对话线程复用相同的user值即可延续同一 Agent 会话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}] }非流式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}] }流式-N关闭 curl 缓冲并演示x-openclaw-model覆盖后端模型、openclaw/research指定 Agentcurl -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获取单个模型注意 Agent ID 中的/需 URL 编码为%2Fcurl -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] }底层实现一次请求的完整调用链理解端点如何落到普通 Agent run 的调用链能帮你更准确地预估行为均基于 src/gateway/openai-http.ts 的源码结构认证与授权handleOpenAiHttpRequest通过handleGatewayPostJsonEndpoint进入按上文矩阵解析 scopesresolveOpenAiCompatibleHttpOperatorScopes随后authorizeOpenAiCompatibleHttpModelOverride校验模型覆盖权限resolveOpenAiCompatibleHttpSenderIsOwner判定 sender 是否 owner。请求解析与校验parseGatewayJsonRequest用OpenAiChatCompletionRequestSchema校验 JSONtoken 上限、采样参数、response_format、stop依次解析校验任何失败即返回400 invalid_request_error。上下文解析resolveGatewayRequestContext解析agentId、sessionKey前缀openai与messageChannel默认webchatauthorizeGatewaySessionCreation与authorizeOpenAiCompatibleHttpSession分别校验会话创建与 incognito 续接权限后者对应文档中的403 forbidden语义。工具契约组装extractClientToolsFromChatRequest提取客户端函数工具applyToolChoice把tool_choice转成运行时约束required/固定函数时收窄工具集并注入 extra system prompt。运行执行buildAgentCommandInput组装 prompt、图片、客户端工具、模型覆盖、streamParams 等最终经agentCommandFromGatewayIngress以 Gateway ingress 的普通 Agent run 方式执行——这正是文档「同一 codepath」论断的代码落点。响应整形非流式按stop/length/tool_calls三种 finish_reason 整形为chat.completion流式按 SSE 增量块输出收尾校验 append-only 一致性。该端点的测试覆盖见 src/gateway/openai-http.test.ts 与 src/gateway/openai-compatible-http.test-helpers.ts需要深入边界行为如tool_choice约束、流式一致性、incognito 权限时可以继续翻阅。小结OpenAI 兼容 HTTP 端点是 OpenClaw Gateway 对外开放能力中最轻量的一层它不引入新的消息网络抽象而是把「任何会讲 OpenAI 协议的工具」直接映射到你的 Agent 拓扑上。使用时的三个核心心法按操作员入口对待安全边界仅私有网络暴露、把model当作 Agent 目标而非提供商模型、用user或x-openclaw-session-key显式管理会话路由。把握住这三点你就能用 Open WebUI、自定义 SDK 或任意 OpenAI 兼容客户端安全稳定地驱动 OpenClaw Agent。RelatedConfiguration referenceOperator scopesOpenAI【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考