Claude Tap 本地追踪器
在本机捕获并审查 AI 编程助手的真实 API 调用与上下文。
这个 Agent 能做什么，适合哪些场景？
claude-tap 是面向 AI 编程客户端的本地代理和调用追踪查看器。它启动反向或正向代理，并运行所选客户端，或在仅代理模式下等待外部客户端接入。每次请求—响应对或 WebSocket 会话会写入本地 trace 存储，结束后可生成零外部依赖的单文件 HTML 查看器，也可导出紧凑追踪包。查看器可检查系统提示词、消息、工具 schema、工具调用、流式响应、令牌用量和相邻请求之间的结构化差异。它明确支持 Claude Code、Codex CLI 与 Codex App，以及 Gemini CLI、Kimi、OpenCode、Pi、Cursor CLI 等多个客户端。
运行 claude-tap 时，程序为选定客户端启动 reverse 或 forward proxy；支持 base URL 的客户端会被指向反向代理，其他客户端通过代理和本地 CA 环境变量接入。它在流式传输期间转发 SSE 分块和 WebSocket 消息，并把请求—响应对或 WebSocket 会话记录到本地 trace。默认不保存原始 SSE/WebSocket 事件数组；如需在查看器或导出结果中保留，使用 --tap-store-stream-events。运行结束会生成自包含 HTML 查看器；claude-tap dashboard 可浏览已保存追踪，claude-tap export <session-id> -o trace.ctap.json 可导出紧凑包，随后可用 claude-tap export trace.ctap.json -o trace.html 渲染。
- 使用 Claude Code 的开发者想核对某次行为实际收到的系统提示词、消息和工具定义。
- 使用 Codex CLI 的团队要比较相邻请求，定位模型行为变化来自上下文、参数还是工具调用。
- 运行 OpenCode、Pi 或 Hermes 等多提供商客户端的工程师需要在同一个本地界面审查其 API 流量。
- 需要将一次本地调试会话导出为单文件 HTML 或紧凑追踪包，用于离线复盘或归档的开发者。
- 在 macOS 上测试 Codex App 后端请求的用户，希望通过前向代理捕获 HTTP 与 WebSocket 请求体。
这个 Agent 有哪些优点和局限？
- 同时覆盖反向代理与前向代理模式，适配既支持自定义 base URL、又只能通过通用 HTTPS 代理接入的客户端。
- 将请求、响应、工具 schema、工具调用、流式重建结果和令牌用量放入本地单文件查看器，并提供相邻请求结构化 diff。
- 追踪默认保留在本机，不依赖托管仪表盘；记录前会自动脱敏常见认证请求头。
- 要求 Python 3.11+、命令行环境、网络访问，以及已安装并完成认证的目标客户端。
- 覆盖范围受客户端的代理或 base URL 支持限制；不同客户端需选用对应的 `--tap-client` 和代理模式。
- 原始 SSE/WebSocket 事件默认不会持久化，事后若需要这些事件无法从普通追踪中补回。
- 部分 macOS 前向代理场景需要信任本地 CA；Antigravity 首次启动时可能要求解锁登录钥匙串。
如何安装或部署这个 Agent？
需要 Python 3.11+，并已安装且配置好要追踪的客户端。推荐安装：uv tool install claude-tap；或使用：pip install claude-tap。随后先按客户端自身流程完成认证；例如 Codex CLI 的 ChatGPT 订阅 OAuth 使用 codex login，API Key 模式则设置 OPENAI_API_KEY。
如何使用这个 Agent？
Claude Code 可直接运行 claude-tap。Codex CLI 运行 claude-tap --tap-client codex；Gemini CLI 示例为 claude-tap --tap-client gemini -- -p "hello"。实时查看器默认开启；脚本或 CI 环境可加 --tap-no-live。若只启动代理而不启动客户端，使用 claude-tap --tap-no-launch --tap-port 8080，再按对应客户端的 base URL 或代理设置接入。