Claude Tap 本地追踪器
在本机捕获并审查 AI 编程助手的真实 API 调用与上下文。
- Star 数
- ★ 3.2k
- 最近更新
- 8 天前
- License
- MIT
- 主语言
- Python
- FA 评分
- 53/100 · 缺口较多
30 秒速览
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code · OpenAI API · Claude APIChatGPT（部分支持）
- 开始前需要
- 典型场景
- 使用 Claude Code 的开发者想核对某次行为实际收到的系统提示词、消息和工具定义。
- 主要局限
- 要求 Python 3.11+、命令行环境、网络访问，以及已安装并完成认证的目标客户端。
这个 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？
需要 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 或代理设置接入。
这个 Agent 有哪些优点和局限？
- 同时覆盖反向代理与前向代理模式，适配既支持自定义 base URL、又只能通过通用 HTTPS 代理接入的客户端。
- 将请求、响应、工具 schema、工具调用、流式重建结果和令牌用量放入本地单文件查看器，并提供相邻请求结构化 diff。
- 追踪默认保留在本机，不依赖托管仪表盘；记录前会自动脱敏常见认证请求头。
- 要求 Python 3.11+、命令行环境、网络访问，以及已安装并完成认证的目标客户端。
- 覆盖范围受客户端的代理或 base URL 支持限制；不同客户端需选用对应的
--tap-client和代理模式。 - 原始 SSE/WebSocket 事件默认不会持久化，事后若需要这些事件无法从普通追踪中补回。
- 部分 macOS 前向代理场景需要信任本地 CA；Antigravity 首次启动时可能要求解锁登录钥匙串。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|
| Claude Tap 本地追踪器 当前 | 53 · 缺口较多 | ★ 3.2k | 8 天前 | Python | Codex · Claude Code · OpenAI API · Claude API |
| ccxray | 73 · 存在缺口 | ★ 295 | 3 天前 | JavaScript | Claude Code · Claude API |
| OrcaReplay | 84 · 表现良好 | ★ 261 | 今天 | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| Agent Skills 技能库 | 67 · 存在缺口 | ★ 240 | 25 天前 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：项目作为本地代理，会拦截并记录API流量，但未明确说明权限最小化原则；用户确认方面，有--permission-mode等选项，但未明确要求用户确认；数据流透明度方面，README说明了代理模式和流量记录，但未详细说明数据流向；敏感数据处理方面，提到redact auth headers，但未详细说明；依赖安全方面，依赖版本固定，但未提供漏洞扫描证据；外部影响方面，会修改环境变量和信任CA，但未说明影响范围；回滚方面，未提及；来源归属方面，有作者信息，但未验证。扣分原因：权限最小化未明确，用户确认机制不清晰，数据流透明度不足，敏感数据处理细节缺失，依赖安全证据不足，外部影响未充分说明，回滚缺失，来源归属未验证。
证据显示：项目有CI测试，覆盖多个Python版本，但未提供测试结果；依赖可用性方面，依赖版本固定，但未提供可用性保证；失败消息方面，未提供具体错误处理信息。扣分原因：测试结果未提供，依赖可用性未验证，失败消息不明确。
证据显示：项目支持多种客户端，场景广泛；能力边界方面，README说明了支持的客户端和模式，但未明确限制；触发精度方面，有--tap-client等选项，但未详细说明；环境适配方面，支持多平台，但未详细说明。扣分原因：能力边界未明确，触发精度细节不足，环境适配细节不足。
证据显示：信息架构清晰，有README、docs等；安装说明详细；命名稳定，有版本号；示例和FAQ丰富；已知限制方面，未明确列出；许可证为MIT；版本变更日志存在；维护责任方面，有作者信息，但未明确维护计划。扣分原因：已知限制未明确，维护责任不明确。
证据显示：输出可用性方面，有trace viewer和HTML导出；边际价值方面，提供了独特的调试功能；成本效益方面，本地运行，无需托管。扣分原因：输出可用性细节不足，边际价值未量化，成本效益未详细说明。
证据显示：README中有截图和演示，但未提供可验证的测试结果；跨来源验证方面，未提供外部验证；事实与推断分离方面，未明确区分。扣分原因：声明可追溯性不足，跨来源验证缺失，事实与推断分离不明确。
- 源码中未见：回滚或恢复路径运行前先备份，或在 git 分支、快照上操作，确保改动可以撤销。
- 项目会拦截并记录API流量，可能包含敏感数据，需谨慎使用。
- 项目会修改环境变量和信任CA，可能影响系统安全，需在隔离环境中测试。
- 依赖版本固定，但未提供漏洞扫描证据，需定期检查依赖安全。
常见问题
它会把追踪上传到云端吗？
是否能查看 Codex 的 ChatGPT 订阅 OAuth 流量？
codex login，再运行 claude-tap --tap-client codex；默认会尽可能从认证状态自动判断目标地址。能否捕获所有流式原始事件？
--tap-store-stream-events；该选项默认关闭。需要付费 API Key 吗？
OPENAI_API_KEY 两种模式；其他客户端按其自身认证配置运行。