Claude-TAP 使用分析报告

unique2026-06-17 13:05

一、Claude-TAP 概述

1.1 什么是 Claude-TAP？

Claude-TAP 是一个开源的本地代理（Proxy）和 Trace 查看器 ，专为 AI 编程代理（Coding Agent）设计。它通过在 AI 客户端和 API 上游之间插入一层透明代理，拦截、记录并可视化所有 API 请求和响应流量。

用一句话概括：它是 AI Agent 领域的 Wireshark。

  • 作者：liaohch3
  • 许可证：MIT
  • 语言/运行时：Python 3.11+
  • 分发方式 ：通过 PyPI (pip install claude-tap 或 uv tool install claude-tap)
  • GitHub Stars：已破千

1.2 解决的核心问题

在传统 Web 开发中，我们有 Chrome DevTools、Fiddler、Charles 来调试 HTTP 流量。但在 AI Agent 开发中，当你想了解：

  • Claude Code 到底发了什么请求？
  • System Prompt 长什么样？
  • 工具定义和调用参数是什么？
  • 每次请求消耗了多少 Token？
  • 缓存有没有生效？
  • 一个月的 API 账单钱到底烧在哪了？

这些问题 Agent 自己不会告诉你。claude-tap 填补了这个空白。

1.3 支持的客户端（11 个）

客户端 API 类型 代理模式
Claude Code Anthropic API / Bedrock / DeepSeek 反向代理
Codex CLI OpenAI API / ChatGPT OAuth 反向代理
Gemini CLI Google OAuth / Code Assist 正向代理
Kimi CLI Kimi Code / Moonshot Platform 反向代理
OpenCode 多 Provider 正向代理
Pi 多 Provider（含 Codex OAuth） 正向代理
Hermes Agent 多 Provider（10+） 正向代理
Cursor CLI Cursor Agent 正向代理
Qoder CLI Qoder Agent 正向代理
Antigravity CLI Google Code Assist 正向代理
CodeBuddy CLI 腾讯 Copilot 反向代理

二、核心架构与工作原理

2.1 整体架构

复制代码 
你 → 运行 claude-tap → 启动 AI 客户端 → 请求先到本地代理 → 再转到真实 API → 响应原路返回
                                                    ↓
                                          同时写入 trace 文件（JSONL）
                                                    ↓
                                        结束后生成 HTML 查看器 / 实时 Live 模式

2.2 两种代理模式

反向代理（Reverse Proxy）------ "改写通讯录"

适用于支持自定义 base_url 的客户端（如 Claude Code、Codex CLI、Kimi CLI）。

  • claude-tap 启动本地监听服务（如 http://127.0.0.1:9123）
  • 通过改写环境变量（如 ANTHROPIC_BASE_URL），让客户端主动将请求发送到本地代理
  • 代理拦截并记录请求后，转发给真实上游 API
  • 响应原路返回给客户端
正向代理（Forward Proxy）------ "设立邮局中转站"

适用于不支持改写地址的客户端（如 Gemini CLI、Cursor CLI）。

  • 在客户端必经的"网络出口"设置拦截关卡
  • 配合 HTTPS/TLS 中间人证书（MITM）解密加密流量
  • 所有外发请求都经过本地代理记录后再转发

2.3 数据存储与安全

  • 所有记录以 JSONL 格式 保存在本地（trace_*.jsonl）
  • 敏感信息脱敏 ：Authorization、x-api-key 等鉴权头在写入前自动打码
  • 数据留在本机：无需云端服务，适合内网、合规要求高的场景
  • 流式响应几乎不拖慢：SSE、WebSocket 都是边收边转，代理只做记录

三、安装与快速上手

3.1 安装

bash 复制代码 
# 方式一：使用 uv（推荐）
uv tool install claude-tap

# 方式二：使用 pip
pip install claude-tap

# 升级
claude-tap update
# 或
pip install --upgrade claude-tap

前置条件：Python 3.11+ 及你要追踪的 AI 客户端。

3.2 基本使用

bash 复制代码 
# 默认追踪 Claude Code
claude-tap

# 追踪其他客户端
claude-tap --tap-client codex
claude-tap --tap-client gemini
claude-tap --tap-client kimi
claude-tap --tap-client cursor

# 透传参数给客户端（用 -- 分隔）
claude-tap -- --model claude-sonnet-4-20250514

3.3 实时查看模式（Live Mode）

bash 复制代码 
# 添加 --tap-live 参数，自动打开浏览器实时查看
claude-tap --tap-live

Agent 一边跑，你在浏览器里一边看，每个 API 调用进来，页面就实时刷新一条记录。

3.4 离线归档

每次运行结束，自动生成一个自包含的 HTML 文件。可以：

  • 离线用浏览器打开
  • 发给同事 review
  • 不需要安装任何东西

3.5 高级配置

bash 复制代码 
# 指定自定义上游 API（如 DeepSeek）
claude-tap --tap-target https://api.deepseek.com/anthropic

# 部署为共享代理服务
claude-tap --tap-host 0.0.0.0 --tap-port 80 \
    --tap-output-dir /data/llm-tap \
    --tap-live --tap-live-port 8080 \
    --tap-proxy-mode reverse --tap-target http://llm.ai \
    --tap-no-open --tap-no-launch \
    --tap-no-update-check --tap-client claude

四、核心功能详解

4.1 System Prompt 完整查看

claude-tap 能捕获并展示 AI Agent 发送给模型的完整 System Prompt，包括：

  • 基础系统指令
  • 用户自定义的 CLAUDE.md 内容
  • Skills 定义和说明
  • MCP Server 配置
  • 工具（Tools）的完整定义列表
  • 权限设置和上下文信息

4.2 对话历史追踪

  • 查看每一轮请求中的完整对话上下文
  • 相邻请求 Diff 对比：直观显示每次请求之间的变化，帮助理解 Agent 的上下文管理策略

4.3 工具调用分析

  • 查看 Agent 定义了哪些工具（tool definitions）
  • 检查每次工具调用的参数和返回结果
  • 分析 Agent 的工具选择策略

4.4 Token 用量分析

  • 详细分析每次请求的 Token 用量
  • 区分输入 Token、输出 Token 和缓存 Token
  • 帮助优化成本和排查缓存效率

4.5 流式响应重组

  • SSEReassembler 组件负责还原流式响应的完整上下文
  • 即使是流式 SSE/Chunked 传输，也能完整记录和回放

五、与 Charles / Fiddler 横向对比

5.1 工具定位对比

对比维度 Claude-TAP Charles Fiddler
定位 AI Agent API 流量专用抓包工具 通用 HTTP/HTTPS 调试代理 通用 HTTP/HTTPS 调试代理
目标用户 AI 编程工具开发者/使用者 Web 开发者、移动开发者 Web 开发者、安全测试人员
开源 是（MIT） 否（付费软件，$50） Fiddler Classic 免费 / Everywhere 付费
语言 Python Java .NET (C#)

5.2 功能对比

功能 Claude-TAP Charles Fiddler
HTTP/HTTPS 抓包 仅 AI API 流量 全部 HTTP(S) 流量 全部 HTTP(S) 流量
SSL/TLS 中间人解密 支持（自动处理） 支持（需安装根证书） 支持（需安装根证书）
SSE/流式响应处理 原生深度支持 + 重组还原 基本支持 基本支持
请求修改/断点 不支持（只读记录） 支持（Breakpoints） 支持（AutoResponder）
请求重放 不支持 支持（Repeat） 支持（Replay）
System Prompt 解析 原生支持、结构化展示 需手动从 JSON 中查找 需手动从 JSON 中查找
Token 用量统计 原生支持、自动计算 不支持 不支持
工具调用可视化 原生支持 不支持 不支持
Diff 对比 相邻请求自动 Diff 支持（手动对比） 支持（手动对比）
实时查看器 浏览器 Web UI（--tap-live） 独立桌面 GUI 独立桌面 GUI
离线报告 自动生成自包含 HTML 可导出 .chls 文件 可导出 .saz 文件
多客户端支持 11 个 AI 编程客户端 任意 HTTP 客户端 任意 HTTP 客户端
带宽限流模拟 不支持 支持 支持
DNS 欺骗/Map Local 不支持 支持 支持
移动设备抓包 不支持 支持 支持
WebSocket 调试 部分支持 支持 支持

5.3 使用场景对比

场景 推荐工具 原因
分析 Claude Code 的 System Prompt Claude-TAP 原生解析 AI 协议，结构化展示
排查 AI Agent 的 Token 消耗 Claude-TAP 自动统计 Token 用量和缓存命中率
调试 Web 应用 API 接口 Charles / Fiddler 通用 HTTP 调试，功能更全面
移动端 App 网络调试 Charles / Fiddler 支持设备代理和证书安装
修改/模拟 API 响应 Charles / Fiddler 支持断点、重写、Map Local 等
安全渗透测试 Fiddler 可自定义规则，扩展性强
AI Agent 开发与调优 Claude-TAP 专为 AI 场景设计，开箱即用
团队共享调试记录 Claude-TAP 自包含 HTML 报告，零依赖分享

5.4 核心差异总结

Claude-TAP 的独特优势：

  1. AI 语义理解：不只是看原始 HTTP 数据包，而是解析 AI 协议层面的语义（System Prompt、Tools、Token Usage）
  2. 零配置启动：一行命令完成代理设置和客户端启动，无需手动配置证书
  3. 11 客户端覆盖：自动适配不同客户端的认证和代理方式
  4. 报告即分享：自包含 HTML，对方不需要安装任何软件

Charles/Fiddler 的优势：

  1. 通用性更强：可调试任何 HTTP 流量，不限于 AI 场景
  2. 交互能力：支持修改请求、设置断点、模拟响应
  3. 功能更丰富：带宽模拟、DNS 欺骗、Map Local 等高级功能
  4. 生态更成熟：拥有更完善的插件体系和社区支持

六、实战示例：使用 Claude-TAP 分析 Skills 加载与调用过程

6.1 场景说明

本示例演示如何使用 claude-tap 捕获 Claude Code 加载和调用 Skills 的完整过程，帮助理解 Skills 在底层 API 层面是如何工作的。

6.2 步骤一：启动 claude-tap 实时监控

bash 复制代码 
# 安装 claude-tap（如果尚未安装）
pip install claude-tap

# 以实时模式启动，自动打开浏览器查看器
claude-tap --tap-live

执行后，claude-tap 会：

  1. 在本地启动代理服务器（默认 127.0.0.1:9123）
  2. 自动设置 ANTHROPIC_BASE_URL 指向本地代理
  3. 启动 Claude Code CLI
  4. 打开浏览器实时查看器

6.3 步骤二：在 Claude Code 中触发 Skill 调用

在 Claude Code 的交互界面中，输入一个会触发 Skill 的命令，例如：

复制代码 
/init

或者输入一条自然语言指令，触发已安装的 Skill：

复制代码 
帮我 review 一下当前分支的代码变更

6.4 步骤三：在 Trace 查看器中分析捕获的数据

打开浏览器中的 claude-tap 实时查看器，你会看到类似以下结构的 API 请求：

（A）第一个请求 ------ 包含 Skills 定义的 System Prompt

在请求的 system 字段中，你会看到 Claude Code 发送给模型的完整 System Prompt。其中与 Skills 相关的部分类似：

json 复制代码 
{
  "system": [
    {
      "type": "text",
      "text": "... 核心系统指令 ..."
    },
    {
      "type": "text",
      "text": "<system-reminder>\nThe following skills are available for use with the Skill tool:\n\n- init: Initialize a new CLAUDE.md file with codebase documentation\n- review: Review a pull request\n- security-review: Complete a security review...\n- a1: 集团内部研发产品统一命令行客户端...\n</system-reminder>"
    }
  ]
}

关键发现 ：Skills 是通过 <system-reminder> 标签注入到 System Prompt 中的，作为可用技能列表告知模型。

（B）模型响应 ------ 决定调用 Skill

模型在分析用户意图后，如果判断需要调用某个 Skill，会返回一个 tool_use 类型的响应：

json 复制代码 
{
  "type": "tool_use",
  "id": "toolu_01XYZ...",
  "name": "Skill",
  "input": {
    "skill": "review",
    "args": ""
  }
}

关键发现 ：Skill 的调用本质上是模型发起的一次 Tool Call，工具名称固定为 Skill，通过 skill 参数指定要调用的具体技能名。

（C）Skill 执行后 ------ 后续请求的上下文变化

使用 claude-tap 的 Diff 对比功能，比较 Skill 调用前后的两次请求，你会发现：

  1. 对话历史增长 ：包含了 Skill 的调用结果（tool_result）
  2. 新增的上下文：Skill 执行产生的输出被追加到对话中
  3. Token 用量变化：Skill 调用可能显著增加上下文长度
（D）Token 用量面板 ------ 分析 Skill 的成本影响

在 claude-tap 的 Token 面板中，你可以看到：

复制代码 
请求 #1（含 Skill 定义的 System Prompt）:
  - 输入 Token: ~15,000  （System Prompt 中 Skill 列表占比较大）
  - 缓存 Token: ~12,000  （首次之后 System Prompt 通常被缓存）
  - 输出 Token: ~200

请求 #2（Skill 执行后的后续请求）:
  - 输入 Token: ~18,000  （包含 Skill 执行结果）
  - 缓存 Token: ~15,000
  - 输出 Token: ~500

6.5 从 Trace 中提炼的 Skills 工作机制

通过 claude-tap 的抓包分析，我们可以完整还原 Skills 的工作流程：

复制代码 
┌──────────────────────────────────────────────────────┐
│  1. Claude Code 启动                                  │
│     ↓                                                 │
│  2. 扫描已安装的 Skills 列表                           │
│     (.claude/commands/ 目录和内置 skills)              │
│     ↓                                                 │
│  3. 将 Skills 列表注入 System Prompt                   │
│     (通过 <system-reminder> 标签)                      │
│     ↓                                                 │
│  4. 用户输入指令 (如 /review 或自然语言)                │
│     ↓                                                 │
│  5. 模型判断是否需要调用 Skill                          │
│     ↓                                                 │
│  6. 模型返回 tool_use 响应                              │
│     (name: "Skill", input: {skill: "review"})          │
│     ↓                                                 │
│  7. Claude Code 执行对应的 Skill 脚本/命令              │
│     ↓                                                 │
│  8. 执行结果作为 tool_result 追加到对话上下文            │
│     ↓                                                 │
│  9. 发送新请求让模型基于结果继续工作                     │
└──────────────────────────────────────────────────────┘

6.6 实用价值

通过 claude-tap 分析 Skills 加载调用，你可以：

  1. 理解 Skills 的底层实现：Skills 不是独立模块，而是通过 System Prompt 注入和 Tool Call 机制实现的
  2. 优化 Token 消耗：如果安装了大量 Skills，它们的描述会占用 System Prompt 的 Token 额度，可以考虑精简不常用的 Skills
  3. 调试 Skill 行为：当 Skill 调用结果不符合预期时，通过 Trace 查看传入参数和返回内容
  4. 分析缓存效率：观察 System Prompt（含 Skills 列表）是否被有效缓存

七、最佳实践与建议

7.1 日常使用建议

  1. 开发调试时 使用 --tap-live 实时模式，边开发边观察 Agent 行为
  2. 生产环境审计时使用默认模式，结束后分享 HTML 报告
  3. 排查 Token 消耗时重点关注 System Prompt 的大小和缓存命中率
  4. 优化 Agent 行为时使用 Diff 对比功能，观察上下文变化

7.2 与传统抓包工具的协作

  • Claude-TAP 专注于 AI Agent 语义层面的分析，是"看懂 AI 在想什么"
  • Charles/Fiddler 适用于底层网络调试，当你需要分析 TLS 握手、DNS 解析、连接复用等网络层问题时使用
  • 两者可以互补：先用 claude-tap 定位 AI 行为问题，再用 Charles/Fiddler 排查网络层面的问题

7.3 注意事项

  • claude-tap 仅记录流量，不修改请求/响应内容，对 Agent 行为完全透明
  • 虽然会自动脱敏 API Key，但生成的 Trace 文件仍可能包含对话的敏感内容，分享时需注意
  • 正向代理模式需要安装 MITM 证书，首次使用时注意信任设置

八、总结

维度 评价
易用性 极高 --- 一行命令启动，零配置
功能深度 高 --- AI 语义级别的流量分析
性能影响 极低 --- 透明代理，流式转发
安全性 好 --- 数据本地存储，自动脱敏
适用范围 11 个主流 AI 编程客户端
与传统工具互补性 强 --- 填补 AI Agent 可观测性空白

Claude-TAP 是一个精准定位的工具 --- 它不试图替代 Charles 或 Fiddler 的通用抓包能力，而是专注于 AI Agent API 流量的语义级可观测性。对于频繁使用 AI 编程代理的开发者来说，它是排查问题、优化成本、理解 Agent 行为的不可或缺的利器。

相关推荐
穿过生命散发芬芳1 小时前
现在CC Switch一开，Claude Code随便玩
ai编程
yuanyxh4 小时前
macOS 应用 - 纯对话生成
前端·macos·ai编程
葫芦和十三5 小时前
多模态融合｜是数据形态工程，不是 Prompt 工程
openai·agent·ai编程
码哥字节5 小时前
同事做 PPT 比你快 5 倍，不是因为他努力，是因为他用了这套工具流
ai编程
沉默王二5 小时前
面试官：RAG 不用向量数据库，用 MySQL 硬扛？我：100 万向量不是很轻松？
mysql·面试·ai编程
程序员老刘6 小时前
跨平台开发地图 | 2026年6月
flutter·ai编程·客户端
唐老板6 小时前
给 Claude 定规则：让它写出的代码像我们团队的人写的
ai编程
Avan_菜菜14 小时前
AI 能写代码了，为什么我反而开始要求它先写文档？
前端·github·ai编程
ServBay18 小时前
打通 AI 编程本地运维边界，利用 MCP 协议简化环境与服务管理
后端·ai编程·mcp
葫芦和十三19 小时前
渐进发现｜代码库不是文档库
langchain·agent·ai编程
热门推荐
012026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？022026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05GitHub 镜像站点062026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？07AI科技热点日报 | 2026年6月1日08Codex 下载安装指南：Windows 和 macOS 官方版下载09上线仅72小时被强制下架：Claude Fable 5 的短命10AI一周事件 · 2026-06-03 至 2026-06-09