Claude Code 通信机制逆向分析

使用 Proxyman 抓包工具对 Claude Code 进行 API 通信抓包，基于请求/响应数据进行的完整逆向分析。

---

一、背景

1.1 什么是 Claude Code

Claude Code 是 Anthropic 官方推出的命令行编程助手。用户在终端中以自然语言描述需求，Claude Code 能够：

• 读写本地文件
• 执行 Shell 命令
• 搜索代码库
• 查阅网络信息
• 多代理并行协作

这些能力背后，是 Claude Code 与 Anthropic API 之间的一系列结构化通信。

1.2 分析目标

本文的核心目标是搞清楚 Claude Code 到底是如何工作的：

问题	目标
Claude Code 向 API 发送了什么？	拆解请求体的完整结构
API 返回了什么？	解析 SSE 流式响应的格式
AI 怎么"动手"？	理解工具调用（tool_use）机制
多轮对话如何衔接？	分析对话历史的维护方式
怎么省成本？	研究缓存策略和模型选择

---

二、分析方法

2.1 工具选择：Proxyman

Proxyman 是一款 HTTPS 抓包工具，支持：

• 解密 HTTPS 流量
• 查看请求/响应的完整 body
• 过滤特定域名或进程
• 导出数据供离线分析

2.2 抓包配置

┌─────────────┐ ┌─────────────┐ ┌──────────────────┐
│ Claude Code │ ──→ │ Proxyman │ ──→ │ Anthropic API │
│ (终端) │ │ (MITM 代理) │ │ (api.anthropic) │
│ │ ←── │ │ ←── │ │
└─────────────┘ └─────────────┘ └──────────────────┘
|------|------|
| 1 | 启动 Proxyman，启用 SSL Proxying |
| 2 | 安装并信任 Proxyman 的 CA 证书 |
| 3 | 在终端设置 HTTPS 代理指向 Proxyman（默认 `localhost:9090`） |
| 4 | 运行 Claude Code，正常发起对话任务 |
| 5 | 在 Proxyman 中过滤域名 |
| 6 | 导出请求/响应的完整 JSON body |

2.3 测试场景

我们设计了两类任务来触发不同的通信模式：

场景	用户输入	预期触发
文件操作	创建文本文件test.txt,内容为"创建文件测试"	Write 工具调用
网络搜索	查询今天天气信息 → 北京	WebSearch 工具调用 + 反问机制

两类任务覆盖了：纯文本回复、本地工具调用、远程搜索、内部子代理、多轮澄清对话。

---

三、产出文档

基于抓包数据的完整分析，产出以下 5 份文档：

#	文档	内容
1	背景介绍	本文档——分析背景、方法、工具说明
2	Claude Code API 请求结构解析	请求体顶层参数、messages/system/tools/metadata 各字段详解
3	Claude Code 工具列表	27 个原生工具的归类、参数、约束条件
4	创建文件任务分析	3 轮请求/响应的逐步拆解，token 消耗分析
5	天气查询任务分析	4 轮请求/响应的逐步拆解，内部搜索代理机制
6	AI Agent 运行机制浅谈	用通俗语言解释 Agent 的"思考→行动→观察"循环机制

---

四、核心发现摘要

4.1 请求结构

Claude Code 的每次 API 请求包含以下核心组件：

请求体
├── model 指定模型（Opus/Sonnet/Haiku）
├── messages 对话历史
├── system 顶层系统提示词（可分块+缓存控制）
├── tools 27 个工具定义（JSON Schema）
├── metadata 设备/会话标识
├── thinking 思考模式（adaptive/enabled/disabled）
└── stream 是否流式（始终为 true）

4.2 响应结构

API 返回 SSE 流，包含三种增量类型：

类型	作用	用户可见
thinking_delta	AI 内部思考过程	不可见
text_delta	给用户的文本回复	可见
input_json_delta	工具调用参数（JSON 片段）	内部使用

一次响应可包含多个 content_block，每个 block 有独立的类型（thinking / text / tool_use）。

4.3 工具调用机制

AI 不直接操作你的电脑。流程是：

AI 返回 tool_use 指令
→ Claude Code 本地运行时执行工具
→ 执行结果作为 tool_result 加入对话历史
→ 再次请求 AI 继续推理

4.4 缓存策略

• 系统提示词和工具定义（约 21K tokens）通过 cache_control: ephemeral 缓存
• 后续请求复用缓存，新增输入通常仅 100-900 tokens
• 大幅降低 API 费用

4.5 内部子代理

当需要执行 WebSearch 等任务时，Claude Code 启动独立精简子请求：

• 系统提示词压缩为一行
• 仅携带 1 个必要工具
• 子代理自行完成搜索+总结
• 结果透传回主对话

4.6 模型选择策略

场景	模型	原因
会话标题生成	Haiku 4.5	最快最便宜，关闭思考
编程任务	Opus 4.8	最强推理能力
搜索子代理	Opus 4.8	精简提示词控制成本

---

五、相关资源

• Claude Code 官方文档
• 完整抓包数据