导读很多开发者在折腾 AI Agent 时把大部分精力花在了写 Prompt 上却对底层的通信协议一知半解。在 OpenClaw 的配置中指定api请求格式绝不是简单的选个厂商而是在为你的 Agent 选择底层的数据总线和交互规范。本文将从系统架构的视角深入拆解当前大模型生态的四大核心 API 格式。从 JSON Payload 结构到 Tool Calling 握手逻辑带你彻底看清大模型通信的工程真相。如果你在配置 OpenClaw这篇文章能帮你绕开 90% 的坑。一、 破除迷信模型没有协议只有 API 请求格式在开始之前我们需要理清一个架构常识底层的 LLM 权重本身是不懂任何网络协议的。它只接受 Token 序列。我们常说的配置某某协议本质上是配置推理框架如 vLLM或云厂商提供的一层 API 网关Gateway。在 OpenClaw 中api参数实际上是在指定你要采用哪种模型的请求 API 格式。这种格式规范的核心工作只有两件事且必须精准无歧义序列化 (Serialization)把 Agent 内部的上下文树、工具定义按照特定结构的 JSON 序列化并发送。反序列化 (Deserialization)解析大模型返回的流Stream——比如处理 OpenAI 碎石般的delta.tool_calls拼接或是 Anthropic 结构化的content_block_delta——将纯文本精准抽离出Reasoning思维链、Content回复和Tool Calls工具指令。打个比方序列化就是把你要说的话翻译成对方能听懂的语言发过去反序列化则是把对方的回复拆解成你真正想要的行动指令。中间如果翻译出错或者对方用了你听不懂的方言——你接到的就只剩一堆乱码。一旦 API 格式选错或者下游提供商对接口的实现标准被阉割你的 Agent 就会立刻丧失调用本地 CLI 工具的能力退化成一个只会聊天的残次品。二、 四大核心 API 格式Payload 深度对比目前最核心的请求 API 格式有以下四种。我们直接看底层的报文差异。1.openai-completions(事实上的行业标准)注意虽然 OpenClaw 中这个配置项的字面量叫openai-completions但它在底层实际指向的是标准的 Chat Completions API/v1/chat/completions而不是早期的非对话 Completions 接口。这不仅是 OpenAI 的规范更是 vLLM、DeepSeek、Qwen 等开源生态对外的通用基座。Payload 结构特点 它采用扁平的messages数组。对于工具调用的处理相对松散通过tool_calls数组挂载在 assistant 的消息体下。// OpenAI 工具调用返回的典型结构message:{role:assistant,content:null,tool_calls:[{id:call_abc123,type:function,function:{name:execute_shell,arguments:{\cmd\: \ls -la\}}}]}实战踩坑点 当你使用这种兼容格式对接 DeepSeek R1 这类带有显式思考过程的模型时需要注意 R1 的思维链通常不在标准的content里而是在一个非标扩展的reasoning_content字段中。如果 OpenClaw 的配置没有显式透传或记录该字段你可能在前端或调试日志中看不到完整的推导过程。2.anthropic-messages(复杂编程 Agent 的基石)为什么顶级的命令行工具如 Claude Code死死绑定 Anthropic 的 API 格式因为它在工程设计上极其严谨接口定义明确极大地降低了状态漂移的风险。URL 与鉴权追加/v1/messages强依赖特定的 Header如anthropic-version。Payload 结构优势// Anthropic 的工具调用结构严格且支持多模态嵌套content:[{type:text,text:thinking我需要查看当前目录结构/thinking},{type:tool_use,id:toolu_01A09q90,name:bash_command,input:{command:ls -la}}]独立的 System 字段系统提示词不再混在消息列表里而是在顶层。严格的角色交替与显式绑定它要求 user 和 assistant 严格交替并且tool_use和tool_result在 content 数组中是显式关联的。每个工具的调用和结果必须严丝合缝地对齐。实战踩坑点这是构建高效代码助手的首选。它原生支持 Prompt Caching提示词缓存机制。但这并非 API 自带的魔法而是需要你在 Payload 中通过cache_control显式标记哪些内容块该被缓存。如果不做这层精细控制每次重传几十个代码类的上下文会让成本原地爆炸。3.openai-responses(面向工具型 Agent 的次世代抽象)这是 2025 年后逐渐浮现的一条暗线。架构理念降维打击 它并不是简单地在服务端存历史记录而是 OpenAI 面向工具驱动型 Agent提供的新一代交互抽象。它将一次完整的任务执行包含多次工具调用、多模态流建模为连续的Items序列。实战场景相比于用 Chat API 手动编排并行工具调用Responses 格式更适合用来构建具备复杂操作流如 Computer Use 接管电脑的 Agent 应用是对整个交互生命周期的重构。4.google-generative-ai(原生多模态与巨量上下文)Gemini 的底层 API 格式是四者中最反直觉的一个——它完全抛弃了传统的messages[]数组思路转而用一种更接近文件管理系统的模型来处理对话。Payload 结构一切皆parts内容块即原子。// Google 的结构弱化角色强调内容块contents:[{role:user,parts:[{text:分析这个项目的架构},{fileData:{fileUri:[https://generativelanguage.googleapis.com/v1beta/files/abc](https://generativelanguage.googleapis.com/v1beta/files/abc),mimeType:application/pdf}}]}]注意这里没有content字段没有tool_calls数组所有内容都是parts。这意味着 OpenClaw 在接入 Google 格式时需要额外做一层格式转换层Adapter来对齐 Tool Calling 语义。实战场景当你需要 OpenClaw 分析一个包含几百个文件的庞大工程库时走 OpenAI 的 Base64 塞文本方式会导致 JSON 体积过大而直接被底层 HTTP 框架拒绝。Google 格式支持直接传递 File URIFile API 先上传这在处理长文本、超大 PDF 和视频帧时具有压倒性优势。实战踩坑点File API 有时效性Google 的 File URI 并非永久有效上传后超过一定时间通常 48 小时会过期。如果你的 Agent 在长任务中途需要复用之前上传的文件可能会收到404 File not found。建议在长周期任务中使用BatchAPI 或直接将文件内容内联。Tool Calling 需要手动对齐Google 原生使用function_declarations而非tool_callsOpenClaw 在底层需要做字段名映射。如果你发现 Claude 配得好好的工具调用切到 Gemini 后完全不动先检查这个映射层是否正确初始化。上下文窗口虽大但不是免费的Gemini 的 100 万 token 上下文看着很美好但超长上下文会带来显著的首 token 延迟和成本膨胀。建议结合generateContent的topP/temperature参数做精细调优别直接用默认值跑大文件。三、 总结如何为 OpenClaw 注入正确的灵魂在配置openclaw.json时不要盲目跟风请参考以下架构选型逻辑写代码、跑 CLI 自动化 如果你追求极致的工具调用严谨性且主力使用 Claude 系列模型anthropic-messagesAPI 格式是最契合的选型。它的 XML 标签解析和状态约束机制非常稳健。重度依赖开源模型/追求高性价比 采用openai-completionsAPI 格式对接 DeepSeek、Qwen 等。但要注意挑选那些能完整透传tool_calls和非标扩展字段的靠谱 API 渠道。超大型代码库阅读/视频分析 采用google-generative-aiAPI 格式利用其原生的 File API 优势应对巨量上下文。请求 API 格式不是简单的填空题它是大模型与现实世界交互的通信栈。选对了你的 Agent 能调用本地工具、阅读代码库、监控邮件选错了它就是个贵一点的 Siri。摸透了它你才算真正掌握了这把勺子的用法。