cost-xray
看清 Claude Code 与 Codex 真正发给 API 的内容，以及每一部分花了多少钱。
- Star 数
- ★ 6.1k
- 最近更新
- 5 天前
- License
- MIT
- 主语言
- Python
- FA 评分
- 65/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 兼容但需适配Codex · Claude Code · OpenAI API · Claude API
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 编码智能体账单突然上涨，想确认是 MCP schema 前缀、thinking token 还是工具输出在吃钱
- 不适合
- 需要 Windows 原生支持的团队
- 已经结束的会话无法事后补抓，只支持前向捕获
- 需要逐源精确 token 拆分的用户（当前仅估算）
- 源码审查
- 65/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
cost-xray 是一个本地抓包与成本归因工具，面向 Claude Code 和 Codex 两类编码智能体。它用 mitmproxy 在本地做一次透明中转：Claude Code 走反向代理加 base-URL 覆盖，Codex 走正向代理加一个仅对 codex 命令生效的本地 CA，从而捕获真实的 API 请求与响应，而不是事后读取本地日志。原始流量先做脱敏（Authorization、API key、cookie 等）再落到 ~/.cost-xray/sessions/，由独立的 materializer 离线做分词与定价，不占用请求链路延迟。它的核心产出是把 fresh、cache-read、cache-write、output 四类 token 成本回溯到具体来源——系统提示、工具 schema、MCP 服务器、工具调用、消息块，并能下钻到单次调用。界面是一个全程可在任意目录启动的终端 TUI，命令为 cx。
安装后由 install.sh 部署后台抓包服务（开机自启、自愈、端口自适应），并按提示选择捕获 Claude Code、Codex 或两者。运行时 mitmproxy 绑定 127.0.0.1 中转请求，只把脱敏后的原始 request/response 写入 ~/.cost-xray/sessions/；随后 materializer 从原始字节重建每次调用的完整上下文，按来源切分 token 并用 LiteLLM 价格数据计价。Claude 的私有分词器通过 tiktoken 估算加比例校准处理：thinking 与工具 schema 等偏差较大的部分单独修正，其余按比例缩放到 provider 返回的 usage 总量，因此总额精确、来源间拆分近似。存储上对重复块做去重，每个唯一 message/schema/tool-result 只存一次，配合逐轮增量，按需重建完整字节。TUI 中可按 agent → 项目 → 会话 → 类别 → MCP 服务器 → 工具 → 单轮调用 → 真实输出逐层下钻，并展示上下文窗口占用与未被调用的 MCP 冗余。
- 编码智能体账单突然上涨，想确认是 MCP schema 前缀、thinking token 还是工具输出在吃钱
- 配置了多个 MCP 服务器，想知道哪些服务器从未被调用却每轮都在付 schema 开销
- 想评估某个 Read/Bash 工具返回的大段输出是否应该在上游截断
- 需要在团队内解释一次会话的缓存命中与缓存写入行为，判断前缀是否被反复重写
- 想在不修改智能体配置的前提下，观察 Claude Code 或 Codex 实际发送的请求结构
如何安装或部署这个 Agent？
要求 macOS 或 Linux，已安装 Claude Code 或 Codex，无需 API key 或账号。执行安装脚本：
curl -fsSL https://raw.githubusercontent.com/tigerless-labs/cost-xray/master/install.sh | bash安装器会询问捕获哪个智能体（Claude Code、Codex 或全部），在管道执行时也会提示。CI 等非交互场景可跳过提示：
COST_XRAY_AGENTS=claude bash install.sh已克隆仓库时可直接运行：
./install.sh安装后需打开新终端，捕获为前向生效，只覆盖新 shell 中启动的运行。
如何使用这个 Agent？
在新终端里像平常一样运行 claude 或 codex，无需加参数或改 base-URL。随后在任意目录打开 TUI：
cx常用子命令：
cx status # 查看服务状态、监听端口与已捕获会话
cx stop # 停止监控，代理下线，智能体改走直连（不再捕获）
cx start # 恢复监控
cx restart # 修改配置后重启代理
cx install # 重新安装，以本次选择为准并移除未选中的智能体
cx uninstall # 移除服务与 shell 包装（保留已捕获数据）调整端口或上游地址需编辑 ~/.cost-xray/env 后执行 cx restart。清空数据只需删除 ~/.cost-xray/ 目录。
这个 Agent 有哪些优点和局限？
- 数据源是真实 API 请求而非本地 transcript，能看见日志里根本不存在的系统提示、注入 schema 与 MCP 前缀
- 成本归因能下钻到单次工具调用及其输出的 fresh/cache-read/cache-write/output 拆分，而非会话级汇总
- 捕获链路不侵入智能体：Claude Code 免证书，Codex 的本地 CA 仅对 codex 命令生效，不进入系统信任库，代理故障时自动回退直连
- 落盘前完成密钥与敏感字段脱敏，全部数据留在 ~/.cost-xray/ 下，无遥测，可整目录删除
- 用去重加逐轮增量存储，长会话重复上下文不会撑爆磁盘
- 分析过程在请求链路之外，materializer 离线分词计价，不增加推理延迟
- 仅支持 macOS 与 Linux，README 未提供 Windows 路径
- 前向捕获：安装前的历史会话无法补齐，只能从现在开始记录
- Claude 分词器为私有实现，来源间的 token 拆分是校准后的估算而非精确值，精确模式尚未发布
- 依赖 mitmproxy、systemd（自动启动与自愈）以及本地 CA/wrapper 机制，非 systemd 环境需手动模式
- 仅支持 Claude Code 与 Codex 两类智能体，新增智能体需编写适配模块
- 无正式发行版与版本号信息，需通过 install.sh 或仓库直接获取
这个 Agent 与同类方案有什么区别？
README 将自身与基于本地日志的用量工具对比，明确点名 ccusage 与 codeburn。日志类工具直接从 transcript 统计会话成本，按模型、日期或任务汇总，能回答“花了多少”；但它们看不到请求时才组装的系统提示、工具 schema、MCP schema 与 provider 注入块，这些内容不写入 transcript，在真实编码请求中可能占据约一半或更多上下文。cost-xray 读原始 API 请求，因此能给出 schema、MCP 服务器、工具与消息桶的逐源 token 与美元归属，以及缓存读/写/新建的边界拆分。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| cost-xray 当前 | 65 · 存在缺口 | 命令行工具免费 | ★ 6.1k | 5 天前 | Python | Codex · Claude Code · OpenAI API · Claude API |
| AgentOps 可观测性平台 | 50 · 缺口较多 | 代码库 / SDK免费版 + 付费版 | ★ 5.9k | 3 个月前 | Python | OpenAI API · Claude API |
| AgentAcct | 61 · 存在缺口 | 命令行工具免费 | ★ 767 | 17 天前 | Python | Codex · Claude Code |
| ClawMetry | 81 · 表现良好 | 命令行工具免费版 + 付费版 | ★ 436 | 3 天前 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
信任维度：代理仅绑定 127.0.0.1、无遥测、在写盘前对 Authorization/x-api-key/Cookie 及疑似密钥字段做递归脱敏，且 tests/test_addon.py 用真实 hook 断言脱敏落地，数据流透明与敏感数据处理给到 3。但安装脚本以 curl|bash 方式执行并写入 shell rc、systemd/launchd 服务与 linger，属于较宽的系统级副作用，用户确认仅靠安装时提示，扣分至 2；Codex 需生成本地 CA，虽声明仅作用于 codex 命令且不入系统信任库，但仍是敏感操作。依赖仅以 >= 下限声明（mitmproxy>=10、tiktoken>=0.7、rich>=13），无锁定或哈希，供应链可复现性弱，dependency_security 仅 1。回滚有 cx stop/uninstall 且保留数据，但 uninstall 只清理 bashrc 块，其他 shell 需手工，rollback 给 2。来源归属在 README Credits 中致谢 mitmproxy/llm-interceptor/LiteLLM，但未逐文件标注，给 2。
可靠性：README、docs/install.md、SECURITY.md 与代码/测试对捕获路径、端口、脱敏、自愈行为的描述基本一致，self_consistency 给 2。依赖可用性仅声明下限版本、无锁文件、无 vendored 依赖，且 install.sh 未在证据中出现（无法核验其 venv/uv 逻辑），给 1。失败信息方面测试覆盖 raw 写失败记 WARNING、SSE 垃圾行容错、未知类型自显并标记，troubleshooting 列出常见错误，但缺少统一错误码/退出码说明，给 2。
适配性：明确面向 Claude Code 与 Codex 两类用户，含 GUI/Cursor 与手动模式场景，audience_and_scenarios 给 2。能力边界说明清晰（仅本地捕获、forward-only、不改变 agent 行为与成本、tokenizer 为估算+校准），给 2。触发精度上 _matched 精确匹配 /v1/messages、/responses 等并排除 count_tokens，测试覆盖，给 2。环境适配限 macOS/Linux，WSL/容器回退手动模式，Windows 未支持，给 2。
惯例：README 结构清晰、docs 分层，information_architecture 给 2。install_notes 详尽（systemd/launchd、linger、端口、CA、手动模式、卸载、排障），给 3。命名稳定性弱：项目名在测试中出现 context-xray 与 cost-xray 混用，且 pre-1.0 无稳定接口承诺，给 1。示例与 FAQ 有截图、命令示例与排障问答，但无独立 FAQ，给 2。已知限制有（tokenizer 近似、forward-only、pre-1.0），给 2。LICENSE 为完整 MIT，给 3。版本仅 pyproject 0.1.0，无 CHANGELOG，给 1。维护责任仅指向 master 与安全邮箱，无 SLA/维护者角色说明，且发布者未验证，给 1。
有效性：输出为 TUI 下钻到 MCP/工具/单次调用的成本归因，output_usability 给 2。相对日志类工具确有增量价值（可见请求时前缀、schema、MCP 浪费），但依赖 mitmproxy 拦截带来部署成本，marginal_value 给 2。成本收益上本地无遥测、去重存储控制磁盘，但需常驻服务与 CA，给 2。
可验证性：README 的多数主张（脱敏、绑定、去重、tokenizer 校准）可在代码与测试中找到对应，但“nothing else prices below the tool”等比较性断言无外部证据，claim_traceability 给 1。跨源一致性较好：README、SECURITY.md、docs/install.md 与 tests 相互印证，给 2。事实与推断分离：README 明确标注 tokenizer 为估算、校准残差近似、coming soon 的精确模式，区分了事实与推断，给 2。
- 安装脚本以 curl|bash 执行并写入 shell rc、systemd/launchd 服务与 linger，属系统级改动；建议先审阅 install.sh 再运行，并优先使用已克隆仓库的 ./install.sh。
- Codex 捕获需生成本地 mitm CA，虽声明仅作用于 codex 命令且不入系统信任库，仍应确认其作用域与卸载清理。
- 依赖仅声明下限版本、无锁文件或哈希，供应链可复现性弱；生产使用前应自行锁定版本。
- tokenizer 对 Claude 为估算+比例校准，单请求内各来源的 token 拆分是近似值，不应作为精确计费依据。
- 发布者未经 FollowAgents 验证，维护责任与更新路径仅指向 master 与安全邮箱，无 SLA 或版本化发布说明。
- 项目为 pre-1.0，命名在文档/测试中出现 context-xray 与 cost-xray 混用，接口与命名可能变动。