liaohch3/claude-tap

claude‑tap – AI 编码代理的本地代理与跟踪查看器

它是什么

• 一个基于 Python 的命令行工具，位于您和 AI 编码助手（Claude Code、OpenAI Codex、Gemini、Grok、Kimi 等）之间，并记录代理发出的每个 HTTP/WebSocket 请求。
• 然后，它提供一个轻量级 Web UI，您可以在其中浏览捕获的跟踪：完整的请求/响应体、系统提示、工具定义、工具调用、流式块、令牌使用情况，以及一个突出显示连续轮次之间变化的差异视图。

为什么您可能需要它

• 调试 – 查看发送给模型的精确负载，发现缺失的上下文或配置错误的工具架构。
• 透明度 – 将所有跟踪保留在您的机器上；敏感标头会自动编辑。
• 共享 – 将运行导出为自包含的 HTML 文件，以便查看或存档。
• 统一工作流 – 一个包装器适用于数十种流行的编码代理 CLI（Claude Code、Codex CLI/App、Gemini CLI、Grok Build、Kimi、OpenCode、Pi、Hermes Agent、Cursor、Qoder、Antigravity、CodeBuddy 等）。

主要功能

功能	描述
实时查看器	启动一个本地 Web 服务器（默认），在代理运行时实时更新。
仅捕获模式	claude‑tap --tap-no-live 记录跟踪而不启动 UI，适用于 CI 或批处理作业。
差异模态框	两个相邻请求的结构化并排差异 – 显示哪个提示、消息或工具发生了变化。
流式重建	重新组装 SSE/WS 流式响应，以便您可以像阅读普通回复一样阅读最终输出。
令牌核算	显示从提供商的响应元数据中提取的每个请求的令牌使用情况。
导出	Export → HTML 将跟踪打包到单个文件中，可在任何地方打开。
代理模式	反向（充当提供商端点）或正向（注入 HTTPS_PROXY）以适应签名的 AWS Bedrock、Google Vertex 或其他网关。
自动检测	从环境变量或客户端配置（例如 ANTHROPIC_BASE_URL、OPENAI_API_KEY）检测正确的上游 URL。

典型工作流

# 安装（需要 Python 3.11+）
uv tool install claude-tap   # 或：pip install claude-tap

# 通过代理运行编码代理
claude-tap --tap-client codex          # 启动 Codex CLI 并记录流量
claude-tap --tap-client gemini -- -p "hello"   # Gemini CLI 示例

# 打开实时查看器（通常为 http://127.0.0.1:5173）
# 检查提示、工具调用、令牌使用情况，并比较轮次。

# 导出运行以供以后查看
# （UI 按钮 → 导出 → HTML）或使用 CLI 标志 `--export html`

支持的客户端（部分）

• Claude Code（Anthropic、Bedrock、DeepSeek、Vertex）
• OpenAI Codex CLI 和桌面应用
• Google Gemini CLI
• Grok Build CLI
• Kimi CLI / Kimi Code CLI
• OpenCode、MiMo Code、Pi（多提供商代理）
• Hermes Agent、Cursor CLI、Qoder CLI、Antigravity CLI、CodeBuddy CLI
• …以及任何其他尊重系统代理的工具。

生态系统

• Phistory – 一个配套项目，使用 claude‑tap 的仅捕获模式来存档版本化的系统提示快照并提供差异查看器。
• 文档网站：https://liaohch3.com/claude-tap/
• 特殊设置指南（DeepSeek、AWS Bedrock、Google Vertex）位于 docs/guides/。

许可证

• 根据 MIT 许可证开源（请参阅 LICENSE）。

---

底线：claude‑tap 为开发者提供了一种具体、本地的方式来观察和调试现代 AI 编码助手的精确 API 流量，将不透明的模型调用转变为可检查、可共享的工件。