/README_zh.md

# claude-tap

[![PyPI version](https://img.shields.io/pypi/v/claude-tap.svg)](https://pypi.org/project/claude-tap/)
[![PyPI downloads](https://img.shields.io/pypi/dm/claude-tap.svg)](https://pypi.org/project/claude-tap/)
[![Python version](https://img.shields.io/pypi/pyversions/claude-tap.svg)](https://pypi.org/project/claude-tap/)
[![License](https://img.shields.io/github/license/liaohch3/claude-tap.svg)](https://github.com/liaohch3/claude-tap/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/liaohch3/claude-tap?style=social)](https://github.com/liaohch3/claude-tap/stargazers)
[![All Contributors](https://img.shields.io/badge/all_contributors-9-orange.svg)](#贡献者)

[English](README.md)

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

网站：[本地 AI Agent Trace Viewer](https://liaohch3.com/claude-tap/) · 指南：[如何本地查看 Agent traces](docs/guides/agent-trace-viewer.zh.md)

它支持 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex CLI](https://github.com/openai/codex)、[Codex App](https://openai.com/codex/)、[Gemini CLI](https://github.com/google-gemini/gemini-cli)、[Kimi CLI](https://github.com/MoonshotAI/kimi-cli)、[MiMo Code](https://mimo.xiaomi.com/en/mimocode)、[OpenCode](https://opencode.ai)、[OpenClaw](https://github.com/openclaw/openclaw)、[Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)、[Hermes Agent](https://github.com/NousResearch/hermes-agent)、[Cursor CLI](https://cursor.com/cli)、[Qoder CLI](https://qoder.com/cli)、[Antigravity CLI](https://antigravity.google/product/antigravity-cli) 和 [CodeBuddy CLI](https://www.codebuddy.ai)。

<p align="center">
  <img src="docs/demo_zh.gif" alt="claude-tap 演示：真实 Codex trace" width="100%">
  <br>
  <sub>打开一次真实 agent 运行，检查每个请求，并对比上下文如何在多轮之间变化。</sub>
</p>

<table>
  <tr>
    <td width="33%" align="center">
      <img src="docs/viewer-zh.png" alt="亮色模式 trace 查看器" width="100%">
      <br>
      <sub>亮色模式总览</sub>
    </td>
    <td width="33%" align="center">
      <img src="docs/viewer-dark.png" alt="暗色模式 trace 查看器" width="100%">
      <br>
      <sub>适合长时间 review 的暗色模式</sub>
    </td>
    <td width="33%" align="center">
      <img src="docs/diff-modal.png" alt="结构化 Diff 弹窗" width="100%">
      <br>
      <sub>相邻请求之间的结构化 Diff</sub>
    </td>
  </tr>
</table>

## 使用 claude-tap 构建

<table>
  <tr>
    <td width="55%">
      <strong><a href="https://github.com/WEIFENG2333/phistory">Phistory</a></strong> 会归档 Claude Code、Codex、Kimi、opencode、Pi 等 Agent CLI 的系统提示词版本快照。它基于 claude-tap 的 capture-only prompt export 能力，保留原始 HTTP trace 证据，并生成方便阅读和对比的 prompt 快照。
      <br><br>
      <a href="https://phistory.cc/">打开 prompt diff 查看器</a> · <a href="https://github.com/WEIFENG2333/phistory">查看仓库</a>
    </td>
    <td width="45%" align="center">
      <a href="https://phistory.cc/">
        <img src="https://raw.githubusercontent.com/WEIFENG2333/phistory/main/docs/screenshot.png" alt="Phistory prompt diff 查看器" width="420">
      </a>
    </td>
  </tr>
</table>

## 为什么用它

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

## 支持的客户端

| 客户端 | 典型用途 |
|--------|----------|
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Anthropic API、AWS Bedrock、DeepSeek / GLM 等 Claude 兼容网关，或 CC Switch 等本地代理上游 |
| [Codex CLI](https://github.com/openai/codex) | OpenAI API 密钥模式，或 ChatGPT 订阅 OAuth |
| [Codex App](https://openai.com/codex/) | 从 `CODEX_HOME` 或 `~/.codex` 导入本地 Codex App 会话；自动尽力补充 CDP WebSocket 证据 |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Google OAuth / Code Assist 的多 Google 端点流量 |
| [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | 旧版 kimi-cli 和新版 Kimi Code CLI |
| [MiMo Code](https://mimo.xiaomi.com/en/mimocode) | MiMo Code 会话（基于 OpenCode 的多提供方 fork） |
| [OpenCode](https://opencode.ai) | 多提供方 OpenCode 会话 |
| [OpenClaw](https://github.com/openclaw/openclaw) | 多提供方 OpenClaw 会话 |
| [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) | Pi 会话，包括 OpenAI Codex OAuth 提供方 |
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | 多提供方 Hermes TUI 或 gateway 会话 |
| [Cursor CLI](https://cursor.com/cli) | Cursor Agent 会话，并导入可读的本地 transcript |
| [Qoder CLI](https://qoder.com/cli) | 通过 forward proxy 捕获 Qoder Agent 会话 |
| [Antigravity CLI](https://antigravity.google/product/antigravity-cli) | 通过 forward proxy 捕获 Antigravity Agent 会话 |
| [CodeBuddy CLI](https://www.codebuddy.ai) | 腾讯 CodeBuddy SaaS 或内部 Copilot 端点 |

## 安装

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

```bash
# 推荐
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` 启动你想观察的客户端。`--` 后面的参数会透传给所选客户端。

```bash
# 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"

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

<details>
<summary>Claude Code 更多示例</summary>

```bash
# 透传参数给 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](https://github.com/farion1231/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` 路径。

</details>

<details>
<summary>Claude Code + DeepSeek API</summary>

完整中文指南见 [Claude Code 搭配 DeepSeek API](docs/guides/deepseek-claude-code.zh.md)，英文版见 [Claude Code with DeepSeek API](docs/guides/deepseek-claude-code.md)。

```bash
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
```

```bash
claude-tap -- --permission-mode bypassPermissions
```

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

</details>

<details>
<summary>Claude Code + AWS Bedrock</summary>

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

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

```bash
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）**

```bash
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 签名请求）**

```bash
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`。

</details>

<details>
<summary>Claude Code + Google Vertex AI</summary>

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

```bash
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 模式有单一上游可转发。

</details>

<details>
<summary>Codex CLI 认证方式和示例</summary>

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`。

```bash
# 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
```

</details>

<details>
<summary>Codex App 监听示例</summary>

Codex App 会话会从 `CODEX_HOME/sessions` 或 `~/.codex/sessions` 下的本地 JSONL 文件导入。这个模式不会启动 Codex，也不会创建网络代理；它会保持一个 claude-tap dashboard session，并在 Codex App 运行中或完成后追加可查看的记录。

```bash
# 监听本地 Codex App 会话，并在 dashboard 中查看
claude-tap --tap-client codexapp

# 使用自定义 Codex home 目录
CODEX_HOME=/path/to/codex-home claude-tap --tap-client codexapp
```

`--tap-client codexapp` 会自动导入本地 transcript，并在 Codex App debug endpoint 可用时静默补充 CDP WebSocket 证据。CDP capture 是旁路观测，不是代理；如果前端没有通过 Chrome DevTools Protocol 暴露模型流量，Codex App 复盘仍以本地 session transcript 为准。

</details>

<details>
<summary>Kimi CLI 示例</summary>

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

```bash
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
```

</details>

<details>
<summary>Gemini CLI 示例</summary>

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

```bash
# 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"
```

</details>

<details>
<summary>OpenCode 示例</summary>

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

```bash
# 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
```

</details>

<details>
<summary>MiMo Code 示例</summary>

[MiMo Code](https://mimo.xiaomi.com/en/mimocode) 是 [OpenCode](https://opencode.ai) 的 fork，增加了持久化记忆、子 agent 编排和小米 MiMo 平台集成。claude-tap 默认对 mimocode 使用 **forward proxy** 模式——向子进程注入 `HTTPS_PROXY` 与本地 CA，捕获它对接的任意 provider 流量。

```bash
# 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
```

</details>

<details>
<summary>Pi 示例</summary>

[Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) 是一个多 provider coding agent。因为 Pi 可以使用 `openai-codex` 这类订阅 OAuth provider，也可以使用模型注册表中的自定义 API-key provider，claude-tap 默认对 Pi 使用 **forward proxy** 模式。

```bash
# 通过 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`。

</details>

<details>
<summary>Hermes Agent 示例</summary>

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 流量。

```bash
# 交互式 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。

</details>

<details>
<summary>Cursor CLI 示例</summary>

Cursor CLI 默认使用 forward proxy。免费套餐建议传 `--model auto`；需要工具调用时不要加 `--mode ask`。

```bash
claude-tap --tap-client cursor -- -p --trust --model auto "hello"
claude-tap --tap-client cursor -- -p --trust --model auto --continue "continue"
```

</details>

## 集成与指南

- [OpenClaw 设置指南](docs/guides/OPENCLAW_README.zh.md)：在 OpenClaw 中集成 `claude-tap`。英文版见 [OpenClaw setup guide](docs/guides/OPENCLAW_README.md)。
- [Claude Code 搭配 DeepSeek API](docs/guides/deepseek-claude-code.zh.md)：让 Claude Code 走 DeepSeek 的 Anthropic 兼容 API。英文版见 [Claude Code with DeepSeek API](docs/guides/deepseek-claude-code.md)。
- [客户端支持矩阵](docs/support-matrix.md)：查看各客户端对应的环境变量、代理模式和 URL 改写规则。

<details>
<summary>Qoder CLI 示例</summary>

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

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

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

</details>

<details>
<summary>Antigravity CLI 示例</summary>

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。

```bash
claude-tap --tap-client agy --tap-live

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

</details>

<details>
<summary>CodeBuddy CLI 示例</summary>

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

```bash
# 自动识别上游（登录后四种登录方式都适用）
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"
```

</details>

<details>
<summary>查看器、导出和高级选项</summary>

```bash
# 客户端运行时默认启动实时查看器
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 或代理配置指向本地代理。具体接法见 [客户端支持矩阵](docs/support-matrix.md)。

作为 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 / gemini / 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/kimi/kimi-code/openclaw/codebuddy 用 reverse，agy/gemini/mimo/opencode/pi/hermes/cursor/qoder 用 forward；codexapp 是 transcript-only）
--tap-trust-ca           macOS 上显式把本地 CA 信任到当前用户 login keychain（agy 会自动执行）
```

</details>

## 查看器功能

### 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, Русский

## 架构

![架构图](docs/architecture.png)

<details>
<summary>工作原理</summary>

**工作原理:**

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 自动脱敏 · ⚡ 低开销流式转发 · 📦 自包含查看器 · 🔄 实时模式

</details>

## 社区

### 生态项目

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

### Star 历史

<a href="https://www.star-history.com/?repos=liaohch3%2Fclaude-tap&type=date&legend=bottom-right">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=liaohch3/claude-tap&type=date&theme=dark&legend=top-left" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=liaohch3/claude-tap&type=date&legend=top-left" />
    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=liaohch3/claude-tap&type=date&legend=top-left" />
  </picture>
</a>

### 贡献者

感谢以下贡献者：

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<table>
  <tbody>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/liaohch3"><img src="https://avatars.githubusercontent.com/u/34056481?s=100" width="100px;" alt="liaohch3"/><br /><sub><b>liaohch3</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=liaohch3" title="Code">💻</a> <a href="https://github.com/liaohch3/claude-tap/commits?author=liaohch3" title="Documentation">📖</a> <a href="#maintenance-liaohch3" title="Maintenance">🚧</a> <a href="https://github.com/liaohch3/claude-tap/commits?author=liaohch3" title="Tests">⚠️</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/WEIFENG2333"><img src="https://avatars.githubusercontent.com/u/61730227?s=100" width="100px;" alt="BKK"/><br /><sub><b>BKK</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=WEIFENG2333" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/YoungCan-Wang"><img src="https://avatars.githubusercontent.com/u/73347006?s=100" width="100px;" alt="YoungCan-Wang"/><br /><sub><b>YoungCan-Wang</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=YoungCan-Wang" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/oxkrypton"><img src="https://avatars.githubusercontent.com/u/154910746?s=100" width="100px;" alt="0xkrypton"/><br /><sub><b>0xkrypton</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=oxkrypton" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/googs1025"><img src="https://avatars.githubusercontent.com/u/86391540?s=100" width="100px;" alt="CYJiang"/><br /><sub><b>CYJiang</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=googs1025" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/TITOCHAN2023"><img src="https://avatars.githubusercontent.com/u/138754853?s=100" width="100px;" alt="陈展鹏"/><br /><sub><b>陈展鹏</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=TITOCHAN2023" title="Documentation">📖</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/devtalker"><img src="https://avatars.githubusercontent.com/u/23204195?s=100" width="100px;" alt="devtalker"/><br /><sub><b>devtalker</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=devtalker" title="Code">💻</a></td>
    </tr>
    <tr>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/dingyaguang117"><img src="https://avatars.githubusercontent.com/u/1930778?s=100" width="100px;" alt="Yaguang Ding"/><br /><sub><b>Yaguang Ding</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=dingyaguang117" title="Code">💻</a></td>
      <td align="center" valign="top" width="14.28%"><a href="https://github.com/sephymartin"><img src="https://avatars.githubusercontent.com/u/299891?s=100" width="100px;" alt="Sephy"/><br /><sub><b>Sephy</b></sub></a><br /><a href="https://github.com/liaohch3/claude-tap/commits?author=sephymartin" title="Code">💻</a></td>
    </tr>
  </tbody>
</table>

<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->

<!-- ALL-CONTRIBUTORS-LIST:END -->

## 许可证

MIT