claude-tap 是一款开源的本地代理和流量追踪查看工具,专为 AI 编程助手(AI Coding Agents)设计。它允许开发者拦截、检查和分析 AI 编码助手与 LLM API 之间的完整通信流量,包括系统提示词、对话历史、工具模式、工具调用、流式响应、Token 使用量以及请求差异对比。
在 AI 编码助手日益普及的今天,这些工具的行为犹如一个"黑盒"——开发者看到的是最终结果(代码补全、文件修改),但无法了解 Agent 的决策过程和内部状态。claude-tap 的出现彻底改变了这一局面,它提供了前所未有的透明度和可观测性,是 AI Agent 开发者和高级用户的必备利器。

claude-tap 的 Web 追踪查看界面,展示拦截的 Agent 会话列表、请求详情和 Token 统计
claude-tap 作为本地代理服务器运行在用户机器上,AI 编码工具通过它转发所有 LLM API 请求。与传统的网络抓包工具(如 Wireshark、mitmproxy)不同,claude-tap 深度理解 AI Agent 通信协议,能够自动解析和结构化展示 LLM API 交互内容。
claude-tap 能够捕获并展示以下关键数据:
Agent 与 LLM 之间的对话通常是流式的——Token 逐块生成、逐步修正。claude-tap 能够实时展示这一过程,开发者可以观察 Agent 的思考链条从"不确定"到"确定"的演进过程。
监控每次请求的 Token 消耗情况,包括输入 Token 数、输出 Token 数、总 Token 数以及对应的 API 成本估算。这对控制 AI 编码工具的运营成本至关重要。
对比不同请求之间的差异,理解 Agent 的决策演变。例如,当 Agent 连续两次调用同一个工具但传入了不同的参数时,差异对比功能可以高亮显示变化的部分,帮助开发者理解 Agent 为何调整策略。
兼容以下主流 AI 编码工具的 LLM API 通信:
| 工具名称 | 类型 | 支持状态 |
|---|---|---|
| Claude Code | CLI | ✅ 完整支持 |
| Codex CLI | CLI | ✅ 完整支持 |
| Gemini CLI | CLI | ✅ 完整支持 |
| Kimi CLI | CLI | ✅ 完整支持 |
| OpenCode | CLI | ✅ 完整支持 |
| Pi | CLI | ✅ 完整支持 |
| Hermes Agent | CLI | ✅ 完整支持 |
| Cursor CLI | CLI | ✅ 完整支持 |
| Qoder CLI | CLI | ✅ 完整支持 |
| Antigravity CLI | CLI | ✅ 完整支持 |
| CodeBuddy CLI | CLI | ✅ 完整支持 |
支持检测和记录通过本地代理(如 CC Switch)转发的流量。当用户通过环境变量将 LLM API 端点指向本地代理(如 ANTHROPIC_BASE_URL=http://localhost:8080),claude-tap 会自动检测该配置并记录上游流量,形成完整的通信链路追溯。
claude-tap 的核心机制是一个透明中间代理,运行在 AI 编码工具和 LLM API 之间。
localhost:PORT)HTTP/HTTPS 代理实现:
claude-tap 在本地启动一个 Node.js HTTP 服务器,支持 HTTP CONNECT 隧道方法进行 HTTPS 流量拦截。对于 HTTP 请求,直接解析明文内容;对于 HTTPS 请求,通过 MITM(中间人)技术解密流量——但与传统的 MITM 代理不同,claude-tap 不需要用户安装 CA 证书,因为 AI 工具的 HTTP 客户端通常支持自定义代理且信任操作系统证书链。
流式响应解析:
AI 编码工具与 LLM API 之间的通信通常使用 Server-Sent Events (SSE) 协议进行流式数据传输。claude-tap 会解析 SSE 事件流中的每个数据块,从中提取 Token 内容、暂停原因、工具调用请求等结构化信息。
请求/响应匹配:
由于 HTTP/1.1 的连接复用和流式响应的异步特性,claude-tap 需要精确地将响应与对应的请求匹配。它通过请求唯一的 X-Request-Id 头部或请求体中的 message_id 字段来实现精确配对。
| 要求 | 说明 |
|---|---|
| Node.js | v18.0.0 或更高版本 |
| 操作系统 | macOS、Linux、Windows(含 WSL2) |
| 磁盘空间 | ~50MB(用于工具自身及日志缓存) |
| 网络 | 需要能够正常访问目标 LLM API |
claude-tap 有多种安装方式:
# 方式一:全局安装(推荐)
npm install -g claude-tap
# 方式二:使用 npx 直接运行
npx claude-tap
# 方式三:从源码安装
git clone https://github.com/liaohch3/claude-tap.git
cd claude-tap
npm install
npm run build
npm link
安装完成后,运行以下命令启动 claude-tap:
# 启动 claude-tap(默认端口 8080)
claude-tap
# 指定端口启动
claude-tap --port 9090
# 指定日志级别
claude-tap --log-level debug
启动后,claude-tap 会在默认浏览器中自动打开追踪查看界面。
对于 Claude Code VS Code 扩展:
Cmd/Ctrl + ,)Claude Code: Claude Process Wrapperclaude-tap(Windows 上使用完整路径 claude-tap.exe)单次启动命令:
CLAUDE_CODE_WRAPPER=claude-tap code .
或使用环境变量在启动时绑定:
# Unix/macOS
CLAUDE_CODE_WRAPPER=claude-tap code /path/to/project
# Windows PowerShell
$env:CLAUDE_CODE_WRAPPER = "claude-tap.exe"
code /path/to/project
对于 Claude Code CLI:
# 设置 HTTP 代理
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
# 启动 Claude Code
claude
各工具的配置方式有所不同,下表总结了常见工具的配置方法:
| 工具 | 配置方式 | 关键参数 |
|---|---|---|
| Claude Code CLI | HTTP_PROXY 环境变量 |
http://127.0.0.1:PORT |
| Claude Code VS Code | claudeProcessWrapper 设置 |
设置为 claude-tap |
| Codex CLI | 启动参数 --proxy |
--proxy http://127.0.0.1:PORT |
| Gemini CLI | HTTPS_PROXY 环境变量 |
http://127.0.0.1:PORT |
| Kimi CLI | 配置文件 proxy 字段 |
同标准 HTTP 代理 |
| Cursor CLI | 启动参数或环境变量 | 使用 --proxy 标志 |
| OpenCode | 命令行参数 | --proxy=http://127.0.0.1:PORT |
如果通过 CC Switch 等代理转发工具将 Claude Code 指向本地 ANTHROPIC_BASE_URL,claude-tap 会自动检测该配置并记录上游流量:
# 启动 CC Switch 将 API 指向本地
ANTHROPIC_BASE_URL=http://localhost:8080/proxy claude
# claude-tap 会自动检测并记录
这种情况下,请求路径为:Claude Code → CC Switch → claude-tap → LLM API,claude-tap 能够识别并记录完整的请求链路。
claude-tap 的追踪查看界面按功能划分为多个区域,每个区域专注于特定的分析维度和深度。
主视图左侧是会话列表,按时间倒序排列。每个会话条目显示:
会话状态使用颜色编码:
点击任意请求,展开详细信息面板,包含以下 Tab:
1. System Prompt Tab
展示 Agent 的底层系统提示词,通常包含:
例如,Claude Code 的系统提示词可能包含:
You are Claude, an AI assistant created by Anthropic.
You are connected to the user's system via a code editing interface.
You can read, create, and modify files.
You should use the most appropriate tools for the task.
When in doubt, ask the user for clarification.
...
2. Messages Tab
展示完整的对话消息序列,分为用户消息和助手消息。每次工具调用前后追加相应的消息,形成完整的思维链(Chain of Thought)。
3. Tools Tab
展示 Agent 可调用的工具定义,以 JSON Schema 格式呈现。例如 Claude Code 的工具集包含:
| 工具 | 用途 | 关键参数 |
|---|---|---|
Read |
读取文件内容 | file_path |
Write |
写入/创建文件 | file_path, content |
Edit |
编辑文件(结构化 diff) | file_path, old_string, new_string |
Bash |
执行 Shell 命令 | command, timeout, description |
Glob |
文件搜索 | pattern |
Grep |
文本搜索 | pattern, path |
Dispatch |
子 Agent 派发 | task, context |
4. Tool Call Results Tab
展示每次工具调用的输入参数和输出结果,包含执行状态、耗时、错误信息等。
5. Stats Tab
展示详细的数据统计:
请求统计:
- 请求方法: POST
- 端点: /v1/messages
- 响应时间: 2.45s
- HTTP 状态: 200
Token 统计:
- 输入 Token: 12,847
- 输出 Token: 3,216
- 总 Token: 16,063
- 估算成本: $0.32
流式统计:
- 数据块数: 124
- 首次 Token TTFB: 0.82s
时间线视图以甘特图形式展示请求-响应流程,每个请求显示为一条时间条,长度与响应时间成比例。这有助于识别性能瓶颈——例如,当某个工具调用耗时异常时,时间条会显著变长。
选中相邻的两个请求,差异对比面板会用 diffs 格式高亮显示两者之间的变化:
差异对比功能特别适合以下场景:
问题:Claude Code 在处理某个 React 组件时,多次调用 Edit 工具却始终无法正确修改导入语句。
使用 claude-tap 分析:
import 语句的排序逻辑new_string,发现 Agent 在排序和修改之间来回切换根因:Agent 的修改操作和排序规则相互冲突,导致每次 Edit 后排序逻辑又把导入语句恢复原样。
解决方案:分两步操作——先完成所有修改,再在最后执行一次导入排序。
问题:团队自研的 Codex CLI 代理在处理大型文件时经常超出 Token 限制,导致请求失败。
使用 claude-tap 分析:
查看 claude-tap 的 Token 统计面板:
| 因素 | Token 消耗 | 占比 |
|---|---|---|
| 系统提示词 | 3,200 | 8% |
| 对话历史 | 28,500 | 71% |
| 当前文件内容 | 6,800 | 17% |
| 工具定义 | 1,500 | 4% |
| 总计 | 40,000 | 100% |
发现对话历史占据了 Token 消耗的 71%。通过查看时间线视图,发现 Agent 在每次工具调用后都会将完整的历史消息附加到下一次请求中。
优化方案:
优化后,每次请求的 Token 消耗从平均 40,000 降低到 15,000,API 成本降低约 62%。
通过 claude-tap 的统计面板,可以追踪项目全生命周期的 API 成本。
示例:开发一个中型 React 项目的 Token 成本跟踪
各阶段 Token 消耗及成本估算(以 Anthropic Claude 3.5 Sonnet $15/MTok 输入、$60/MTok 输出为例):
| 阶段 | 输入 Token | 输出 Token | 总计 | 估算成本 |
|---|---|---|---|---|
| 项目初始化 | 65,000 | 20,000 | 85,000 | $1.70 |
| 功能开发 | 240,000 | 80,000 | 320,000 | $6.40 |
| 代码审查 | 70,000 | 25,000 | 95,000 | $1.90 |
| Bug 修复 | 155,000 | 55,000 | 210,000 | $4.20 |
| 文档编写 | 30,000 | 15,000 | 45,000 | $0.90 |
| 项目总计 | 560,000 | 195,000 | 755,000 | $15.10 |
通过这类数据,团队可以:
在企业环境中,AI 编码工具可能被用于处理敏感代码库。claude-tap 可以充当安全审计工具:
自动化安全审计流程:
对于正在开发自定义 AI Agent 的团队,claude-tap 是最有效的调试工具之一:
| 开发阶段 | claude-tap 的用途 | 带来的价值 |
|---|---|---|
| 工具定义调试 | 验证工具 Schema 是否正确被 LLM 理解 | 减少因工具定义错误导致的无效调用 |
| 提示词工程 | 测试不同系统提示词对 Agent 行为的影响 | 快速迭代找到最优提示词 |
| Tracing 验证 | 检查 Agent 的思维链条是否合理 | 发现逻辑断裂和错误的推理路径 |
| 性能优化 | 识别响应延迟的瓶颈环节 | 优化工具调用策略,减少不必要的 LLM 往返 |
| 回归测试 | 对比 Agent 更新前后的行为差异 | 确保行为变更符合预期 |
1. Proxy Server(代理服务器模块)
基于 Node.js 内置 http 模块实现 HTTP/HTTPS 代理,支持 CONNECT 隧道、自动解析 Host 头。监听指定端口,接收 AI 工具的所有 HTTP 请求。
2. Packet Handler(数据包处理器)
对接收到的原始 HTTP 请求进行解包处理:
3. Parser Engine(解析引擎)
核心组件,负责将原始 HTTP 内容转化为结构化数据:
4. Data Store(数据存储)
使用内存级存储方案,提供快速读写能力:
5. WebSocket Server(实时推送模块)
建立 WebSocket/SSE 连接,将解析后的数据实时推送到 Web UI:
6. Web UI(追踪查看界面)
基于 React 或 Vue.js 构建的 Web 应用,提供交互式数据查看:
llm-interceptor 是另一款类似的工具,两者在定位和实现方式上有显著差异:
| 对比维度 | claude-tap | llm-interceptor |
|---|---|---|
| 定位 | 本地代理 + 追踪查看器 | MITM 代理 + 分析日志 |
| 拦截方式 | HTTP/HTTPS 透明代理 | MITM(中间人攻击) |
| 证书要求 | 无需安装证书 | 需要安装 CA 根证书 |
| 复杂度 | 低(即装即用) | 中(需额外配置步骤) |
| 支持的 LLM 工具 | 10+ 种(Claude Code、Codex CLI、Gemini CLI、Cursor CLI 等) | 主要支持 Claude Code、Open Code |
| 用户界面 | 内置 Web UI,可视化追踪查看器 | 命令行日志输出为主 |
| 分析深度 | 请求差异对比、时序分析、Token 统计 | 通信日志记录、文本分析 |
| 适用场景 | 日常开发调试、行为分析、成本追踪 | 安全审计、流量审计 |
| 实时性 | 实时流式追踪 | 请求完成后查看 |
| 持久化 | 可选 | 默认持久化到文件 |
| 社区活跃度 | 社区维护活跃,更新频繁 | 基本稳定维护 |
优先选择 claude-tap 的场景:
优先选择 llm-interceptor 的场景:
A: 影响非常小。claude-tap 作为本地代理运行,仅在内存中进行内容解析和存储,转发时只是增加了一次本地网络往返(通常 <1ms)。根据实测数据,引入 claude-tap 后,API 响应时间增加约 2-5%,在正常使用中几乎无法感知。
A: 基本配置要求 AI 工具指向 claude-tap 作为代理。但对于使用 VS Code 扩展的 Claude Code,可以通过 claude-tap wrapper 模式自动配置,无需手动设置环境变量。
A: 会记录通过它传递的所有 LLM API 请求内容,包括你可能发送给 AI 的敏感代码。所有数据存储在本地,不会上传到外部服务器。建议在涉及敏感项目时,确保本地存储安全,并在不需要时及时停止 claude-tap。
A: claude-tap 默认使用内存存储,数据量过大时会自动清理最早的会话。你可以通过参数控制存储上限:
# 限制最多保留 100 个会话
claude-tap --max-sessions 100
# 启用持久化到本地文件
claude-tap --persist /path/to/data
A: 有差异。不同 LLM 提供商(Anthropic、OpenAI、Google、Moonshot 等)的 API 格式各不相同。claude-tap 针对每种 API 格式实现了专门的解析器,目前支持 Anthropic Messages API、OpenAI Chat Completion API、Google Gemini API 等主流格式。
除了 llm-interceptor,市场上还有以下替代方案:
| 方案 | 类型 | 优点 | 缺点 |
|---|---|---|---|
| claude-tap | 本地代理+追踪查看器 | 易用、功能完整、多工具支持 | 不支持所有 LLM API 格式 |
| llm-interceptor | MITM 代理 | 安全审计能力强、日志持久化 | 需要安装证书、配置复杂 |
| mitmproxy | 通用 MITM 代理 | 功能强大、可编写 Python 脚本 | 无 AI 专用解析、学习曲线陡 |
| Wireshark | 网络抓包 | 底层协议分析、功能最全面 | 无法解析高级协议、数据量大 |
| LangSmith | 云端 Tracing | 云端管理、团队协作 | 非开源、数据上传到云端 |
| 自家实现 | 自定义 | 可完全定制 | 开发维护成本高 |
对于日常使用,推荐以下工作流:
# 终端 1:启动 claude-tap(可放在后台运行)
claude-tap --port 8080 --persist ~/claude-tap-data
# 启动后访问 http://localhost:PORT 查看追踪界面
# 终端 2:正常使用 AI 编码工具(已配置代理)
code /path/to/project
每当 Agent 执行操作时,你可以在浏览器中实时观察:
对于团队使用,可以将 claude-tap 集成到 CI/CD 流程中:
# .github/workflows/token-audit.yml
name: Token Usage Audit
on: [pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install claude-tap
run: npm install -g claude-tap
- name: Run agent with tracing
run: |
# 启动 claude-tap 在后台
claude-tap --port 8080 --persist ./trace-data &
sleep 2
# 执行 AI 编码任务
CLAUDE_CODE_WRAPPER=claude-tap claude --task "review this PR"
# 停止 claude-tap
kill %1
- name: Upload trace data
uses: actions/upload-artifact@v4
with:
name: trace-data
path: ./trace-data/
随着 AI 编码工具的快速发展,Agent 的行为将越来越复杂。claude-tap 这类可观测性工具将成为 AI Agent 开发栈中的标准组件。未来可能出现: