claude-tap: 在本地 trace viewer 中拦截和检查编码代理 API 流量
在本地 trace viewer 中拦截和检查来自 Claude Code、Codex CLI、Gemini CLI、Cursor CLI、OpenCode、Kimi、Pi、Hermes 等编码代理的 API 流量。
claude-tap
在本地 trace viewer 中拦截和检查来自 Claude Code、Codex CLI、Gemini CLI、Cursor CLI、OpenCode、Kimi、Pi、Hermes 等编码代理的 API 流量。
claude-tap 是一个用于 AI 编码代理的本地代理和 trace 查看器。通过它运行你的 CLI 工具，然后检查真实的 API 流量：系统提示词、对话历史、工具定义、工具调用、流式响应、token 用量和请求差异对比。
它支持 Claude Code、 Codex CLI、 Gemini CLI、 Kimi CLI、 OpenCode、 Pi、 Hermes Agent、 Cursor CLI、 Qoder CLI、 Antigravity CLI 和 CodeBuddy CLI。
为什么使用它
核心价值一览
- 查看确切的上下文 — 检查提示词、消息、工具定义、工具调用、工具结果、重建的流式响应和 token 用量。
- 基于证据调试行为 — 比较相邻请求，精确定位哪个提示词、消息、工具或参数发生了变化。
- 分享一个可移植的制品 — 每次运行都会写入一个本地 trace 会话，可导出为自包含的 HTML 查看器，供审查或存档。
- trace 数据留在你的机器上 — 不需要托管的仪表盘，常见的认证头会在记录前被脱敏。
- 跨客户端使用统一工作流 — 可 trace Claude Code、Codex CLI、Gemini CLI、Kimi CLI、OpenCode、Pi、Hermes Agent、Cursor CLI、Qoder CLI 和 CodeBuddy。
支持的客户端
11 种主流编码代理
| 客户端 | 典型用途 |
|---|---|
| Claude Code | Anthropic API、AWS Bedrock 或兼容 Claude 的网关（如 DeepSeek / GLM） |
| Codex CLI | OpenAI API key 模式或 ChatGPT 订阅 OAuth |
| Gemini CLI | Google OAuth / Code Assist 流量 |
| Kimi CLI | Kimi Code 或 Moonshot 开放平台 |
| OpenCode | 多提供商的 OpenCode 会话 |
| Pi | Pi 会话，包括 OpenAI Codex OAuth 提供商 |
| Hermes Agent | 多提供商 Hermes TUI 或网关会话 |
| Cursor CLI | Cursor Agent 会话，以及可读的本地转录导入 |
| Qoder CLI | 通过正向代理模式的 Qoder Agent 会话 |
| Antigravity CLI | 通过正向代理模式的 Antigravity Agent 会话 |
| CodeBuddy CLI | 腾讯 CodeBuddy SaaS 或内部 Copilot 端点 |
安装
需要 Python 3.11+ 以及你想要 trace 的客户端。
# 推荐
uv tool install claude-tap
# 或使用 pip
pip install claude-tap升级：claude-tap update、uv tool upgrade claude-tap 或 pip install --upgrade claude-tap
快速开始
通过 claude-tap 运行你想要检查的客户端。-- 之后的参数会传递给选定的客户端。
# Claude Code，默认启用实时浏览器查看器
claude-tap
# 恢复 v0.1.75 之前的行为：不启动实时查看器服务器
claude-tap --tap-no-live
# Codex CLI
claude-tap --tap-client codex
# Gemini CLI
claude-tap --tap-client gemini -- -p "hello"
# Kimi CLI
claude-tap --tap-client kimi
# Pi
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"
# Cursor CLI
claude-tap --tap-client cursor -- -p --trust --model auto "hello"
# Qoder CLI
claude-tap --tap-client qoder -- -p "hello" --permission-mode dont_ask
# Antigravity CLI
claude-tap --tap-client agy
# CodeBuddy CLI
claude-tap --tap-client codebuddyClaude Code 示例
# 将参数透传给 Claude Code
claude-tap -- --model claude-opus-4-6
claude-tap -c # 继续上次对话
# 跳过所有权限提示（自动接受工具调用）
claude-tap -- --dangerously-skip-permissions
# 实时查看器默认开启；在 -- 后传递 Claude 参数
claude-tap -- --dangerously-skip-permissions --model claude-sonnet-4-6
claude-tap 会自动从环境变量或 Claude 设置中检测自定义的 Claude Code 上游地址（ANTHROPIC_BASE_URL 或 ANTHROPIC_BEDROCK_BASE_URL）。仅当你想要覆盖自动检测的目标时才使用 --tap-target。
对于 Claude Code VS Code 扩展，将 Claude Code: Claude Process Wrapper 设置为 claude-tap；在 Windows 上，如果 VS Code 找不到它，请使用完整的 claude-tap.exe 路径。
Claude Code 搭配 DeepSeek API
英文完整指南：Claude Code with DeepSeek API。简体中文版：Claude Code 搭配 DeepSeek API。
export ANTHROPIC_AUTH_TOKEN="<your DeepSeek API key>"
unset ANTHROPIC_API_KEY
export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export CLAUDE_CODE_EFFORT_LEVEL=maxclaude-tap -- --permission-mode bypassPermissionsClaude Code 搭配 AWS Bedrock
claude-tap 支持两种 Bedrock 场景，并自动检测适用哪种：
自定义 Bedrock 网关（公司代理，无 SigV4）
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL="https://your-gateway.company.com/bedrock"
claude-tap
claude-tap 检测到非 AWS 主机，将 ANTHROPIC_BASE_URL 和 ANTHROPIC_BEDROCK_BASE_URL 都重定向到本地代理，并解码 AWS EventStream 二进制响应格式以提取 token 用量和模型信息。
AWS 原生 Bedrock（SigV4 签名请求）
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL="https://bedrock-runtime.us-east-1.amazonaws.com"
export AWS_REGION="us-east-1"
claude-tap --tap-proxy-mode forward
当端点是真实的 AWS 域名（*.amazonaws.com）时，claude-tap 不会将 ANTHROPIC_BEDROCK_BASE_URL 重写为 localhost——这样做会破坏 AWS SigV4 签名验证。使用正向代理模式（--tap-proxy-mode forward）在不修改签名请求的情况下捕获此流量。
Codex CLI 认证模式和示例
Codex CLI 支持两种认证模式，对应不同的上游目标：
| 认证模式 | 认证方式 | 上游目标 | 备注 |
|---|---|---|---|
| OAuth（ChatGPT 订阅） | codex login | https://chatgpt.com/backend-api/codex | ChatGPT Plus/Pro/Team 用户默认方式 |
| API Key | 设置 OPENAI_API_KEY | https://api.openai.com（默认） | 通过 OpenAI Platform 按量付费 |
# OAuth 用户（ChatGPT Plus/Pro/Team） — 在 `codex login` 后自动检测
claude-tap --tap-client codex
# 如果自动检测无法读取你的 Codex 认证文件，显式指定目标
claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex
# API Key 用户 — 默认 OpenAI API 目标可直接使用
claude-tap --tap-client codex
# 指定特定模型
claude-tap --tap-client codex -- --model codex-mini-latest
# 完全自动批准（跳过所有权限提示）
claude-tap --tap-client codex -- --full-autoKimi CLI 示例
claude-tap --tap-client kimi
claude-tap --tap-client kimi -- --thinking
# 使用 Moonshot 开放平台而非 Kimi Code
claude-tap --tap-client kimi --tap-target https://api.moonshot.ai/v1Gemini CLI 示例
# Google OAuth / Code Assist
claude-tap --tap-client gemini -- -p "hello"
# 兼容 API-key / Vertex 流程的反向模式
claude-tap --tap-client gemini --tap-proxy-mode reverse -- -p "hello"OpenCode 示例
# 正向代理模式 — 捕获 OpenCode 通信的所有提供商（默认）
claude-tap --tap-client opencode
# 反向模式 — 通过 ANTHROPIC_BASE_URL 使用单个 Anthropic 提供商
claude-tap --tap-client opencode --tap-proxy-mode reversePi 示例
# 通过 Pi 的 openai-codex 提供商使用 OpenAI Codex OAuth
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"
# 只读工具捕获
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark --tools bash -p "Run pwd"Pi 在 /login 后将 OAuth 凭据存储在 ~/.pi/agent/auth.json 中。如果你将 Pi 凭据保存在其他目录，请在启动 claude-tap 之前设置 PI_CODING_AGENT_DIR。
Hermes Agent 示例
# 交互式 TUI — 推荐的本地 trace 捕获方式。
claude-tap --tap-client hermes
# 网关模式 — 捕获由传入的平台消息（Slack、Telegram 等）触发的 LLM 调用。
claude-tap --tap-client hermes -- gateway start
# 反向模式可通过 OPENAI_BASE_URL 为与 OpenAI 兼容的 Hermes 环境配置选择性启用。
claude-tap --tap-client hermes --tap-proxy-mode reverseCursor CLI 示例
claude-tap --tap-client cursor -- -p --trust --model auto "hello"
claude-tap --tap-client cursor -- -p --trust --model auto --continue "continue"Qoder CLI 示例
# 浏览器登录、PAT 或 job token 必须在启动前配置。
qodercli login
claude-tap --tap-client qoder -- -p "hello" --permission-mode dont_askAntigravity CLI 示例
claude-tap --tap-client agy --tap-live
# 可选：在启动正向代理客户端之前单独信任 CA。
claude-tap trust-ca在 macOS 上，Antigravity 可能不遵循每个进程的 CA 环境变量。claude-tap 在首次 agy 启动时自动信任当前用户登录钥匙串中的本地 CA。这不会使用 sudo 或系统钥匙串，但 macOS 可能会提示解锁登录钥匙串。
CodeBuddy CLI 示例
# 自动检测端点（登录后适用于所有四种登录模式）
claude-tap --tap-client codebuddy
# 显式覆盖（例如外部 SaaS 或测试环境）
claude-tap --tap-client codebuddy --tap-target https://www.codebuddy.ai/v2
# 或通过环境变量
CODEBUDDY_BASE_URL=https://www.codebuddy.ai/v2 claude-tap --tap-client codebuddy -- -p "Reply OK"指南和集成
- OpenClaw 设置指南 用于将
claude-tap与 OpenClaw 集成。简体中文版：OpenClaw 设置指南。 - Claude Code 搭配 DeepSeek API 将 Claude Code 路由通过 DeepSeek 的 Anthropic 兼容 API。简体中文版：Claude Code 搭配 DeepSeek API。
- 客户端支持矩阵 精确的环境变量、代理模式和 URL 重写规则。
查看器、导出和高级选项
# 实时查看器在客户端运行时默认运行
claude-tap
# 为脚本、CI、远程 shell 或旧行为禁用实时查看器
claude-tap --tap-no-live
# 在不启动客户端的情况下浏览已保存的 trace
claude-tap dashboard
# 从 JSONL 重新生成自包含的 HTML 查看器
claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html
# 导出可移植的紧凑 trace 包，之后再进行渲染
claude-tap export <session-id> --format compact -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html
# 仅捕获提示词表面用于自动化；同时在 prompt.md 旁边写入 trace.jsonl
claude-tap --tap-export-prompt prompt.md -- -p "hello"
# 在 iframe 中嵌入导出的查看器，使用简化的界面
# trace.html?embed=1&hideHeader=1&hidePath=1&hideHistory=1&hideControls=1&density=compact&theme=light
# 将 trace 存储在其他目录，或保留更少的会话
claude-tap --tap-output-dir ./my-traces
claude-tap --tap-max-traces 10
# 仅为自定义设置启动代理
claude-tap --tap-no-launch --tap-port 8080
# 禁用实时和生成查看器的浏览器自动打开
claude-tap --tap-no-open在仅代理模式下，在另一个终端启动你的客户端，并将其 base URL 或代理设置指向本地代理。使用客户端支持矩阵了解确切的连接方式。
当作为 VSCode Claude Code 的 claudeProcessWrapper 使用时，claude-tap 会遵循扩展传递的 Claude 二进制路径。
CLI 选项
所有参数都会转发给选定的客户端，除了以下这些 --tap-* 参数：
| 参数 | 说明 |
|---|---|
--tap-client CLIENT | 要启动的客户端：claude（默认）、agy、codex、gemini、kimi、opencode、pi、hermes、cursor、qoder 或 codebuddy |
--tap-target URL | 上游 API URL（默认：按客户端自动选择） |
--tap-live | 在客户端运行时启动实时查看器（默认：开启） |
--tap-no-live | 禁用实时查看器服务器（v0.1.75 之前的行为） |
--tap-live-port PORT | 实时查看器服务器端口（默认：自动选择） |
--tap-no-open | 不自动在浏览器中打开实时或生成的 HTML 查看器 |
--tap-output-dir DIR | Trace 输出目录（默认：./.traces） |
--tap-port PORT | 代理端口（默认：自动选择） |
--tap-host HOST | 绑定地址（默认：127.0.0.1，或在 --tap-no-launch 模式下为 0.0.0.0） |
--tap-no-launch | 仅启动代理，不启动客户端 |
--tap-max-traces N | 保留的最大 trace 会话数（默认：50，0 = 无限制） |
--tap-store-stream-events | 在捕获期间持久化原始 SSE/WebSocket 事件数组，以便查看器/导出输出可以显示它们（默认：关闭） |
--tap-no-update-check | 禁用启动时的 PyPI 更新检查 |
--tap-no-auto-update | 检查更新但不自动下载 |
--tap-proxy-mode MODE | 代理模式：reverse 或 forward（默认：claude/codex/kimi/codebuddy 为 reverse，agy/gemini/opencode/pi/hermes/cursor/qoder 为 forward） |
--tap-trust-ca | 在 macOS 上，在启动前显式信任用户登录钥匙串中的本地 CA（agy 会自动执行此操作） |
Trace 查看器功能
查看器是一个单独的自包含 HTML 文件（零外部依赖）：
结构化差异对比
比较连续请求以准确查看变化：新增/移除的消息、系统提示词差异、字符级内联高亮
路径过滤
按 API 端点过滤（例如仅显示 /v1/messages）
模型分组
侧边栏按模型对请求进行分组，优先排列 Claude 系列
Token 用量明细
输入 / 输出 / 缓存读取 / 缓存创建
工具检查器
可展开的卡片，包含工具名称、描述和参数 schema
全文搜索
跨消息、工具、提示词和响应的全文搜索
深色模式
切换浅色/深色主题（遵循系统偏好）
Iframe 嵌入模式
支持 ?embed=1、hideHeader=1、density=compact 等查询参数
键盘导航
j / k 或方向键
复制辅助
一键复制请求 JSON 或 cURL 命令
国际化 (i18n)
英语、简体中文、日本語、한국어、Français、العربية、Deutsch、Русский
架构
工作原理
claude-tap启动反向或正向代理，并生成选定的客户端- 支持 base URL 的客户端指向反向代理；不支持 base URL 的客户端使用 proxy/CA 环境变量
- SSE 和 WebSocket 流以低代理开销按块/消息到达时进行转发
- 每个请求-响应对或 WebSocket 会话被记录到本地 trace 存储中；原始 SSE/WebSocket 事件数组默认不存储，如需在查看器/导出输出中使用，必须通过
--tap-store-stream-events捕获 - 退出时，生成自包含的 HTML 查看器
- 实时模式默认启用，通过 SSE 将更新广播到浏览器
🔒 常见认证头自动脱敏 ⚡ 低开销流式传输 📦 自包含查看器 🔄 实时模式
参与贡献
欢迎贡献。从 CONTRIBUTING.md 开始。
许可证
MIT