记录 Claude Code、OpenCode、Codex-Cli 的 请求/响应 数据
摘要
-
记录 Claude Code、OpenCode、Codex CLI 以及通过独立正向代理接入的指定大模型端点 API 流量。在自包含 HTML 查看器中查看系统提示词、工具输出、思考块以及完整请求/响应数据。
-
mariozechner/claude-trace 的分支版本,扩展支持 Claude Code V2+ 原生二进制、独立的 OpenCode 命令(多 provider 拦截,Anthropic 与 OpenAI API 格式),以及 Codex CLI ChatGPT OAuth 追踪(通过 ChatGPT 账号登录 —— 多数用户的默认 Codex 认证方式)。
代理模式总览(正向代理 & 反向代理)
本项目同时支持 两种代理模式:
-
反向代理(内置工具封装):
claude-trace、opencode-trace、codex-trace会启动本地反向代理,并在启动目标工具时把其上游 base URL 重定向到代理(因此可以自动记录流量)。 -
正向代理(独立代理):
vibe-coding-proxy只启动 HTTP/HTTPS 正向代理,供会遵守HTTP_PROXY/HTTPS_PROXY/ALL_PROXY的客户端使用(已验证 Claude Code、OpenCode)。当前 Codex CLI 的模型请求不走这些环境变量,请改用codex-trace。使用前须在同一个 shell/session 中先导出代理变量。
支持的工具
| 工具 | CLI 命令 | 日志目录 | 拦截方式 |
|---|---|---|---|
| Claude Code | claude-trace |
.claude-trace/ |
V1:fetch() 钩子 · V2+:反向代理(ANTHROPIC_BASE_URL) |
| OpenCode | opencode-trace |
.opencode-trace/ |
反向代理 + 模型路由;支持 Anthropic 与 OpenAI 格式。仅支持 OpenCode 1.x,2.0+ 请用 vibe-coding-proxy + opencode --standalone |
| Codex CLI | codex-trace |
.codex-trace/ |
反向代理(CODEX_HOME 覆盖);ChatGPT OAuth 与 OpenAI API Key(Responses API) |
| 独立代理 | vibe-coding-proxy |
.vibe-coding-proxy/ |
正向代理(HTTP_PROXY / HTTPS_PROXY);仅 Claude Code 与 OpenCode。Codex 请用 codex-trace |
三条命令共用同一套 HTML 报告界面、JSONL/JSON 导出,以及 --index 会话摘要功能。
快速开始
1 | npm install -g @hanqunfeng/claude-trace |
会话结束后会自动在浏览器中打开最新 HTML 报告(可用 --no-open 关闭)。
安装
从 npm 安装
1 | npm install -g @hanqunfeng/claude-trace |
从源码安装
1 | git clone https://github.com/hanqunfeng/claude-trace.git |
Claude Code(claude-trace)
使用
1 | # 启动 Claude Code 并记录日志(自动识别 V1 JS / V2+ 原生二进制) |
日志路径:当前目录 .claude-trace/log-YYYY-MM-DD-HH-MM-SS.{jsonl,json,html}。
CLI 选项
| 参数 | 说明 |
|---|---|
--include-all-requests |
记录所有 API 流量,不仅限于 /v1/messages |
--include-sensitive-headers |
记录 auth token、cookie 等,不做脱敏 |
--log NAME |
自定义日志文件名(不含扩展名) |
--claude-path PATH |
Claude 二进制路径(省略则自动检测) |
--no-open |
生成 HTML 后不自动打开浏览器 |
--run-with ARGS... |
将后续参数传给 Claude |
--extract-token |
提取 OAuth token 后退出 |
--generate-html FILE [OUT] |
从 JSONL 生成 HTML 报告 |
--index |
生成会话摘要与索引 |
Claude Code V2+(原生二进制)
Claude Code V2 以原生二进制分发(macOS Mach-O / Linux ELF / Windows PE),不再是 Node.js 脚本。原有 node --require interceptor claude 方式已不可用。
| Claude Code 版本 | 二进制类型 | 拦截模式 |
|---|---|---|
| V1.x | Node.js 脚本 | 通过 --require 注入 interceptor-loader.js |
| V2+ | 原生二进制 | 本地反向代理;重定向 ANTHROPIC_BASE_URL |
流程:
-
在
127.0.0.1启动本地 HTTP 反向代理 -
通过
ANTHROPIC_BASE_URL将 Claude Code 指向代理 -
转发流量到真实上游(
~/.claude/settings.json或环境变量) -
实时写入
.claude-trace/
若 ~/.claude/settings.json 已设置 ANTHROPIC_BASE_URL,会使用持久化配置 overlay(~/.claude-trace/claude-config-overlay/):仅重写 settings.json 去掉该项,其余条目尽量通过符号链接指向原配置(Windows 目录用 junction,文件 symlink 失败则复制)。单项链接失败不会阻断启动,代理仍可用;跳过的条目仅在 CLAUDE_TRACE_DEBUG=1 时输出到 stderr。
第三方模型(CC-Switch 与自定义端点)
支持任何通过自定义 ANTHROPIC_BASE_URL 路由 Claude Code 的方案——CC-Switch、LiteLLM、企业网关、自托管代理等。
1 | Claude Code → claude-trace 代理(记录) → CC-Switch / 自定义端点 → 模型提供商 |
CC-Switch 示例:
1 | # CC-Switch 写入 ~/.claude/settings.json 后: |
手动指定上游:
1 | export ANTHROPIC_BASE_URL="https://your-gateway.example.com" |
注意事项:
-
上游需支持 Anthropic Messages API(
/v1/messages),或使用能转换为该格式的网关 -
API Key 及 settings 中的其他
env项会保留——仅在本地覆盖ANTHROPIC_BASE_URL -
HTML 日志会显示实际上游 URL 和每次请求的模型名
请求过滤(Claude)
代理模式(V2+): 默认 /v1/messages;--include-all-requests 记录所有代理流量。
拦截模式(V1,Node.js): 默认记录上下文中消息数 > 2 的 /v1/messages;--include-all-requests 记录所有 api.anthropic.com 请求。
OpenCode(opencode-trace)
使用
1 | # 启动 OpenCode TUI 并记录日志 |
日志路径:当前目录 .opencode-trace/log-YYYY-MM-DD-HH-MM-SS.{jsonl,json,html}。代理运行时错误追加写入 .opencode-trace/proxy-errors.log。
OpenCode 2.0+:
opencode-trace仅支持 OpenCode 1.x。OpenCode 2.0+ 只能使用独立正向代理(vibe-coding-proxy),并且需要用opencode --standalone启动 OpenCode。详见下方「OpenCode 2.x(仅支持正向代理)」一节。OpenCode 2.x 的安装见 opencode 2.x 的安装和使用。
OpenCode 2.x(仅支持正向代理)
OpenCode 2.x 的模型请求由共享的后台服务发出,而不是你启动的 opencode 进程。后台服务不会继承当前 shell 的环境变量,OPENCODE_CONFIG_CONTENT 也无法可靠生效,因此 opencode-trace 的反向代理无法重定向它的流量。
请改用 vibe-coding-proxy,并且始终用 --standalone 启动 OpenCode,让服务运行在当前进程内,从而读取到代理环境变量:
1 | # 终端 1:启动正向代理(替换为你实际使用的 provider 域名) |
-
不加
--standalone时,已在运行的后台服务会继续直连 provider,不会记录任何请求。 -
日志写入
.vibe-coding-proxy/,而不是.opencode-trace/。
拦截原理
OpenCode 为原生二进制。opencode-trace 启动本地反向代理,并通过 OPENCODE_CONFIG_CONTENT 注入运行时配置覆盖——不会修改原始 opencode.json。
配置中所有 provider 的 baseURL 均指向本地代理。代理从请求体读取 model 字段,映射到对应 provider 与真实上游 URL,再转发请求。支持 Anthropic(/v1/messages)与 OpenAI 格式(/v1/chat/completions、/v1/responses,即 @ai-sdk/openai-compatible 与 @ai-sdk/openai)。
1 | OpenCode → opencode-trace 代理(记录) → provider baseURL(DeepSeek、MiniMax 等) |
配置读取顺序:
-
环境变量
OPENCODE_CONFIG -
OPENCODE_CONFIG_DIR/opencode.json -
~/.config/opencode/opencode.json -
当前目录
.opencode/opencode.json
支持的 API 格式
OpenCode npm 包 |
API 格式 | 端点 | 对话视图标签 |
|---|---|---|---|
@ai-sdk/anthropic |
Anthropic Messages | /v1/messages |
Anthropic Messages |
@ai-sdk/openai-compatible |
OpenAI Chat Completions | /v1/chat/completions |
OpenAI Chat |
@ai-sdk/openai |
OpenAI Responses | /v1/responses |
OpenAI Responses |
代理从请求体读取 model 字段,路由到对应 provider 的 baseURL。同一 provider 下可通过 per-model npm 混用 chat 与 responses API。未在 opencode.json 中显式声明的模型,可通过 provider 级回退路由(providerId/*)匹配。
CLI 选项
| 参数 | 说明 |
|---|---|
--opencode-path PATH |
OpenCode 二进制路径(省略则自动检测) |
--include-all-requests |
记录所有代理流量,不仅限于 messages 端点 |
--include-sensitive-headers |
不脱敏记录 auth 头 |
--log NAME |
自定义日志文件名 |
--no-open |
不自动打开 HTML |
--run-with ARGS... |
传递给 OpenCode 的参数 |
调试
默认情况下运行时日志静默输出,避免污染 OpenCode TUI 输入框。
| 输出内容 | 默认行为 | 设置 OPENCODE_TRACE_DEBUG=1 后 |
|---|---|---|
| 每次请求路由(model → provider → 上游 URL) | 不输出 | 打印到 stderr |
| 代理错误(如上游 TLS 连接失败) | 写入 .opencode-trace/proxy-errors.log |
同时打印到 stderr |
1 | OPENCODE_TRACE_DEBUG=1 opencode-trace |
当模型未正确路由、日志缺少请求,或上游连接失败时,可使用此命令排查。
OpenCode 当前限制
-
对话视图支持 Anthropic 格式(
@ai-sdk/anthropic)与 OpenAI 格式(@ai-sdk/openai-compatible、@ai-sdk/openai)provider;复杂字段(多模态、reasoning 等)可能仅在 Raw/JSON 视图中完整展示。 -
尚未拦截未在
opencode.json中定义的内置models.devprovider。 -
opencode-trace不支持 OpenCode 2.0+;请使用vibe-coding-proxy并以opencode --standalone启动(见上方「OpenCode 2.x(仅支持正向代理)」一节)。
Codex CLI(codex-trace)
主要认证方式:ChatGPT OAuth。 若你通过 ChatGPT 账号登录 Codex(多数安装的默认方式),codex-trace 可完整追踪该路径 —— 多轮对话、zstd 压缩请求与 SSE 流式响应均能在 HTML 报告中正确展示。
用法
1 | # 启动 Codex TUI 并记录流量(支持 ChatGPT OAuth 或 API Key) |
日志路径:当前目录 .codex-trace/log-YYYY-MM-DD-HH-MM-SS.{jsonl,json,html}。
ChatGPT OAuth 模式(推荐)
多数用户通过 ChatGPT 登录 使用 Codex(codex login 或 TUI 内登录)。codex-trace 读取 ~/.codex/auth.json,当 auth_mode 为 "chatgpt" 时,将所有 LLM 流量路由到 ChatGPT OAuth 上游(chatgpt.com/backend-api/codex)——即使 shell 中为其他工具设置了 OPENAI_BASE_URL(如 Cursor、LiteLLM 等)也不受影响。
| 检查项 | 预期 |
|---|---|
| 认证文件 | ~/.codex/auth.json 含 "auth_mode": "chatgpt" |
| 会话数据 | 从真实 $CODEX_HOME symlink,OAuth token 不会被改写 |
| HTML 报告 | 多轮对话完整展示每条 assistant 回复,含最后一轮 |
1 | Codex CLI(ChatGPT OAuth) → codex-trace 代理(记录) → chatgpt.com/backend-api/codex |
提示: 请先完成 ChatGPT 登录,再启动 codex-trace。若在 trace 会话中途于 Codex 内切换认证方式,建议重新运行 codex-trace。
OpenAI API Key 模式
若使用 OpenAI API Key 而非 ChatGPT 登录,流量经 openai_base_url / OPENAI_BASE_URL / api.openai.com(或自定义网关)路由。请勿将 ChatGPT OAuth token 与自定义 OPENAI_BASE_URL 网关混用 —— 同一时间只应使用一种认证方式。
拦截原理
Codex CLI 为 Rust 原生二进制。codex-trace 启动本地反向代理,并在 ~/.claude-trace/codex-config-overlay/ 构建配置覆盖层——不会修改原始 ~/.codex/config.toml。
覆盖层将 openai_base_url、chatgpt_base_url 及自定义 model_providers.*.base_url 改写为代理地址。auth.json 与会话数据通过 symlink 保留,ChatGPT OAuth 可继续使用。代理根据 auth.json 的 auth 模式(ChatGPT OAuth 或 API Key)与请求路径选择上游:
-
ChatGPT OAuth(
auth_mode: "chatgpt"):/responses、/v1/responses、/backend-api/codex/...→chatgpt.com -
ChatGPT Apps MCP(
codex_apps):/api/codex/apps→chatgpt.com/backend-api/wham/apps;/backend-api/wham/...→chatgpt.com(站点根路径) -
OpenAI API Key:
/v1/responses、/responses→openai_base_url/OPENAI_BASE_URL/ 默认 OpenAI 主机 -
自定义
model_providers:非保留 provider id 且配置了base_url的条目
1 | Codex CLI → codex-trace 代理(记录) → chatgpt.com(OAuth)/ api.openai.com / 自定义 provider |
配置查找:CODEX_HOME(覆盖层)或 ~/.codex/config.toml。
CLI 选项
| 参数 | 说明 |
|---|---|
--codex-path PATH |
Codex 二进制路径(省略则自动检测) |
--include-all-requests |
记录所有代理流量,不仅限于 LLM API 路径 |
--include-sensitive-headers |
不脱敏记录认证头 |
--log NAME |
自定义日志文件名前缀 |
--no-open |
不自动打开 HTML |
--run-with ARGS... |
将后续参数传给 Codex |
Codex 限制
-
覆盖层强制
supports_websockets = false,确保 HTTP/SSE 流量可被记录。 -
内置 provider ID(
openai、ollama、lmstudio)不能通过model_providers覆盖;ChatGPT OAuth 使用chatgpt_base_url,API Key 模式使用openai_base_url。 -
Ollama / LM Studio 内置 provider 不会被拦截(流量绕过代理)。
-
旧版
auth.json若无auth_mode字段,会回退到旧启发式;若 OAuth 路由异常,请重新用 ChatGPT 登录。 -
Node.js: Codex ChatGPT OAuth 追踪在 Node.js 16+ 即可正常使用(代理原样转发 zstd 体)。建议 Node.js 22+,以便在日志与 HTML 中解压展示 zstd 压缩的请求体和响应体(例如 OpenCode 收到的
content-encoding: zstdSSE);Node 16–21 下这些条目会显示占位符而非解析后的内容(代理转发不受影响)。
独立正向代理(vibe-coding-proxy)
vibe-coding-proxy 只启动代理服务,不启动 Claude Code、OpenCode 或其他客户端。会遵守 HTTP_PROXY、HTTPS_PROXY 或 ALL_PROXY 的 CLI 可以把流量指到启动后打印的代理 URL。
兼容性与使用顺序
-
已测试通过的客户端:Claude Code、OpenCode。不支持 Codex CLI:当前 Codex 在未配置系统代理时会直连
base_url,忽略上述环境变量,模型请求不会进入本代理。记录 Codex 请使用codex-trace。其他会遵守这些环境变量的客户端理论上可用,但尚未测试。 -
必须先设环境变量再启动:先启动
vibe-coding-proxy→ 在同一个 shell/session 里导出环境变量 → 再启动客户端/工具。若先启动客户端,它可能不会读取到新的代理设置。 -
OpenCode 2.0+:这是记录 OpenCode 2.x 的唯一方式。必须用
opencode --standalone启动。
用法
1 | # 记录指定 DeepSeek Anthropic 兼容端点 |
启动后导出打印的代理 URL:
1 | export HTTP_PROXY=http://127.0.0.1:PORT |
日志路径:当前目录 .vibe-coding-proxy/log-YYYY-MM-DD-HH-MM-SS.{jsonl,json,html}。
HTTPS 记录与 CA 信任
通过 HTTPS_PROXY 发送的 HTTPS 请求通常先发起 CONNECT host:443,代理无法直接看到 JSON body。为了记录请求/响应 body,vibe-coding-proxy 只会对 --target-url / --mitm-host allowlist 命中的目标执行 MITM,并打印本地 CA 证书路径。
只应在你希望检查模型流量的客户端中信任该 CA。命令不会自动把 CA 安装到系统信任链。NODE_TLS_REJECT_UNAUTHORIZED=0 只对 Node.js 客户端有效。未命中 allowlist 的 HTTPS 流量会作为原始 CONNECT 隧道透传,仅在开启 --include-all-requests 时记录元数据。
本地 CA 生命周期
本地 CA 默认复用 ~/.claude-trace/vibe-coding-proxy-ca/,除非你传入 --ca-dir。ca.crt 有效期为 10 年;按主机缓存的 leaf 证书(如 api.deepseek.com.crt.pem)有效期为 1 年。leaf 证书过期会自动重签。CA 过期时会重新生成,并清理所有旧 leaf 证书;此时需要重新信任新的 CA。
CLI 选项
| 参数 | 说明 |
|---|---|
--target-url URL |
解密并完整记录的 URL 前缀(可重复) |
--mitm-host HOST |
解密并完整记录的主机名(可重复) |
--host HOST |
监听地址(默认 127.0.0.1) |
--port PORT |
监听端口(默认 0,随机) |
--log-dir DIR |
日志目录(默认 .vibe-coding-proxy) |
--log NAME |
自定义日志文件名前缀 |
--ca-dir DIR |
本地 CA 与 leaf 证书缓存目录 |
--no-mitm |
禁用 TLS MITM;HTTPS CONNECT 仅透传 |
--include-all-requests |
记录透传 CONNECT 元数据与非目标 HTTP 流量 |
--include-sensitive-headers |
不脱敏记录认证头 |
--no-open |
退出时不自动打开 HTML |
--generate-html FILE [OUT] |
从 JSONL 生成 HTML 报告 |
共用功能
HTML 报告
每次会话生成自包含 HTML 文件(内嵌 CSS/JS),可离线打开。退出时默认自动打开浏览器,可用 --no-open 关闭。
你将看到的内容
-
系统提示词 — 发送给模型的隐藏指令
-
工具定义与输出 — 参数及原始工具结果
-
思考块 — 内部推理过程(如有)
-
Token 用量 — 含缓存命中的详细统计
-
原始 JSONL 日志 — 完整请求/响应对
-
交互式查看器 — 对话、原始 HTTP、JSON 调试等视图
-
API 格式标签 — 每个会话头部显示请求格式(如
8 messages · OpenAI Chat)
会话索引
1 | claude-trace --index |
扫描日志文件,通过 Claude CLI 为有意义会话生成摘要,并输出可搜索的 index.html。注意: 索引会产生额外 API token 消耗。
环境要求
-
Node.js 16+(Codex OAuth 请求体完整日志展示建议 Node.js 22+)
-
Claude Code CLI(V1 Node.js 或 V2+ 原生二进制),用于
claude-trace -
OpenCode CLI,用于
opencode-trace -
Codex CLI,用于
codex-trace
开发
1 | npm run setup # 首次安装 |
架构
后端(src/):
-
CLI(
cli/cli.ts、cli/opencode-cli.ts、cli/codex-cli.ts、cli/cli-common.ts)— 薄入口与共用参数解析 -
Trace Runner(
cli/trace-runner.ts)— 通用启动与代理/拦截器分发 -
Tool Profiles(
tools/claude.ts、tools/opencode.ts、tools/codex.ts、tools/binary-utils.ts)— 各工具配置、二进制检测、上游解析 -
Config Overlays(
config/claude-config-overlay.ts、config/codex-config-overlay.ts)— 持久化代理覆盖层,不修改用户原始配置 -
Reverse Proxy(
intercept/reverse-proxy.ts)— 原生二进制拦截,实时 HTML 生成 -
Interceptor(
intercept/interceptor.ts)+ Loader(intercept/interceptor-loader.js、intercept/token-extractor.js)— Claude Code V1 -
Routing(
routing/proxy-routing.ts、routing/codex-routing.ts)— OpenCode 模型路由与 Codex 路径/auth 上游选择 -
API Format(
adapt/api-format.ts)— 格式检测与展示标签 -
OpenAI Adapter(
adapt/openai-adapter.ts)— OpenAI 请求/响应适配为 AnthropicMessage,供查看器展示 -
Report(
report/html-generator.ts、report/index-generator.ts、report/shared-conversation-processor.ts)— HTML 生成与会话解析
前端(frontend/src/):Lit + Tailwind 交互查看器,嵌入 HTML 报告。
文档
维护者与贡献者文档位于仓库 doc/:
| 文档 | 说明 |
|---|---|
| doc/publishing/oidc.md | 推荐的 GitHub Actions OIDC npm 发布流程 |
| doc/publishing/access-token.md | 使用 npm Access Token 的本地发布(旧方式) |
| doc/github-actions-workflow-guide.md | GitHub Actions 工作流详解与示例 |
| doc/npm-v12-security-changelog.md | npm v12 安装安全策略与 GAT 弃用说明 |
许可证
MIT — 原作者 Mario Zechner,由 @hanqunfeng/claude-trace 维护。