claude-tap

English

claude-tap 是给 AI 编程 agent 用的本地代理和 trace 查看器。把 CLI 通过它启动，或监听本地 app transcript，就能看到真实 API 流量和 agent 上下文：system prompt、对话历史、工具 schema、工具调用、流式响应、token 用量和请求 diff。

网站：本地 AI Agent Trace Viewer · 指南：如何本地查看 Agent traces

它支持 Claude Code、Codex CLI、Codex App、Gemini CLI、Grok Build CLI、Kimi CLI、MiMo Code、OpenCode、OpenClaw、Pi、Hermes Agent、Cursor CLI、Qoder CLI、Antigravity CLI 和 CodeBuddy CLI。

_{打开一次真实 agent 运行，检查每个请求，并对比上下文如何在多轮之间变化。}

亮色模式总览

适合长时间 review 的暗色模式

相邻请求之间的结构化 Diff

使用 claude-tap 构建

Phistory 会归档 Claude Code、Codex、Kimi、opencode、Pi 等 Agent CLI 的系统提示词版本快照。它基于 claude-tap 的 capture-only prompt export 能力，保留原始 HTTP trace 证据，并生成方便阅读和对比的 prompt 快照。 打开 prompt diff 查看器 · 查看仓库

为什么用它

• 👀 看见真实上下文：检查 prompt、messages、工具定义、工具调用、工具结果、流式 chunk 和 token 用量。
• 🔎 用证据定位问题：对比相邻请求，明确是哪段 prompt、消息、工具或参数发生了变化。
• 📦 留下可分享证据：每次运行都会写入 JSONL trace，并生成自包含 HTML 查看器，方便 review 或归档。
• 🔒 数据留在本机：不依赖云端 dashboard；常见认证 header 会在记录前自动脱敏。
• 🧩 覆盖主流编码客户端：同一套流程可用于 Claude Code、Codex CLI、Codex App、Gemini CLI、Grok Build CLI、DeepSeek Harness、Kimi CLI、MiMo Code、OpenCode、OpenClaw、Pi、Hermes Agent、Cursor CLI、Qoder CLI、Antigravity CLI 和 CodeBuddy CLI。

支持的客户端

客户端	典型用途
Claude Code	Anthropic API、AWS Bedrock、DeepSeek / GLM 等 Claude 兼容网关，或 CC Switch 等本地代理上游
Codex CLI	OpenAI API 密钥模式，或 ChatGPT 订阅 OAuth
Codex App	通过 forward proxy 启动桌面 App，捕获后端 HTTP/WebSocket 请求体
Gemini CLI	Google OAuth / Code Assist 的多 Google 端点流量
Grok Build CLI	通过官方 CLI chat proxy 捕获 Grok 订阅 OAuth 会话
DeepSeek Harness	使用 DeepSeek 或兼容网关的 dsh headless 任务和自定义 profile
Kimi CLI	旧版 kimi-cli 和新版 Kimi Code CLI
MiMo Code	MiMo Code 会话（基于 OpenCode 的多提供方 fork）
OpenCode	多提供方 OpenCode 会话
OpenClaw	多提供方 OpenClaw 会话
Pi	Pi 会话，包括 OpenAI Codex OAuth 提供方
Hermes Agent	多提供方 Hermes TUI 或 gateway 会话
Cursor CLI / IDE Agent	启动 cursor-agent + 实时 transcript watch（claude-tap --tap-client cursor）
Qoder CLI	通过 forward proxy 捕获 Qoder Agent 会话
Antigravity CLI	通过 forward proxy 捕获 Antigravity Agent 会话
CodeBuddy CLI	腾讯 CodeBuddy SaaS 或内部 Copilot 端点

安装

需要 Python 3.11+，以及你要追踪的客户端。

# 推荐
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

# Codex App 后端请求捕获
claude-tap --tap-client codexapp

# Gemini CLI
claude-tap --tap-client gemini -- -p "hello"

# Grok Build CLI
claude-tap --tap-client grok -- -p "hello"

# DeepSeek Harness headless 任务
claude-tap --tap-client dsh -- --profile headless "Reply OK"

# Kimi CLI
claude-tap --tap-client kimi

# 新版 Kimi Code CLI
claude-tap --tap-client kimi-code

# MiMo Code（OpenCode fork）
claude-tap --tap-client mimo

# Pi
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"

# Cursor：启动 cursor-agent + 实时 transcript watch + dashboard
claude-tap --tap-client cursor

# 只 watch IDE Agent transcript（不启动 CLI）
claude-tap --tap-client cursor --tap-no-launch

# 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 codebuddy

Claude Code 更多示例

# 透传参数给 Claude Code
claude-tap -- --model claude-opus-4-6
claude-tap -c    # 继续上次对话

# 跳过所有权限确认（自动批准工具调用）
claude-tap -- --dangerously-skip-permissions

# 实时查看器默认开启；-- 后面的参数透传给 Claude Code
claude-tap -- --dangerously-skip-permissions --model claude-sonnet-4-6

claude-tap 会从环境变量或 Claude settings 中的 ANTHROPIC_BASE_URL、 ANTHROPIC_BEDROCK_BASE_URL 或 ANTHROPIC_VERTEX_BASE_URL 自动识别自定义 Claude Code 上游；只有想手动覆盖时才需要传 --tap-target。

也支持本地代理上游：如果 CC Switch 等工具把 Claude Code 指向本地 ANTHROPIC_BASE_URL，claude-tap 会从 Claude settings 中检测到该值，并在转发到上游前记录流量。用 claude-tap 替代 claude 运行，例如 claude-tap -- <Claude Code 参数>；不需要单独的 --tap-client 值。

使用 Claude Code VS Code 插件时，把 Claude Code: Claude Process Wrapper 设置为 claude-tap；如果 Windows 上 VS Code 找不到它，请填写完整的 claude-tap.exe 路径。

Claude Code + DeepSeek API

完整中文指南见 Claude Code 搭配 DeepSeek API，英文版见 Claude Code with DeepSeek API。

export ANTHROPIC_AUTH_TOKEN="<你的 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 CLAUDE_CODE_EFFORT_LEVEL=max
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic

claude-tap -- --permission-mode bypassPermissions

claude-tap 会从 ANTHROPIC_BASE_URL 读取 DeepSeek 上游，再把 Claude Code 指向本地代理。只有手动覆盖时才需要 --tap-target https://api.deepseek.com/anthropic。

Claude Code + AWS Bedrock

claude-tap 支持三种 Bedrock 场景，并自动检测适用哪种：

Anthropic 兼容 Bedrock 网关（New API 或类似网关，Claude Code 不做 SigV4）

export ANTHROPIC_AUTH_TOKEN="<your gateway token>"
unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://new-api.example.com"
export ANTHROPIC_MODEL="bedrock/claude-opus-4-6"
export ANTHROPIC_DEFAULT_OPUS_MODEL="bedrock/claude-opus-4-6"
export ANTHROPIC_DEFAULT_SONNET_MODEL="bedrock/claude-opus-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="bedrock/claude-opus-4-6"
claude-tap -- --model bedrock/claude-opus-4-6

claude-tap 会记录正常的 Claude Code /v1/messages HTTP/SSE 流量，再转发给网关。对于以 bedrock/ 开头的模型名，它会在转发上游前移除 AWS Bedrock 不接受的 Claude Code beta-only 请求选项，同时保留已捕获的 trace。

自定义 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）来捕获此流量，而不修改已签名的请求。

只有手动覆盖时才需要 --tap-target。

Claude Code + Google Vertex AI

claude-tap 支持暴露 Vertex rawPredict、streamRawPredict 和 count-tokens:rawPredict 路径的 Claude Code Vertex 透传网关。

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-east5"
export ANTHROPIC_VERTEX_PROJECT_ID="your-project-id"
export ANTHROPIC_VERTEX_BASE_URL="https://your-gateway.company.com/vertex"
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1  # 网关负责鉴权时使用
claude-tap

当 CLAUDE_CODE_USE_VERTEX=1 且配置了 ANTHROPIC_VERTEX_BASE_URL 时， claude-tap 会检测到该上游，将 ANTHROPIC_BASE_URL 和 ANTHROPIC_VERTEX_BASE_URL 都重定向到本地代理，并记录 Vertex rawPredict HTTP/SSE 流量。如果 Claude Code 直接使用 Google Vertex 原生端点且没有设置 ANTHROPIC_VERTEX_BASE_URL，请使用正向代理模式，或显式设置该 base URL，让 reverse 模式有单一上游可转发。

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 按量付费

claude-tap 会尽量根据 Codex 的认证状态自动识别 target。 在默认 reverse proxy 模式下，它会使用一个临时同级 provider 启动 Codex， 并禁用该 provider 的 supports_websockets。这样每个请求都会生成一条包含 完整请求上下文的 HTTP/SSE trace，同时不会修改 ~/.codex/config.toml。

# OAuth 用户（ChatGPT Plus/Pro/Team）— `codex login` 后通常会自动识别
claude-tap --tap-client codex

# 如果无法读取 Codex auth 文件，可以显式指定 target
claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex

# API Key 用户 — 默认 OpenAI API target 即可
claude-tap --tap-client codex

# 指定模型
claude-tap --tap-client codex -- --model codex-mini-latest

# 全自动模式（跳过所有权限确认）
claude-tap --tap-client codex -- --full-auto

# OAuth + 全自动；实时查看器默认开启
claude-tap --tap-client codex -- --full-auto

Codex App 后端捕获示例

Codex App 会通过 claude-tap 的 forward proxy 启动，因此最终发往 /backend-api/codex/responses 的 HTTP 和 WebSocket 请求体会像其他客户端一样进入 trace viewer。当前 macOS 安装包多为 ChatGPT.app（bundle id 仍是 com.openai.codex）；旧版独立 Codex.app 也会被识别。非模型产品流量会照常转发，但不会持久化成 trace 行。在 macOS 上，必要时 claude-tap 会把本地 CA 信任到当前用户的登录钥匙串中，让内置 app-server 能通过代理连接。

# 启动 Codex App（ChatGPT.app 或 Codex.app），并在 dashboard 中查看捕获到的后端请求
claude-tap --tap-client codexapp

# 在 trace 中保留原始 WebSocket/SSE 事件数组
claude-tap --tap-client codexapp --tap-store-stream-events

# 应用不在默认安装位置时，可覆盖可执行文件路径
CODEX_APP_EXECUTABLE=/path/to/ChatGPT.app/Contents/MacOS/ChatGPT claude-tap --tap-client codexapp

如果 Codex/ChatGPT App 已经在运行，claude-tap 会用独立的 --user-data-dir（默认 ~/.claude-tap/codex-app-profiles/tap）再拉起第二份实例，不打断你当前窗口；被代理的那份窗口可能需要重新登录。可用 CODEX_APP_USER_DATA_DIR 覆盖 profile 路径。这个模式捕获实时后端流量，不再导入本地 session JSONL transcript。

Kimi CLI 示例

旧版 kimi-cli 使用 --tap-client kimi，新版 Kimi Code CLI 使用 --tap-client kimi-code。两者默认都使用 reverse proxy 模式。

claude-tap --tap-client kimi
claude-tap --tap-client kimi -- --thinking
claude-tap --tap-client kimi --tap-target https://api.moonshot.ai/v1

claude-tap --tap-client kimi-code
claude-tap --tap-client kimi-code -- --thinking
claude-tap --tap-client kimi-code --tap-target https://api.moonshot.ai/v1

Gemini CLI 示例

Gemini CLI 默认使用 forward proxy。Google OAuth / Code Assist 流量会访问多个 Google 端点，因此 forward proxy 是更稳妥的默认抓取方式。对于会读取 GOOGLE_GEMINI_BASE_URL 或 GOOGLE_VERTEX_BASE_URL 的 API key / Vertex 类流程，仍可显式使用 reverse 模式。

# Google OAuth / Code Assist
claude-tap --tap-client gemini -- -p "hello"

# 实时查看器默认开启
claude-tap --tap-client gemini -- -p "hello"

# API key / Vertex 兼容流程的 reverse 模式
claude-tap --tap-client gemini --tap-proxy-mode reverse -- -p "hello"

OpenCode 示例

OpenCode 是一款多 provider 的终端 AI 助手。由于它能对接多种 provider，claude-tap 默认对 opencode 使用 forward proxy 模式——向子进程注入 HTTPS_PROXY 与本地 CA，捕获它对接的任意 provider 流量。

# forward proxy 模式 — 捕获 opencode 对接的任意 provider（默认）
claude-tap --tap-client opencode

# 实时查看器默认开启
claude-tap --tap-client opencode

# reverse 模式 — 仅在使用 Anthropic provider 时有效（单一 ANTHROPIC_BASE_URL）
claude-tap --tap-client opencode --tap-proxy-mode reverse

MiMo Code 示例

MiMo Code 是 OpenCode 的 fork，增加了持久化记忆、子 agent 编排和小米 MiMo 平台集成。claude-tap 默认对 mimocode 使用 forward proxy 模式——向子进程注入 HTTPS_PROXY 与本地 CA，捕获它对接的任意 provider 流量。

# forward proxy 模式 — 捕获 MiMo Code 对接的所有 provider（默认）
claude-tap --tap-client mimo

# 实时查看器默认开启
claude-tap --tap-client mimo

# reverse 模式 — 单一 Anthropic provider 并关闭 mimo-only 模式
claude-tap --tap-client mimo --tap-proxy-mode reverse

Pi 示例

Pi 是一个多 provider coding agent。因为 Pi 可以使用 openai-codex 这类订阅 OAuth provider，也可以使用模型注册表中的自定义 API-key provider，claude-tap 默认对 Pi 使用 forward proxy 模式。

# 通过 Pi 的 openai-codex provider 使用 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 -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 示例

Hermes Agent 是基于 Python 的多 provider AI agent（Nous Portal / OpenRouter / NVIDIA NIM / 小米 MiMo / GLM / Kimi / MiniMax / Hugging Face / OpenAI / Anthropic / 自定义）。由于它能对接任意 provider，且 httpx、requests 都默认认 HTTPS_PROXY 环境变量，claude-tap 默认对 hermes 使用 forward proxy 模式——通过向子进程注入 HTTPS_PROXY 与本地 CA，捕获它对接的任意 provider 流量。

# 交互式 TUI — 本地抓 trace 的推荐方式。
claude-tap --tap-client hermes

# Gateway 模式 — 捕获由 Slack、Telegram 等平台消息触发的 LLM 调用。
# 需要在 ~/.hermes/.env 中配置消息平台。
# claude-tap 自动将 `gateway start` 改写为 `gateway run`，使 gateway 在前台运行并
# 继承 HTTPS_PROXY；否则 systemd/launchd 启动的守护进程不会经过代理，无法抓到 trace。
claude-tap --tap-client hermes -- gateway start

# 反向模式仅在 ~/.hermes 配了一个读 OPENAI_BASE_URL 的 OpenAI 兼容 provider 时才有用
claude-tap --tap-client hermes --tap-proxy-mode reverse

注意： Gateway 模式只有在配置的消息平台（Slack、Telegram 等）推送消息给 bot 时才会产生 trace。若没有活跃的平台集成，gateway 不会发起 LLM 请求，也不会生成任何 trace。

Cursor CLI / IDE Agent 示例

Cursor 是 transcript-only（既不是反向代理也不是正向代理）：最短命令会启动 cursor-agent，同时监听 ~/.cursor/projects/*/agent-transcripts/*.jsonl，并且 每个 Cursor 会话 JSONL 对应一个独立 dashboard session，不 MITM api2.cursor.sh。

# 启动 agent + 实时 watch + dashboard（默认）
claude-tap --tap-client cursor

# 透传参数给 cursor-agent
claude-tap --tap-client cursor -- -p --trust --model auto "hello"

# 只 watch IDE Agent（不启动 CLI）
claude-tap --tap-client cursor --tap-no-launch

集成与指南

• OpenClaw 设置指南：在 OpenClaw 中集成 claude-tap。英文版见 OpenClaw setup guide。
• Claude Code 搭配 DeepSeek API：让 Claude Code 走 DeepSeek 的 Anthropic 兼容 API。英文版见 Claude Code with DeepSeek API。
• 客户端支持矩阵：查看各客户端对应的环境变量、代理模式和 URL 改写规则。

Qoder CLI 示例

Qoder CLI 会访问多个 Qoder 端点，因此 --tap-client qoder 默认使用 forward proxy 模式。

# 启动前需要先配置浏览器登录、PAT 或 job token。
qodercli login

claude-tap --tap-client qoder -- -p "hello" --permission-mode dont_ask

Antigravity CLI 示例

Antigravity CLI 会访问多个 Google / Antigravity 端点，因此 --tap-client agy 默认使用 forward proxy 模式。它的 Code Assist 模型 API 还会读取 CLOUD_CODE_URL；claude-tap 会自动注入这个变量，让 /v1internal:streamGenerateContent 这类模型请求也进入同一个本地代理。

在 macOS 上，Antigravity 可能不读取进程级 CA 环境变量。首次启动 agy 时，claude-tap 会自动把本地 CA 信任到当前用户的 login keychain。这个操作不会使用 sudo，也不会写入 System keychain，但 macOS 可能要求解锁 login keychain。

claude-tap --tap-client agy --tap-live

# 可选：也可以先单独信任 CA，再启动 forward proxy 客户端。
claude-tap trust-ca

Grok Build CLI 示例

Grok Build 默认使用 reverse proxy。claude-tap 会临时把官方 GROK_CLI_CHAT_PROXY_BASE_URL 指向本地代理，捕获 OpenAI Responses HTTP/SSE 流量以及 Grok storage/trace 审计请求，再使用现有的 Grok OAuth 会话转发到 https://cli-chat-proxy.grok.com/v1。

# 先用官方 Grok Build CLI 完成一次认证。
grok login

# 交互式 TUI
claude-tap --tap-client grok

# Headless 单轮
claude-tap --tap-client grok -- -p "Reply OK"

# 自定义 Grok 兼容部署
GROK_CLI_CHAT_PROXY_BASE_URL=https://grok-gateway.example.com/v1 \
  claude-tap --tap-client grok -- -p "Reply OK"

DeepSeek Harness 示例

DeepSeek Harness（dsh）默认使用 forward proxy。无论模型端点来自 DEEPSEEK_BASE_URL，还是保存在 dsh 模型设置中，都可以捕获，包括通常会被 NO_PROXY 绕过的本地网关。启动器会确认 Node 支持 --use-env-proxy，仅记录 Chat Completions 流量，并将 -- 后的参数原样传给 dsh。如果当前 Node 不支持该能力，请升级 Node，或对环境变量配置的端点使用 reverse 模式。

# 一次性 headless 任务
claude-tap --tap-client dsh -- --profile headless "Summarize this repository"

# 自定义 dsh profile
claude-tap --tap-client dsh -- --profile my-profile

# 仅通过 DEEPSEEK_BASE_URL 配置的部署也可显式使用 reverse 模式
claude-tap --tap-client dsh --tap-proxy-mode reverse \
  -- --profile headless "Reply OK"

CodeBuddy CLI 示例

CodeBuddy 默认使用 reverse proxy。claude-tap 会自动从 CodeBuddy 自己的登录缓存（~/.codebuddy/local_storage/）识别上游地址，所以 iOA / WeChat / Google-Github / Enterprise-Domain 四种登录方式登录后都可以零参数启动。当缓存还不存在（例如首次登录前）时，会回退到 https://copilot.tencent.com/v2。

# 自动识别上游（登录后四种登录方式都适用）
claude-tap --tap-client codebuddy

# 显式指定上游（外网 SaaS 或 staging）
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"

查看器、导出和高级选项

# 客户端运行时默认启动实时查看器
claude-tap

# 脚本、CI、远程 shell 或需要旧行为时关闭实时查看器
claude-tap --tap-no-live

# 不启动客户端，直接浏览历史 trace
claude-tap dashboard

# 停止共享 dashboard 服务
claude-tap dashboard stop

# 构建本地 macOS 菜单栏 App，然后在 Finder 中双击
claude-tap build-macos-app
open "dist/Claude Tap.app"

# 构建内置 Python 和依赖的 Apple Silicon App
claude-tap build-macos-app --self-contained

# 如果菜单栏 App 在监控中被强制退出，用它恢复 Claude/Codex 配置
claude-tap monitor-restore

# 从已有 JSONL 或紧凑 trace 重新生成自包含 HTML 查看器
claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html

# 导出可独立搬运的压缩 trace，再按需渲染；压缩格式是默认导出格式
claude-tap export <session-id> -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html

# 在 iframe 中嵌入导出的查看器，并减少外层 chrome
# 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 binary 路径并用它启动 Claude。

macOS 上，claude-tap build-macos-app 会生成本地 Claude Tap.app。该 App 以菜单栏图标运行，点击后显示紧凑状态看板，并提供 Start Monitor / Stop Monitor 控制和完整 dashboard 快捷入口。Start Monitor 会先请求确认，再启动 Claude Code 和 Codex CLI 的本地反向代理，并把临时 base URL 写入 ~/.claude/settings.json 和 ~/.codex/config.toml，之后新开的会话会被捕获。Codex 自定义 provider 会改写所选 provider 的 base_url；Claude Bedrock 自定义网关会在目标不是 AWS 原生 Bedrock endpoint 时被路由。AWS 原生 Bedrock endpoint 会保持不变，因为 reverse 模式改写 URL 会破坏 SigV4 签名。Stop Monitor 会按字节还原配置文件。如果 App 被强制退出，可运行 claude-tap monitor-restore 还原配置，并清理 App 记录的 monitor 进程。

默认 launcher 指向当前 checkout；如果构建时所用 Python 环境已经安装了 claude-tap，可加 --installed。加 --self-contained 会用 PyInstaller 构建 Apple Silicon 自包含 bundle，并放在 Contents/Resources 下，这样 App 不依赖同事机器上的 Python 安装。Ad-hoc 签名的构建仍可能需要接收方移除 quarantine 或在 macOS 安全设置中手动允许。

CLI 选项

除以下 --tap-* 参数外，所有参数均透传给所选客户端：

--tap-client CLIENT      启动或监听的客户端: claude（默认）/ agy / codex / codexapp / dsh / gemini / grok / kimi / kimi-code / mimo / opencode / openclaw / pi / hermes / cursor / qoder / codebuddy
--tap-target URL         上游 API 地址（默认: 根据客户端自动选择）
--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 event 数组写入 trace 存储，以便查看器/导出结果展示（默认关闭）
--tap-proxy-mode MODE    代理模式: reverse 或 forward（默认：claude/codex/grok/kimi/kimi-code/openclaw/codebuddy 用 reverse，agy/codexapp/dsh/gemini/mimo/opencode/pi/hermes/qoder 用 forward；cursor 为 transcript-only，不走 MITM 代理）
--tap-trust-ca           macOS 上显式把本地 CA 信任到当前用户 login keychain（agy 会自动执行）

查看器功能

Trace 查看器能力

查看器是一个自包含的 HTML 文件（零外部依赖）：

• 结构化 Diff — 对比相邻请求的变化：新增/删除的消息、system prompt diff、字符级高亮
• 路径过滤 — 按 API 端点筛选（如仅显示 /v1/messages）
• 模型分组 — 侧边栏按模型分组，并对 Claude 系列模型做优先排序
• Token 用量分析 — 输入 / 输出 / 缓存读取 / 缓存创建
• 工具检查器 — 可展开的卡片，显示工具名称、描述和参数 schema
• 全文搜索 — 搜索消息、工具、prompt 和响应
• 暗色模式 — 切换亮色/暗色主题（跟随系统偏好）
• iframe 嵌入模式 — 添加 embed=1、hideHeader=1、hidePath=1、hideHistory=1、hideControls=1、density=compact、theme=light|dark 等 query 参数
• 键盘导航 — j/k 或方向键
• 复制助手 — 一键复制请求 JSON 或 cURL 命令
• 多语言 — English, 简体中文, 日本語, 한국어, Français, العربية, Deutsch, Русский

架构

工作原理

工作原理:

1. claude-tap 启动反向代理或 forward proxy，并启动所选客户端
2. 支持 base URL 的客户端会指向反向代理；不支持 base URL 的客户端会通过 proxy/CA 环境变量接入
3. SSE 和 WebSocket 流会在收到 chunk/message 时实时转发，代理开销很低
4. 每个请求-响应对或 WebSocket 会话记录到本地 trace 存储；原始 SSE/WebSocket event 数组默认不写入，如果后续需要在查看器/导出结果中展示，必须在捕获时开启 --tap-store-stream-events
5. 退出时生成自包含的 HTML 查看器
6. 实时模式默认开启，并通过 SSE 向浏览器广播更新

核心特性: 🔒 常见认证 header 自动脱敏 · ⚡ 低开销流式转发 · 📦 自包含查看器 · 🔄 实时模式

社区

生态项目

• Phistory 会归档 Claude Code、Codex、Kimi、opencode、Pi 等 Agent CLI 的系统提示词版本快照。它基于 claude-tap 的 capture-only prompt export 能力，保留原始 HTTP trace 证据，并生成方便阅读和对比的 prompt 快照。

Star 历史

贡献者

感谢以下贡献者：

liaohch3 💻 📖 🚧 ⚠️	BKK 💻	YoungCan-Wang 💻	0xkrypton 💻	CYJiang 💻	陈展鹏 📖	devtalker 💻
Yaguang Ding 💻	Sephy 💻

许可证

MIT