调试 AI 编程助手的新方式:把 prompt、工具调用和 token 用量全部可视化

项目介绍

AI 编程工具越来越多，但调试体验仍然很粗糙。

你让 Claude Code、Codex CLI、Gemini CLI 或 Cursor CLI 修一个问题，Agent 可能会突然走偏、重复调用工具、上下文丢失，或者莫名其妙多花很多 token。表面上看，它只是终端里的一段对话；真正发生在 API 层的 system prompt、message、tool schema、tool call、streaming response、token usage，很多时候并不透明。

claude-tap 就是为这个痛点做的。

它是一个本地代理和 Trace Viewer。你用它启动 AI Coding CLI，它会在本地捕获真实 API 请求和响应，并生成可视化 trace。开发者可以逐轮查看上下文、工具定义、工具调用、流式输出、token 统计，还能比较相邻请求之间到底改了什么。

一句话：claude-tap 给 AI Coding Agent 装了一个“本地流量显微镜”。

核心功能

1. 看见真实上下文

claude-tap 最核心的能力，是把 Agent 发给模型的真实内容展示出来。包括 system prompt、对话历史、工具 schema、工具调用、工具结果、重建后的流式响应，以及 input / output / cache read / cache creation 等 token 用量。

这对调试 Agent 非常重要。很多时候问题不是模型“不聪明”，而是上下文里混入了错误信息，或者工具 schema 描述不清，或者上一轮结果被错误复用。没有 trace，只能猜；有了 trace，就能看证据。

2. 支持主流 AI Coding CLI

项目当前支持 Claude Code、Codex CLI、Gemini CLI、Kimi CLI、OpenCode、Pi、Hermes Agent、Cursor CLI、Qoder CLI、Antigravity CLI 和 CodeBuddy CLI。

这点很实用。现在开发者常常同时使用多个 Agent 工具，如果每个工具都要一套独立调试方式，成本很高。claude-tap 把它们统一到同一个 trace 工作流里。

3. 结构化 Diff 与本地 HTML Viewer

每次运行都会写入本地 trace，并可以导出成自包含 HTML。这个 Viewer 不依赖云端服务，支持结构化 diff、路径过滤、模型分组、全文搜索、工具检查器、暗色模式、键盘导航、一键复制请求 JSON 或 cURL 命令。

其中结构化 diff 尤其有价值：你可以对比相邻请求，看到新增/删除的消息、system prompt 差异、字符级变化。定位“到底是哪一轮开始跑偏”的时候，非常省时间。

4. 本地优先与脱敏

claude-tap 不要求把 trace 上传到托管平台。数据保存在本机，常见认证 header 会在记录前自动脱敏。

不过要注意：trace 本身仍可能包含 prompt、文件内容、工具结果、业务数据等敏感信息。它适合本地调试和受控分享，不适合随手公开上传。

技术原理与架构

claude-tap 的工作方式可以拆成六步：

启动代理 -> 启动客户端 -> 转发请求 -> 记录 trace -> 生成 Viewer -> 实时广播更新

它支持两类代理模式。

第一类是 reverse proxy。对于能配置 base URL 的客户端，claude-tap 会把客户端指向本地代理，再由本地代理转发到真实上游。例如 Claude Code、Codex、Kimi、CodeBuddy 等场景常用这种模式。

第二类是 forward proxy。对于会访问多个端点、或不能简单改 base URL 的客户端，claude-tap 会给子进程注入 HTTPS_PROXY 和本地 CA，让请求通过本地代理。例如 Gemini、OpenCode、Pi、Hermes、Cursor、Qoder、Antigravity 等默认使用 forward proxy。

在流式场景下，它会转发 SSE 和 WebSocket 消息，并记录请求响应对或 WebSocket 会话。原始 SSE / WebSocket event 数组默认不保存，如果确实需要保留，需要启动时加 --tap-store-stream-events。

从工程实现看，项目主要是 Python，核心依赖包括 aiohttp 和 cryptography。前端 Viewer 则由内置的 HTML、CSS、JavaScript 资源构成，最终可以导出为自包含页面。

安装部署

claude-tap 要求 Python 3.11+，并且本机已经安装你想追踪的客户端。

官方推荐用 uv 安装：

uv tool install claude-tap

也可以用 pip：

pip install claude-tap

升级方式：

claude-tap updateuv tool upgrade claude-tappip install --upgrade claude-tap

代码演示

示例 1：追踪 Claude Code

# 默认启动 Claude Code，并开启实时浏览器 Viewerclaude-tap# 透传 Claude Code 参数claude-tap -- --model claude-opus-4-6# 关闭实时 Viewer，适合脚本或远程 shellclaude-tap --tap-no-live

如果你在 VS Code 里使用 Claude Code 扩展，可以把 Claude Code: Claude Process Wrapper 设置为 claude-tap，这样扩展启动 Claude 进程时也会经过本地追踪。

示例 2：追踪 Codex CLI

# Codex CLI，自动识别 OAuth 或 API Key 模式claude-tap --tap-client codex# 指定模型并跳过权限确认claude-tap --tap-client codex -- --model codex-mini-latest --full-auto

Codex CLI 支持 ChatGPT 订阅 OAuth 和 OpenAI API Key 两种认证方式。claude-tap 会尽量根据本地认证状态自动识别上游目标。

示例 3：导出可分享 Viewer

# 浏览历史 traceclaude-tap dashboard# 从 JSONL 重新生成 HTML Viewerclaude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html# 导出 compact bundle，再渲染成 HTMLclaude-tap export <session-id> --format compact -o trace.ctap.jsonclaude-tap export trace.ctap.json -o trace.html

生成的 HTML 是自包含文件，适合团队内部 review、问题复盘或归档。

示例 4：只捕获 Prompt 快照

claude-tap --tap-export-prompt prompt.md -- -p "hello"

这是 0.1.102 之后加入的能力，适合自动化场景：只导出 prompt surface，同时在旁边写入 trace JSONL。

优势对比

和普通终端日志相比，claude-tap 的优势是完整。终端只告诉你 Agent “说了什么”，而 trace 能告诉你它“实际发了什么请求”。

和云端 observability 平台相比，它更轻量，也更适合本地开发。你不需要搭建服务或上传敏感上下文，直接在本机生成 Viewer。

和 Charles、mitmproxy 这类通用抓包工具相比，它更懂 AI Coding Agent。它不是只展示 HTTP 原文，而是把 messages、tools、token、streaming、diff、模型分组等 LLM 语义结构整理出来。

和单一客户端调试功能相比，它覆盖面更广。Claude Code、Codex、Gemini、Cursor、OpenCode 等工具都能纳入同一个追踪体系，适合多工具并用的开发者。

当然，它也不是所有人都需要。偶尔问几句 AI 的用户，用不上这么细的 trace；但如果你在做 Agent 调试、模型对比、prompt 工程、工具调用优化，或者要复盘一次复杂的 AI Coding 过程，claude-tap 的价值会很明显。

注意事项

第一，trace 可能包含敏感内容。虽然认证 header 会脱敏，但 prompt、工具结果、文件片段、业务上下文仍可能进入记录。导出 HTML 或 compact bundle 前要认真检查。

第二，forward proxy 模式涉及本地 CA。某些客户端，尤其是 macOS 上的 Antigravity，可能需要把本地 CA 信任到用户 login keychain。项目说明中强调不会使用 sudo 或写入 System keychain，但系统可能要求解锁登录钥匙串。

第三，AWS Bedrock 原生 SigV4 场景不能随意改 base URL，否则会破坏签名校验。claude-tap 对真实 AWS 域名会使用 forward proxy 捕获流量，这是一个很重要的实现细节。

总结

claude-tap 的价值可以概括为一句话：它把 AI Coding Agent 从“黑盒终端对话”，变成“可追踪、可对比、可复盘的本地 API 流程”。