ccxray
给 AI Agent 会话装上 X 光：零配置代理记录 Claude Code / Codex 的每一次 API 调用，让黑盒变成透明玻璃盒。
证据显示：本地回环代理、单一运行时依赖（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 等被引用文档未在证据集中核实。
这个 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. / {timestamp}_res. 存入 ~/.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 有哪些优点和局限？
- 零配置：一条 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？
需要 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。