claude-tap

本地拦截 AI 编程代理流量，可视化调试每个 API 调用

claude-tap 是一个面向 AI 编程代理的本地流量拦截与调试工具。它通过本地代理服务器捕获 Claude Code、Codex CLI、Gemini CLI、Cursor CLI、OpenCode、Kimi Code 等主流编码代理的 API 请求和响应，并在内置的 trace 查看器中可视化展示。该项目解决了 AI 编程代理黑盒化带来的调试难题，让开发者能直观看到代理与模型之间的完整交互内容，包括提示词、工具调用、模型输出等。核心能力包括：一键启动本地代理、自动配置环境变量、支持多代理无缝接入、提供清晰的请求/响应时间线视图、支持搜索过滤和详情展开。通过拦截流量，开发者可以深入理解代理行为、定位 prompt 设计问题、分析工具调用错误，从而提升 AI 编程的效率和可控性。项目用 Python 实现，安装简单，适合个人开发者和团队在本地开发环境中使用。

开源 free 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 3235

维护状态活跃

是否开源是

定价模式 free

项目数据

分类智能体

开发团队liaohch3

所属国家

官网地址

GitHubhttps://github.com/liaohch3/claude-tap

定价模式free

价格说明开源项目，MIT 许可证，本地部署使用，完全免费。

访问状态

是否开源是

开源协议MIT

主要语言Python

技术栈/模型agent-debugging,agent-observability,ai-agents,ai-tools,api-debugging,claude-code,codex,codex-cli,cursor-cli,developer-tools,gemini-cli,hermes-agent,kimi,llm,llm-proxy,opencode,pi-coding-agent,proxy,trace,trace-viewer

GitHub 星标★ 3235

30天Star增速

HF 下载量

上线时间2026-02-15 00:00:00

最近更新2026-09-23 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数2

使用教程

难度：入门约 10 分钟部署方式：命令行工具 6 步

⚠ 该项目 README 未提供完整安装说明，以下步骤为通用流程，请以官方文档为准。

环境要求

Python 3.11+
已安装并登录你要追踪的编码代理客户端（Claude Code、Codex CLI、Gemini CLI、Kimi CLI、CodeBuddy 等）
DeepSeek Harness 正向代理模式需要 Node 支持 --use-env-proxy
能访问对应模型服务端点的网络环境

安装与启动步骤

1准备运行环境

确认本机 Python 版本达到 3.11+，并已安装好你要追踪的那个编码代理客户端。
```
python3 --version
```
2安装 claude-tap

节选的 Install 部分未给出具体安装命令，请按项目 README/官网的说明安装 claude-tap 并确保命令可用。
3启动代理与查看器

直接运行会在客户端运行时默认拉起 Live viewer；若只想先起代理，可加 --tap-no-launch。
```
claude-tap
```
4指定要追踪的客户端

用 --tap-client 选择客户端类型，-- 之后的参数会原样传给该客户端，例如 --thinking。
```
claude-tap --tap-client kimi -- --thinking
```
5指向自定义上游

客户端走自建或兼容网关时，用 --tap-target 指定上游地址，代理会转发并记录该端点流量。
```
claude-tap --tap-client kimi --tap-target https://api.moonshot.ai/v1
```
6仅启动代理

用 --tap-no-launch 跳过拉起客户端，并用 --tap-port 指定监听端口，方便你自己配置客户端接入。
```
claude-tap --tap-no-launch --tap-port 8080
```

关键配置

配置项	必填	说明	示例
`--tap-client`	是	选择要拦截的客户端，如 codexapp、kimi、kimi-code、grok、dsh、codebuddy	`--tap-client kimi`
`--tap-target`	否	指定代理转发的上游 API 地址	`https://api.moonshot.ai/v1`
`--tap-proxy-mode`	否	切换反向/正向代理模式，部分客户端默认反向	`reverse`
`--tap-port`	否	设置代理监听端口，常与 --tap-no-launch 搭配	`8080`
`CODEX_APP_EXECUTABLE`	否	Codex/ChatGPT App 装在非默认位置时覆盖可执行文件路径	`/path/to/ChatGPT.app/Contents/MacOS/ChatGPT`
`GROK_CLI_CHAT_PROXY_BASE_URL`	否	指定 Grok 兼容部署的网关地址	`https://grok-gateway.example.com/v1`

如何确认成功

启动后默认拉起 Live viewer，在查看器中能看到客户端的请求/响应时间线、系统提示词与工具调用即成功。

常见问题

Q：客户端装在非默认路径怎么办？

A：用环境变量覆盖可执行文件路径，例如 CODEX_APP_EXECUTABLE=/path/to/ChatGPT.app/Contents/MacOS/ChatGPT claude-tap --tap-client codexapp。

Q：Codex/ChatGPT App 已经在运行会冲突吗？

A：不会。claude-tap 会启动隔离的第二实例，使用 ~/.claude-tap/codex-app-profiles/tap 作为独立的 user-data-dir，原窗口可继续使用，但被追踪窗口可能需要重新登录。

Q：怎么把参数传给被追踪的客户端？

A：把参数放在 -- 之后即可原样传递，例如 claude-tap --tap-client kimi -- --thinking。

Q：Gemini CLI 该用哪种代理模式？

A：默认使用正向代理，因为 Google OAuth / Code Assist 流量会发往多个 Google 端点；只有遵守 GOOGLE_GEMINI_BASE_URL 或 GOOGLE_VERTEX_BASE_URL 的 API key、Vertex 流程才适合反向模式。

Q：DeepSeek Harness 提示 Node 能力不可用？

A：正向代理模式要求 Node 支持 --use-env-proxy，请升级 Node，或改用反向模式配合环境变量中配置好的端点，例如 --tap-proxy-mode reverse。

注意事项

节选内容中 Install 部分为空，未给出安装命令，执行前请以官方 README 或官网确认安装方式。
-- 之后的参数会原样传给被选中的客户端，不要在其中混入 claude-tap 自身的参数。
--tap-client codexapp 模式记录的是实时后端流量，而不是导入本地会话 JSONL 记录。
Kimi 旧版用 --tap-client kimi，新版 Kimi Code 用 --tap-client kimi-code，两者默认都走反向代理模式。

核心亮点

支持 8+ 主流编码代理（Claude Code、Codex、Gemini CLI 等），覆盖面广
本地代理方式无需修改代理代码，即插即用，环境变量自动配置
内置 trace 查看器提供请求/响应时间线，支持搜索和详情展开，调试体验直观

不足之处

仅支持本地查看，缺少远程或团队协作分享功能
文档/社区待观察

适用场景

调试 Claude Code 或 Codex 的 prompt 设计，查看实际发送给模型的提示词
分析代理工具调用失败原因，定位 API 请求参数或响应错误
对比不同编码代理的 API 调用行为，优化选型或成本控制

替代项目

OpenAI Tracing、LangSmith、AgentOps

项目介绍

claude-tap 是基础设施领域的开源项目，由 liaohch3 开发，是 2026 年新上线的项目。

在全站 13,014 个收录项目中，它的 GitHub 星标数（3,235）位列前 30%，在基础设施分类中处于中上游。

近 45 天，它的 GitHub 星标从 2,990 增加到 3,235，净增 245。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-23。MIT 许可证，本地部署使用，完全免费。

它主要面向的使用场景是：调试ClaudeCode或Codex的prompt设计，查看实际发送给模型的提示词。同类可对比的替代方案包括 OpenAI Tracing、LangSmith、AgentOps。

上一篇：dolt

下一篇：arcbox