导读： 很多开发者在折腾 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 结构优势：
- 独立的 System 字段：系统提示词不再混在消息列表里，而是在顶层。
- 严格的角色交替与显式绑定：它要求 user 和 assistant 严格交替，并且
tool_use和tool_result在 content 数组中是显式关联的。每个工具的调用和结果必须严丝合缝地对齐。
<!---->
// Anthropic 的工具调用结构（严格且支持多模态嵌套）
"content": [
{
"type": "text",
"text": "<thinking>我需要查看当前目录结构</thinking>"
},
{
"type": "tool_use",
"id": "toolu_01A09q90",
"name": "bash_command",
"input": { "command": "ls -la" }
}
]
- 实战踩坑点：这是构建高效代码助手的首选。它原生支持 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。建议在长周期任务中使用BatchAPI 或直接将文件内容内联。 - Tool Calling 需要手动对齐：Google 原生使用
function_declarations而非tool_calls，OpenClaw 在底层需要做字段名映射。如果你发现 Claude 配得好好的工具调用切到 Gemini 后完全不动，先检查这个映射层是否正确初始化。 - 上下文窗口虽大，但不是免费的：Gemini 的 100 万 token 上下文看着很美好，但超长上下文会带来显著的首 token 延迟和成本膨胀。建议结合
generateContent的topP/temperature参数做精细调优，别直接用默认值跑大文件。
- File API 有时效性：Google 的 File URI 并非永久有效，上传后超过一定时间（通常 48 小时）会过期。如果你的 Agent 在长任务中途需要复用之前上传的文件，可能会收到
三、 总结：如何为 OpenClaw 注入正确的灵魂？
在配置 openclaw.json 时，不要盲目跟风，请参考以下架构选型逻辑：
- 写代码、跑 CLI 自动化 👉 如果你追求极致的工具调用严谨性，且主力使用 Claude 系列模型，
anthropic-messagesAPI 格式是最契合的选型。它的 XML 标签解析和状态约束机制非常稳健。 - 重度依赖开源模型/追求高性价比 👉 采用
openai-completionsAPI 格式，对接 DeepSeek、Qwen 等。但要注意挑选那些能完整透传tool_calls和非标扩展字段的靠谱 API 渠道。 - 超大型代码库阅读/视频分析 👉 采用
google-generative-aiAPI 格式，利用其原生的 File API 优势应对巨量上下文。
请求 API 格式不是简单的填空题，它是大模型与现实世界交互的通信栈。选对了，你的 Agent 能调用本地工具、阅读代码库、监控邮件；选错了，它就是个贵一点的 Siri。
摸透了它，你才算真正掌握了这把勺子的用法。
