liaohch3/claude-tap

面向 AI coding agent 的本地代理 + trace viewer，拦截真实 API 流量并还原上下文、工具调用、流式响应和 token 使用。

2.98k stars | Python | MIT | 本地优先 | 2026

一句话定位

如果说 open-code-review 解决的是“代码改得对不对”，那 claude-tap 解决的是“Agent 当时到底看到了什么、发出了什么、为什么会这样做”。

它不是一个 Skill，也不是通用 MCP，而是一个直接卡在 coding agent 与上游模型 API 之间的本地观测层：既能做代理抓包，也能读本地 transcript / app session，把一次真实运行整理成可回放、可 diff、可导出的 trace 工件。

2026-08-07 补充：作者另有重写版 fork WEIFENG2333/claude-tap（PyPI 上的旧包不含此重写）。phistory 的采集链安装的就是该 fork：claude-tap run <client> --export-prompt ...，forward 模式（HTTPS_PROXY + 本地 CA MITM）拦截请求，capture-only 时返回合成响应、不调用真实模型提供商。

为什么值得关注

直接看真实上下文：system prompt、conversation history、tool schema、tool call、tool result、streaming response、usage 都能落到同一条 trace 里
不是托管观测平台：数据默认留在本机，常见认证头会在记录前脱敏
覆盖多种 harness：Claude Code、Codex CLI、Codex App、Gemini CLI、Kimi、OpenCode、openclaw、Pi、hermes-agent、Cursor CLI 等共用同一套观测方式
适合做 prompt / harness 逆向：比只看 transcript 更接近真实请求层，非常适合研究 agent-harness-anatomy 和 agent-skill-loading 这类问题

核心能力

1. 两类接入方式

代理模式：claude-tap 启动本地 reverse proxy / forward proxy，把 CLI 的真实 API 请求先接到本地再转发上游
旁路监听模式：对 Codex App、Cursor transcript 等本地会话目录做导入/监听，不强依赖所有客户端都走同一种 HTTP 代理链路

这使它同时覆盖“命令行代理型 agent”和“桌面应用/本地 transcript 型 agent”。

2. trace 不只记录文本，而是记录结构化请求差异

README 的主卖点是“inspect the real API traffic”，代码层面对应的是：

claude_tap/proxy.py：负责 API 路径 allowlist、敏感头脱敏、SSE/EventStream 重组、不同上游兼容修正
claude_tap/viewer.py：把 JSONL / 紧凑 trace 嵌入到单文件 HTML viewer，并支持相邻请求 diff
claude_tap/trace_store.py：用 SQLite 统一持久化 session、records、proxy logs，而不是散落文本文件

它关心的不是“聊天记录长什么样”，而是“每一跳请求到底变了什么”。

3. 支持 live viewer 和离线导出

运行时可起本地 live viewer / dashboard
一次 trace 可导出成自包含 HTML，便于归档、分享和做证据留存
大 trace 走 lazy loading，避免单文件 viewer 被超大 session 拖垮

这个定位和 deepwiki-open 之类“自动生成解释文档”的工具不同。claude-tap 不替你总结，它保留原始证据，再给你一层可视化检查界面。

技术架构

从仓库实际结构看，核心是四层：

claude_tap/
├── cli.py               # 总入口：参数解析、客户端选择、live viewer、CA 信任、dashboard
├── cli_clients.py       # 各 agent client 的启动/目标检测/环境改写
├── proxy.py             # reverse/forward proxy，请求转发与 trace 记录
├── trace_store.py       # SQLite 会话存储
├── viewer.py            # 自包含 HTML viewer 生成
├── live.py/dashboard.py # 实时浏览与共享仪表盘
└── *_transcript.py      # 本地 transcript/session 导入适配

几个值得注意的设计点：

客户端适配层：不是只支持 Claude Code，一个 CLIENT_CONFIGS 框架适配多家 CLI
代理安全边界：proxy.py 内置路径 allowlist，不会把任意本地 HTTP 请求都当模型流量记录
上游兼容修正：对 DeepSeek Anthropic 兼容接口、Bedrock gateway、Vertex gateway、OpenAI Responses / Chat Completions 等做了针对性处理
本地持久化：trace 数据写入 ~/.local/share/claude-tap/traces.sqlite3，而不是临时内存态
前端内嵌式 viewer：HTML/CSS/JS 资源打包进 Python 包，导出时无需再起单独前端工程

适用场景

调试 Claude Code / Codex / OpenClaw 为什么突然行为漂移
做 system prompt、tool schema、上下文压缩、参数差异的证据级比对
研究不同 harness 对同一任务的请求层差异
做 prompt snapshot、trace 存档、回归比对，这一点与 phistory 的集成很契合

局限性

本质仍是“观测层”，不替你做评估闭环；如果想把 trace 再喂回改进系统，需要配合 openai-cookbook-agent-improvement-loop 这类方法论
对真实生产流量做拦截，依赖本地代理、证书信任和各客户端接入方式，接入成本高于只读 transcript
多客户端兼容面很广，意味着边缘 case 也多；仓库里大量 test_*_launch.py / test_*_viewer.py 说明维护成本不低
更适合工程诊断和逆向分析，不是普通终端用户的日常必备工具

快速使用

uv tool install claude-tap
 
# 直接包住 Claude Code
claude-tap -- --model claude-sonnet-4-6
 
# 跑 Codex CLI
claude-tap --tap-client codex
 
# 跑 OpenClaw
claude-tap --tap-client openclaw

常见增强项：

--tap-proxy-mode forward：适合需要保留签名/原始目标的场景，例如 AWS Bedrock SigV4
--tap-no-live：关闭默认 live viewer
claude-tap dashboard stop：停掉共享 dashboard 服务

我的判断

这类工具的价值不在“又一个代理”，而在它把 AI coding agent 的黑盒运行，压成了一个可审计、可导出、可对比的本地 artifact。对做 harness、prompt、skill 工程化的人，它比普通 transcript 更接近事实层。

如果后面要系统研究 OpenClaw / Codex / Claude Code 的行为差异，claude-tap 很适合作为证据采集底座；再往上一层，可以和 skillspector、understand-anything、agent-skill-evaluation-framework 这些“分析/评估/知识组织”能力拼起来。

zhaoweiguo 的知识库

目录