导读：很多开发者在折腾 AI Agent 时，把大部分精力花在了写 Prompt 上，却对底层的通信协议一知半解。在 OpenClaw 的配置中，指定 api 请求格式绝不是简单的"选个厂商"，而是在为你的 Agent 选择底层的数据总线和交互规范。

本文将从系统架构的视角，深入拆解当前大模型生态的四大核心 API 格式。从 JSON Payload 结构到 Tool Calling 握手逻辑，带你彻底看清大模型通信的工程真相。如果你在配置 OpenClaw，这篇文章能帮你绕开 90% 的坑。

一、 破除迷信：模型没有协议，只有 API 请求格式

在开始之前，我们需要理清一个架构常识：底层的 LLM 权重本身是不懂任何网络协议的。它只接受 Token 序列。

我们常说的配置某某协议，本质上是配置推理框架（如 vLLM）或云厂商提供的一层 API 网关（Gateway）。在 OpenClaw 中，api 参数实际上是在指定你要采用哪种模型的请求 API 格式。

这种格式规范的核心工作只有两件事，且必须精准无歧义：

1. **序列化 (Serialization)**：把 Agent 内部的上下文树、工具定义，按照特定结构的 JSON 序列化并发送。
2. **反序列化 (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" }  }]

1. 独立的 System 字段：系统提示词不再混在消息列表里，而是在顶层。
2. 严格的角色交替与显式绑定：它要求 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 URI（File API 先上传），这在处理长文本、超大 PDF 和视频帧时具有压倒性优势。

• 实战踩坑点：

• File API 有时效性：Google 的 File URI 并非永久有效，上传后超过一定时间（通常 48 小时）会过期。如果你的 Agent 在长任务中途需要复用之前上传的文件，可能会收到 404 File not found。建议在长周期任务中使用 Batch API 或直接将文件内容内联。
• Tool Calling 需要手动对齐：Google 原生使用 function_declarations 而非 tool_calls，OpenClaw 在底层需要做字段名映射。如果你发现 Claude 配得好好的工具调用切到 Gemini 后完全不动，先检查这个映射层是否正确初始化。
• 上下文窗口虽大，但不是免费的：Gemini 的 100 万 token 上下文看着很美好，但超长上下文会带来显著的首 token 延迟和成本膨胀。建议结合 generateContent 的 topP/temperature 参数做精细调优，别直接用默认值跑大文件。

三、 总结：如何为 OpenClaw 注入正确的灵魂？

在配置 openclaw.json 时，不要盲目跟风，请参考以下架构选型逻辑：

• 写代码、跑 CLI 自动化 👉 如果你追求极致的工具调用严谨性，且主力使用 Claude 系列模型，anthropic-messages API 格式是最契合的选型。它的 XML 标签解析和状态约束机制非常稳健。
• 重度依赖开源模型/追求高性价比 👉 采用 openai-completions API 格式，对接 DeepSeek、Qwen 等。但要注意挑选那些能完整透传 tool_calls 和非标扩展字段的靠谱 API 渠道。
• 超大型代码库阅读/视频分析 👉 采用 google-generative-ai API 格式，利用其原生的 File API 优势应对巨量上下文。

请求 API 格式不是简单的填空题，它是大模型与现实世界交互的通信栈。选对了，你的 Agent 能调用本地工具、阅读代码库、监控邮件；选错了，它就是个贵一点的 Siri。

摸透了它，你才算真正掌握了这把勺子的用法。