← 返回 Demo Gallery
claude-tap 研究
2026-06-01 · 使用层面分析 · AI Coding Agent 流量追踪工具
摘要： claude-tap 是一个本地代理和追踪查看器，用于拦截和检查 AI Coding Agent 的 API 流量。支持 Claude Code、Codex CLI、Gemini CLI、Cursor CLI、OpenCode、Kimi、Pi、Hermes、OpenClaw 等 11+ 个客户端。可以看到 system prompt、对话历史、工具定义、工具调用、流式响应、token 用量等真实数据，对于调试 AI 行为、理解上下文消耗、排查问题非常有价值。
github.com/liaohch3/claude-tap · Python 3.11+
本质： 本地代理 + 追踪查看器。启动一个反向或正向代理，拦截 AI Coding Agent 的 API 流量，记录每一次请求-响应，最后生成一个自包含的 HTML 查看器。
一、核心功能
👀 看到真实上下文 ：system prompt、messages、工具定义、工具调用、工具结果、流式响应重建、token 用量
🔎 调试行为 ：对比相邻请求，精确定位哪条 prompt、哪条消息、哪个工具或参数发生了变化
📦 可分享 ：每次运行写入本地 trace session，可导出为自包含 HTML 查看器，供审查或归档
🔒 本地优先 ：不需要托管 dashboard，常见 auth header 自动脱敏
🧩 跨客户端统一 ：一个工具搞定 11+ 个 AI Coding Agent
二、支持的客户端（11+）
客户端
典型用法
代理模式
Claude Code
Anthropic API 或兼容网关（DeepSeek / GLM）
Reverse
Codex CLI
OpenAI API Key 或 ChatGPT OAuth
Reverse
Kimi CLI
Kimi Code 或 Moonshot Open Platform
Reverse
Gemini CLI
Google OAuth / Code Assist
Forward
OpenCode
多提供商会话
Forward
Cursor CLI
Cursor Agent + 本地 transcript
Forward
Pi
多提供商（OpenAI Codex OAuth 等）
Forward
Hermes Agent
多提供商（Nous/OpenRouter/NVIDIA/GLM/Kimi 等）
Forward
Qoder CLI
多 Qoder endpoint
Forward
Antigravity CLI
Google/Antigravity endpoint
Forward
CodeBuddy CLI
腾讯 Copilot endpoint
Reverse
OpenClaw OpenClaw ACP / Gateway
有专门指南
三、两种代理模式
Reverse Proxy（反向代理）
改写客户端的 Base URL，指向本地代理
客户端必须支持自定义 Base URL（如 ANTHROPIC_BASE_URL 、OPENAI_BASE_URL ）
适用于：Claude Code、Codex、Kimi、CodeBuddy
开销低，直连感
Forward Proxy（正向代理）
注入 HTTPS_PROXY + 本地 CA 证书到子进程
客户端不需要支持 Base URL 改写，通过系统代理走流量
适用于：Gemini、OpenCode、Pi、Hermes、Cursor、Qoder、Antigravity
macOS 上可能需要信任 CA 到 login keychain
四、安装与使用
安装
uv tool install claude-tap
pip install claude-tap
claude-tap update
uv tool upgrade claude-tap
基本使用（Claude Code 默认）
claude-tap
claude-tap --tap-no-live
claude-tap -- --model claude-opus-4-6 --dangerously-skip-permissions
claude-tap -c
其他客户端
claude-tap --tap-client codex -- --model codex-mini-latest
claude-tap --tap-client gemini -- -p "hello"
claude-tap --tap-client kimi -- --thinking
claude-tap --tap-client cursor -- -p --trust --model auto "hello"
claude-tap --tap-client opencode
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"
查看与导出
claude-tap dashboard
claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html
claude-tap export < session-id> --format compact -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html
claude-tap --tap-output-dir ./my-traces --tap-max-traces 10
claude-tap --tap-no-launch --tap-port 8080
五、查看器功能
查看器是一个单文件自包含 HTML （零外部依赖），包含：
🔀 结构对比 ：对比连续请求，看到新增/删除的消息、system prompt 差异、字符级高亮
🔎 路径过滤 ：按 API endpoint 过滤（如只看 /v1/messages ）
📊 模型分组 ：侧边栏按模型分组，Claude 家族优先排序
💰 Token 用量 ：input / output / cache read / cache creation 拆分
🛠️ 工具检查器 ：可展开卡片，展示工具名、描述、参数 schema
🔍 全文搜索 ：跨消息、工具、prompt、响应搜索
🌗 暗黑模式 ：跟随系统偏好
📋 一键复制 ：请求 JSON 或 cURL 命令
⌨️ 键盘导航 ：j/k 或方向键
🌍 多语言 ：英/中/日/韩/法/阿/德/俄
🖼️ Iframe 嵌入 ：支持 query 参数控制显示元素（embed=1 、hideHeader=1 等）
六、与 OpenClaw 的关系
claude-tap 有专门的 OpenClaw 设置指南 （docs/guides/OPENCLAW_README.md ），说明作者明确考虑了与 OpenClaw 的集成。
价值 ：用 claude-tap 追踪 OpenClaw 的 ACP 子 agent 或 Gateway 流量，可以：
看到每个子 agent 实际发出的 system prompt 和工具调用
分析 token 消耗分布（哪个 agent 烧钱最多）
排查"为什么 AI 没调用这个工具"或"上下文怎么被压缩的"
导出 trace 供团队复盘或提交 bug 报告
七、使用场景
场景
为什么用 claude-tap
🔍 调试"AI 为什么这样回答"
看到完整的 system prompt + 对话历史 + 工具调用链，定位问题根源
💰 优化 token 费用
分析哪轮对话消耗最多 token，哪些工具调用是冗余的
🧪 对比不同模型行为
同一任务用 Claude / GPT / DeepSeek 跑一遍，对比 system prompt 和工具选择差异
📚 学习 prompt 工程
观察 Claude Code / Codex 等官方客户端如何构造 prompt，学习最佳实践
🐛 提交 bug 报告
导出 trace 作为复现证据，脱敏后分享给开发者
📊 团队审计
归档每次 AI 会话的完整流量，用于合规审查或知识沉淀
八、局限
需要 Python 3.11+，老环境可能不兼容
Forward proxy 模式在 macOS 上需要信任 CA 证书（首次使用有额外步骤）
某些客户端的认证方式可能无法自动检测，需要手动指定 --tap-target
只能拦截 HTTP/HTTPS 流量，本地工具调用（如直接执行 shell 命令）不经过 API，无法追踪
实时查看器在远程 shell / CI 环境需要关闭（--tap-no-live ）
一句话总结
claude-tap 是 AI Coding Agent 的"黑匣子记录仪" 。它让你看到 AI 到底收到了什么 prompt、调用了什么工具、花了多少 token，而不是猜测。对于 Claude Code、OpenClaw 等重度用户，是调试和优化必备工具。
调研时间：2026-06-01 · 基于 github.com/liaohch3/claude-tap 公开资料 · 使用层面参考