ccxray
给 AI Agent 会话装上 X 光：零配置代理记录 Claude Code / Codex 的每一次 API 调用，让黑盒变成透明玻璃盒。
- Star 数
- ★ 295
- 最近更新
- 2 天前
- License
- NOASSERTION
- 主语言
- JavaScript
- FA 评分
- 73/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Claude Code · Claude APICodex · OpenAI API（部分支持）
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 开发者想弄清 Claude Code 为什么思考 30 秒、哪些工具调用花钱、系统提示词在版本间改了什么
- 不适合
- 需要商业用途或闭源分发的团队——PolyForm 非商业许可禁止商用
- 需要把日志送到 S3/R2 等远程对象存储的团队——目前仅支持本地文件系统
- 对 Codex 会话细节要求完整可靠的团队——Codex 支持仍为 Beta，部分大事件只存为计时锚点
- 源码审查
- 73/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
ccxray 是一个零配置的本地 HTTP 透明代理与实时仪表盘，拦截并记录 Claude Code、Codex、Grok CLI 与上游 API 之间的每一次请求和响应。启动 npx ccxray claude 后，代理在 5577 端口启动，CLI 流量经由它转发，日志以 JSON 形式存入 ~/.ccxray/logs/，仪表盘在同一端口提供时间线、成本、系统提示词版本追踪等视图。多个终端可自动共享同一 Hub，会话中断后数秒内自动恢复。它还支持请求拦截编辑、上下文 HUD、缓存 TTL 倒计时警报和星标永久保留等功能。许可为 PolyForm Noncommercial 1.0.0，仅限非商业用途。
ccxray 以透明 HTTP 代理方式运行：CLI 通过 npx ccxray claude / codex / grok 启动，流量经 :5577 转发至 api.anthropic.com、api.openai.com/ChatGPT 或 cli-chat-proxy.grok.com，同时把请求和响应写成 {timestamp}_req.json / {timestamp}_res.json 存入 ~/.ccxray/logs/。仪表盘在同端口提供 Workflow Timeline（多 Agent 并行车道可视化）、每回合成本与 token 明细、系统提示词版本 diff、缓存 TTL 倒计时警报、按账户的 5 小时/每周配额卡片，以及 ccxray usage -- 等 CLI 分析命令。可开启拦截模式，在请求到达上游前暂停并编辑系统提示词、消息、工具或采样参数，再选择放行或拒绝。日志保留默认 14 天（LOG_RETENTION_DAYS），星标项永久保留。
- 开发者想弄清 Claude Code 为什么思考 30 秒、哪些工具调用花钱、系统提示词在版本间改了什么
- 团队管理者需要按账户查看 Claude/Codex 的 5 小时和每周配额消耗与真实支出
- 提示词工程师需要在真实请求到达 API 前修改系统提示词或工具定义做实验
- 多项目并行工作者在多个终端运行会话，想在同一个仪表盘里集中查看所有项目
- 重度多 Agent 用户想通过并行车道图看清 orchestrator 与 subagent 的并发结构
如何安装或部署这个 Agent？
需要 Node.js 18+，无独立安装步骤，直接用 npx 运行：
bash
npx ccxray claude首次运行会创建 ~/.ccxray/ 目录（日志、设置、local-secret 鉴权密钥）。也可用 Docker：
bash
docker build -t ccxray .
docker run -p 5577:5577 ccxray要接入 Herdr，可执行：
bash
herdr plugin install lis186/ccxray/plugins/herdr如何使用这个 Agent？
bash
npx ccxray claude # 启动代理并打开仪表盘
npx ccxray codex exec "hello" # 透传任意 codex 参数
npx ccxray --port 8080 claude # 独立端口，不共享 Hub
ccxray status # 查看 Hub 与已连接客户端
ccxray usage -- --last 7d # 生成供 Agent 使用的 JSON 用量报告
ccxray usage --session costliest --open # 跳转到最贵会话
代理启动后仪表盘自动在浏览器打开 http://localhost:5577。多个终端运行会自动共享同一 Hub。可用环境变量如 CCXRAY_PLAN、ANTHROPIC_BASE_URL、LOG_RETENTION_DAYS 等调整行为；在仪表盘顶部栏可开启 Intercept 拦截模式或 Context HUD。
这个 Agent 有哪些优点和局限？
- 零配置：一条 npx 命令即同时获得代理、日志与实时仪表盘，无需改环境变量
- 多 Agent 并行车道可视化与顺序/并发交错追踪，是少见的会话级结构视图
- 可拦截并编辑即将发出的请求，用于提示词实验和风险工具调用沙箱
- ccxray usage CLI 可在 0.6 秒内直接读 index.nd 产出 agent 可用的 JSON 报告，不依赖服务器
- 星标机制可保护关键回合免受 14 天自动清理，状态服务端持久
- PolyForm Noncommercial 1.0.0 许可禁止商业使用
- Codex 支持为 Beta，WebSocket 逐帧解码使部分大事件仅存时间锚点，细节不如 Claude 路径完整
- 日志仅存本地文件系统，尚不支持 S3/R2 等远程对象存储
- Grok 代理会用 CLI 的 token 调用 /v1/billing 接口填充账户卡片，可能涉及额外的上游调用
- Context HUD 在父 Agent 调用 sub-agent 时可能截断子 Agent 响应导致静默数据丢失，需手动关闭
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| ccxray 当前 | 73 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 295 | 2 天前 | JavaScript | Claude Code · Claude API |
| ccusage | 67 · 存在缺口 | — | ★ 19k | 今天 | Rust | Codex · Claude Code |
| Claude Tap 本地追踪器 | 53 · 缺口较多 | 命令行工具免费 | ★ 3.3k | 5 天前 | Python | Codex · Claude Code · OpenAI API · Claude API |
| ccglass | 74 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 851 | 14 天前 | JavaScript | Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：本地回环代理、单一运行时依赖（ws）、未知 provider 即刻失败、认证采用一次性 bootstrap token + HttpOnly/SameSite=Strict cookie，并有测试覆盖重放与跨站拒绝。扣分项：回环默认免认证（SECURITY.md 自述这不是认证边界）、代理以明文 JSON 记录完整提示词与上游流量、Grok 路径会用同一 auth token 额外调用计费端点（已披露但属额外外呼）、无版本回滚路径、日志自动 prune 依赖用户主动 star 保护。
证据显示：CI 在隔离 CCXRAY_HOME 下跑 Node 20/22 测试矩阵，count_tokens 误录修复有端到端回归测试，auth 模块有细致的拒绝路径测试；未知 provider 明确快速失败。扣分项：hub 崩溃自动恢复仅由 README 断言、无对应源码或测试佐证；部分文档（usage.md、CHANGELOG、CLAUDE.md）被引用但未在证据集中。
证据显示：明确面向 Claude Code/Codex/Grok 开发者的调试与成本观测场景，多项目 hub 共享、Docker、企业代理、自定义上游均有覆盖。扣分项：Codex 支持自标 Beta 且保真度低于 Claude 路径；天气功能因已知缺陷默认关闭；仅覆盖列出的三个 provider 命令。
证据显示：三语 README、完整 PolyForm Noncommercial 许可文本且与 package. 一致、版本号 2.3.1 双向吻合、安装与配置表完整、SECURITY.md 提供报告渠道并自述单人维护。扣分项：CHANGELOG 被引用但未在证据中出现，无法核实变更记录质量；无正式治理或多人维护机制。
证据显示：产品本身就是透明化层，解决 Claude Code 黑盒这一真实空白；提供时间线、成本核算、usage CLI（含 <4KB JSON 契约与模式文档）、键盘导航与深链接。扣分项：Context HUD 在多代理场景可能截断 sub-agent 返回（文档已承认），代理路径增加一跳与本地存储开销，代价需要用户自行权衡。
证据显示：测试直接对应 #486 修复、count_tokens 噪声抑制、auth bootstrap 回归；CI 审计分离 job 有具体事故说明；对不确定项诚实标注（如 unknown 提示词、Beta 范围）。扣分项：性能与功能声明（0.6 秒分析、hub 恢复）依赖未附文档，静态审查无法执行验证。
- 代理以明文 JSON 在 ~/.ccxray/logs/ 记录完整提示词、工具调用与上游响应——包含潜在敏感商业内容，请确保磁盘加密并知悉 LOG_RETENTION_DAYS 默认 14 天的保留行为。
- 回环连接默认免认证；在共享或高风险机器上务必设置 CCXRAY_LOOPBACK_REQUIRE_AUTH=1（SECURITY.md 自身建议）。
- Grok 路径会复用 CLI 的 auth token 调用计费端点；若不希望此外呼，请评估 XAI_BASE_URL 或避免代理 Grok 流量。
- Codex 支持为 Beta，保真度低于 Claude 路径；天气功能因已知缺陷默认关闭，需 ?weather=on 手动开启。
- Context HUD 在 sub-agent 密集的工作流中可能截断返回数据；相关场景请关闭 HUD。
- 许可为 PolyForm Noncommercial 1.0.0——禁止商业用途，企业采用前需法务评估；发布者身份未经企业注册库验证。
- 本评估为静态源码审查（低置信度），未执行任何运行验证；CHANGELOG、usage.md 等被引用文档未在证据集中核实。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v2.5.0-rc.3 预发布
发布说明摘录
Release candidate for 2.5.0 — published to npm under the next dist-tag; latest stays on 2.3.1. Install: npm install -g [email protected] SHA256 (ccxray-2.5.0-rc.3.tgz): 138684b90f94e64de8d95525bf97de5edbd29f7dbe2866c78e0d6a91eea717b7 204 non-merge commits since 2.3.1. Three headlines: ccxray adds optional GCS summary export and one-step setup; session, cost, and context data become more accurate and diagnosable; and launcher reliability, status reporting, and agentflow usage reports improve. Added …在 GitHub 查看 ↗ -
v2.3.1 v2.3.1 — Weather display toggle
发布说明摘录
Changed - Weather display off by default (#484, PR #488). The tool-failure signals (stuck, error_cluster, error_cumulative, tool_failure) are unreliable across all data paths — cumulative inflation on Anthropic proxy, absent fields on imported data, decoder defects on OpenAI wire. Weather computation and persistence continue running; only the six render sites are hidden behind a localStorage tri-state toggle (default OFF). Append ?weather=on to inspect. See docs/weather.md § Display toggle for details. …在 GitHub 查看 ↗ -
v2.0.0 v2.0.0 — Workflow timeline, enforced auth, per-session entry cap
发布说明摘录
Two domain shifts in one release: enforced auth on all endpoints (breaking for direct /v1/* callers), and a full workflow-timeline view that visualizes agent concurrency, sequential interleaving, and multi-model sessions. Highlights Workflow Timeline (new) - Sequential-interleave tracker with R1/R2 pre-numbering - Parallel-lane inference: orchestrator + Fork/Teammate lanes - Lane identity routing via coreHash + convId - WCAG ≥3:1 lane color pool (light + dark) - Birdseye overview mode (magnified minimap) - Adaptive overview height (viewport-proportional) …在 GitHub 查看 ↗