现在很多开发者已经开始把 AI 编程 Agent 当成日常工具使用。

比如 Claude Code、Codex、OpenCode、Cursor、Cline、DeepSeek 相关 CLI、Kimi、Ollama、OpenRouter 等。它们不只是补全代码，还会读项目、搜索文件、调用工具、运行命令、修改代码、解释错误，甚至连续完成一个小型开发任务。

这类工具确实提高了效率，但也带来一个很现实的问题：

当 Agent 做错事时，我们经常不知道它到底为什么错。

你能看到它最终说了什么，也能看到它改了哪些文件。但很多关键问题并不在最终回答里：

• 它到底把哪些上下文发给了模型？
• system prompt 里有哪些限制和行为规则？
• 这一轮请求带了哪些 tool schema？
• 模型有没有真的返回 tool call？
• 工具结果有没有进入下一轮上下文？
• input token 为什么突然变大？
• cache 有没有命中？
• 请求慢到底是网络慢、模型慢，还是上下文太重？
• 同一个任务下，Claude Code 和 Codex 给模型的请求有什么差异？

如果这些问题看不到，调试 AI Agent 就很容易变成猜测。

这篇文章介绍一个开源工具：ccglass。

GitHub 地址：https://github.com/jianshuo/ccglass

ccglass 是什么？

一句话概括：

ccglass 是一个面向 AI 编程 Agent 的本地观测工具，用来查看 Agent 实际发送给大模型的请求和响应。

它不是新的 AI 编程助手，也不是模型服务商。它更像一个本地的请求观察层。

当你运行 Claude Code、Codex、OpenCode、Kimi、Ollama、OpenRouter 等工具时，ccglass 可以在本地启动一个代理服务，把请求和响应记录下来，再通过 Web Dashboard 展示出来。

你可以在 Dashboard 中看到：

• request / response body
• system prompt
• user / assistant 消息历史
• tools schema
• tool call
• tool result
• streamed chunks
• token 使用量
• cache 命中情况
• cost 估算
• latency 和吞吐
• 不同请求之间的上下文 diff

这对使用 AI 编程工具的人来说很有价值，因为很多 Agent 的行为差异，本质上都藏在请求层。

为什么只看最终答案不够？

以前我们使用普通聊天模型时，主要关注的是：

模型回答得对不对？

但 AI 编程 Agent 不一样。它不是一次性回答问题，而是在多轮循环中不断做决策：

1. 先读哪些文件？
2. 是否要运行测试？
3. 是否调用搜索工具？
4. 工具参数怎么填？
5. 工具返回结果后，要不要继续请求模型？
6. 哪些上下文需要保留？
7. 是否应该修改文件？

所以 Agent 的失败不一定是“模型不聪明”，也可能是请求链路里的某个环节出了问题。

举几个常见例子。

1. Agent 没有调用工具

表面现象：

Agent 说自己无法确定结果，或者直接给出一个泛泛的回答。

可能原因：

• tool schema 根本没有传给模型；
• 工具描述太模糊，模型不知道何时使用；
• system prompt 限制了工具调用；
• 客户端没有正确解析模型返回的 tool call。

如果只看最终回答，很难判断是哪种情况。用 ccglass 可以直接检查请求里有没有工具 schema，响应里有没有 tool call。

2. Agent 修改了错误文件

表面现象：

它确实改了代码，但改的不是问题所在。

可能原因：

• 第一轮请求没有项目结构；
• 搜索工具返回了相似但无关的文件；
• 工具结果太长，关键信息被稀释；
• 后续请求没有保留关键错误输出。

这类问题看 Dashboard 里的消息历史和工具结果会更清楚。

3. token 成本突然升高

表面现象：

一个看似很小的任务，跑了很多轮，请求成本明显变高。

可能原因：

• 每一轮都重复携带大量文件内容；
• 工具返回结果没有被压缩；
• 上下文没有有效裁剪；
• cache 命中率低；
• system prompt 和 tool schema 本身就很大。

ccglass 可以展示 input token、output token、cache token 和 cost 估算。对于团队使用 AI 编程工具，这些指标很有必要。

ccglass 和普通抓包工具有什么不同？

有些同学可能会问：这不就是抓包吗？Charles、mitmproxy、Proxyman 不能做吗？

通用抓包工具当然有价值，但 AI 编程 Agent 的场景有一些特殊点。

很多 AI CLI 是 Node 或原生程序，不一定稳定遵守 HTTP_PROXY / HTTPS_PROXY。有些客户端还有自己的网络实现、认证逻辑或流式响应处理方式。直接 patch fetch 也容易因为客户端升级而失效。

ccglass 的思路是：

1. 在本地启动一个代理服务。
2. 通过 OPENAI_BASE_URL、ANTHROPIC_BASE_URL 等环境变量，把 Agent 请求指向本地代理。
3. 本地代理记录请求和响应。
4. 再把请求转发到真实模型 API。
5. Dashboard 读取日志并可视化展示。

这种方式的好处是：

• 不需要安装 CA 证书；
• 不需要解密 HTTPS；
• 不需要改客户端源码；
• 更适合观察 prompt、tool call、token、cache、cost、latency；
• 更贴近 AI Agent 的调试场景。

它不是替代所有抓包工具，而是把重点放在 AI 编程请求的可观测性上。

快速开始

ccglass 是一个 Node 工具，安装方式很简单：

npm install -g ccglass

安装完成后，直接运行：

ccglass

它会弹出交互式菜单，让你选择要观察的客户端。

也可以直接指定：

ccglass claude
ccglass codex
ccglass kimi
ccglass opencode
ccglass ollama
ccglass openrouter

例如观察 Codex：

ccglass codex

启动成功后，终端会输出 Dashboard 地址，类似：

dashboard: http://127.0.0.1:57633

打开这个地址，就可以实时查看请求记录。

一个实际调试场景

假设你让 Agent 修复一个测试失败：

项目里有一个测试失败，请分析原因并修复。

Agent 最后给出一个改动，但测试仍然没过。

这时如果只看最终输出，你可能只能问：

它是不是没理解需求？

但用 ccglass，可以把问题拆得更具体：

1. 第一轮请求里是否包含测试失败信息？
2. Agent 是否真的运行了测试？
3. 测试输出是否被完整返回给模型？
4. 它搜索了哪些文件？
5. 它读取的源码和测试是否匹配？
6. 修改前最后一轮请求里，模型到底看到了哪些上下文？
7. 修改后是否又请求模型检查结果？

这样调试就从“猜 Agent 为什么错”，变成“检查请求链路哪里断了”。

适合哪些人使用？

我觉得 ccglass 特别适合下面几类开发者：

• 经常使用 Claude Code、Codex 等 AI 编程工具的人；
• 想研究不同 Agent 请求结构差异的人；
• 正在开发 AI Agent、IDE 插件或 OpenAI-compatible 客户端的人；
• 需要排查 tool calling 问题的团队；
• 关注 token 成本、cache 命中率和请求延迟的人；
• 想把 AI 编程过程沉淀成可复盘日志的人。

如果你只是偶尔让 AI 写一段小代码，可能暂时不需要它。

但如果你已经开始让 AI Agent 参与真实项目，尤其是让它读文件、改代码、跑测试、调用工具，那么请求级可观测性会越来越重要。

可以重点观察哪些指标？

第一次使用 ccglass 时，可以先从这几个地方看：

1. system prompt

看看 Agent 的底层规则是什么。很多行为差异不是模型本身造成的，而是 system prompt 决定的。

2. tool schema

看看模型实际看到了哪些工具，工具描述是否清晰，参数结构是否复杂。

3. tool call 顺序

看看 Agent 是先读文件、先搜索、先跑测试，还是直接修改代码。

4. 上下文变化

观察每一轮请求新增了什么、保留了什么、丢失了什么。

5. token 和 cost

关注 input token 是否持续膨胀，cache 是否命中，单次任务成本是否异常。

6. latency

区分是模型生成慢、上下文太大，还是请求链路本身慢。

总结

AI 编程工具正在从“代码补全”走向“开发 Agent”。

这个变化很重要，因为 Agent 不只是生成代码，它还会读上下文、调用工具、做决策、执行多轮任务。

能力越强，黑箱感也越强。

如果我们只能看到最终回答，就很难判断 Agent 是哪里做错了：是 prompt 问题、工具问题、上下文问题、客户端解析问题，还是 token 和成本控制问题。

ccglass 的价值就在这里：

它把 AI 编程 Agent 的请求过程展示出来，让调试从猜测回到证据。

如果你也在用 Claude Code、Codex、OpenCode、Kimi、Ollama、OpenRouter 或其他 OpenAI-compatible 客户端，可以试试这个工具。

GitHub：https://github.com/jianshuo/ccglass

安装：

npm install -g ccglass

启动：

ccglass

对于越来越复杂的 AI 编程工作流来说，看清请求层，可能会成为开发者的基本功。