主流大模型请求API格式对比与深度解析

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

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

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

别被“协议”这个词吓到，我们先理清一个架构常识：底层的 LLM 权重本身是不懂任何网络协议的。它只接受 Token 序列。你让它理解 HTTP、gRPC？那是天方夜谭。

咱们日常说的配置某某协议，本质上是在配置推理框架（比如 vLLM）或云厂商提供的一层 API 网关（Gateway）。在 OpenClaw 中，api 参数实际上是在指定你要采用哪种模型的请求 API 格式——说白了，就是告诉你的 Agent 该用什么“方言”跟大模型交流。

这套规范真正要解决的核心问题只有两件事，而且必须精准无歧义：

1. 序列化 (Serialization)：把 Agent 内部的上下文树、工具定义，按照特定结构的 JSON 打包好，发给大模型。
2. 反序列化 (Deserialization)：解析大模型返回的数据流——比如处理 OpenAI 那种一块块拼起来的 delta.tool_calls，或是 Anthropic 结构清晰的 content_block_delta——从纯文本里精准地抽取出 Reasoning（思维链）、Content（回复）和 Tool Calls（工具指令）。

打个比方：序列化就是把你要说的话“翻译成对方能听懂的语言”发过去，反序列化则是把对方的回复“拆解成你真正想要的行动指令”。中间如果翻译出错，或者对方用了你听不懂的方言——你接到的就只剩一堆乱码，Agent 直接就懵了。

一旦 API 格式选错，或者下游提供商对接口的实现标准被“阉割”了一部分，你的 Agent 会立刻丧失调用本地 CLI 工具的能力，退化成一个只会聊天的残次品。这事儿，可比你写Prompt重要多了。

二、 四大核心 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": "我需要查看当前目录结构"
    },
    {
      "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 应用，是对整个交互生命周期的重构。如果你的 Agent 要处理鼠标点击、键盘输入这种连续动作，选它准没错。

4. google-generative-ai (原生多模态与巨量上下文)

Gemini 的底层 API 格式，是四者中最“反直觉”的一个——它完全抛弃了传统的 messages[] 数组思路，转而用一种更接近“文件管理系统”的模型来处理对话。一开始用会觉得很不习惯，但习惯了就会发现它在处理复杂内容时的强大之处。

• Payload 结构：一切皆 parts，内容块即原子。没有传统的 content 字段，也没有 tool_calls 数组：

  // Google 的结构：弱化角色，强调内容块
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "分析这个项目的架构"},
      {"fileData": {"fileUri": "https://...", "mimeType": "application/pdf"}}
    ]
  }]

  这意味着 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 和非标扩展字段（比如 reasoning_content）的靠谱 API 渠道，别用那些阉割版。
• 超大型代码库阅读/视频分析? 采用 google-generative-ai API 格式，利用其原生的 File API 优势应对巨量上下文，你会发现世界瞬间清净了。

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

摸透了它，你才算真正掌握了这把勺子——不，这把大模型的“万能钥匙”该怎么用。