最近一段时间，我在开发中高频使用 AI Coding Agent，比如 Claude Code、Codex、OpenCode、DeepSeek-TUI、Reasonix、Kimi 等。
这些工具已经不只是“代码补全”了。它们可以读取项目、修改文件、执行命令、调用工具、根据报错继续修复问题。也正因为它们越来越像一个自动化开发代理，我开始遇到一个很 实际的问题：
当 Agent 做出一个决定时，我很难知道它到底看到了什么。
终端里看到的是最终回答，或者一部分执行日志。但真正决定 Agent 行为的内容，往往藏在它发给模型的请求里：
- system prompt
- message history
- tool schema
- tool call
- tool result
- 当前上下文
- token usage
- cache hit
- streamed response
- latency
- cost
如果这些内容不可见，很多问题就只能靠猜。
比如：
- 为什么 Agent 没有调用预期的工具？
- 为什么它重复读取同一个文件？
- 为什么一次任务消耗了异常多的 token？
- 为什么上下文越来越大？
- 为什么同样的提示在不同客户端表现不一样？
- 它到底有没有把敏感信息发给模型？
这些问题本质上都是可观测性问题。
传统抓包方式并不总是有效
最开始我尝试过 Charles、mitmproxy、系统代理等方式。
但在 AI Coding Agent 这类工具上，这条路并不稳定。很多客户端是 Node 或 native 应用，它们不一定遵守系统的 HTTP_PROXY / HTTPS_PROXY。有些工具会使用自己的网络实 现，有些场景会走 WebSocket，有些还会受到 TLS 证书或请求路径变化的影响。
结果就是：你以为自己已经开始抓包，但实际上什么都没有抓到；Agent 仍然能正常返回结果，说明它绕过了你配置的代理。
对于调试来说，这种“不确定是否真的观测到请求”的状态很难接受。
从 base URL 入手
后来我换了一个思路。
很多大模型客户端虽然不一定走系统代理，但会支持配置 API Base URL。例如：
- OpenAI-compatible 客户端通常支持 OPENAI_BASE_URL
- Anthropic-compatible 客户端通常支持 ANTHROPIC_BASE_URL
- 一些本地模型、网关和第三方平台也支持自定义 endpoint
- 部分 Agent 可以通过环境变量切换请求入口
既然如此，可以让 Agent 主动请求本地的一个 HTTP 服务，再由这个本地服务转发到真实上游 API。
整体链路类似这样：
AI Coding Agent -> localhost proxy -> real model API
这样有几个好处：
- 不需要改 Agent 源码
- 不依赖系统代理
- 不需要全局 TLS 抓包
- 可以完整记录请求和响应
- dashboard 可以直接基于这些记录做分析
这就是我后来做 ccglass 的起点。
ccglass 是什么
ccglass 是一个开源的本地 logging reverse proxy + web dashboard，用来观察 AI Coding Agent 和模型 API 之间的真实通信。
安装方式：
npm install -g ccglass
运行：
ccglass
也可以直接指定客户端：
ccglass claude ccglass codex ccglass opencode
启动后，它会：
- 在本机启动一个 proxy
- 设置目标客户端需要的 base URL 环境变量
- 启动对应的 AI Coding Agent
- 打开本地 dashboard
- 实时展示请求、响应、token、cost、tool calls 等信息
所有数据都保存在本地，不需要注册账号，也没有云端后台。
它能观察什么
目前 ccglass 主要提供这些能力：
- 实时请求列表
- 查看完整 system prompt
- 查看 message history
- 查看 tool schemas
- 查看 tool calls 和 tool results
- 重组 streamed response
- 展示 input/output/cache tokens
- 估算每次请求成本
- 统计 cache hit rate
- 展示请求延迟
- turn-to-turn diff
- 按 model 过滤请求
- session summary
- 导出 raw HTTP、Markdown、JSON、HAR
我自己最常用的是两个视图。
第一个是完整请求内容。它能让我看到 Agent 到底给模型发送了哪些上下文。
第二个是 turn-to-turn diff。很多 Agent 会在多轮循环中不断携带历史消息，如果上下文膨胀，diff 能直观看到是哪一轮开始引入了大量内容。
一个典型调试场景
假设我让 Agent 修复一个测试失败的问题。
终端里可能只看到：
Read file Run tests Edit file Run tests again Done
但如果从请求层面看，里面可能包含更多信息：
- Agent 收到了哪些 system instructions
- 它有哪些工具可以调用
- 每个工具的 schema 是什么
- 测试失败结果如何被塞回上下文
- 模型为什么决定先读某个文件
- 下一轮请求相比上一轮新增了什么
- 这次修复一共消耗多少 token
- 哪些输入命中了 cache
- streamed response 最终被如何重组
这些信息对定位问题非常关键。
如果 Agent 做错了，我们可以判断问题是在 prompt、tool schema、上下文、模型输出，还是客户端执行逻辑上。
AI Agent 也需要可观测性
传统后端服务里，我们很自然地会关注日志、指标、链路追踪、错误率、延迟、资源消耗。
但到了 AI Agent 上，很多系统级能力反而缺失了。
Agent 的行为越来越复杂：它会读取文件、执行命令、调用工具、维护上下文、访问外部 API、在多轮循环中自我修正。这个过程如果完全黑盒，开发者就很难做稳定性分析和成本 控制。
我认为 AI Agent 的可观测性至少应该包括几个层面：
- Prompt 可见性：模型到底收到了什么
- Tool 可见性：模型能用什么工具，实际调用了什么
- Context 可见性：上下文如何随轮次变化
- Cost 可见性：每轮请求花了多少 token 和成本
- Latency 可见性：慢在哪里，是上游慢还是生成慢
- Privacy 可见性：有没有不该发送的内容进入请求
ccglass 不是让模型更聪明的工具，它更像是给 AI Coding Agent 加了一个 Network Panel。
支持的客户端和提供方
目前它支持多种常见客户端和提供方，包括：
- Claude Code
- Codex
- OpenCode
- DeepSeek-TUI
- Reasonix
- Kimi
- Ollama
- LM Studio
- OpenRouter
- GLM/Zhipu
- AWS Bedrock
- Google Vertex AI
- CodeBuddy
- 以及可通过 OpenAI-compatible / Anthropic-compatible endpoint 配置的自定义工具
对于更通用的场景，也可以使用：
ccglass run --provider openai --
或者只启动 proxy，让 IDE 或其他客户端手动接入：
ccglass proxy --provider openai
目前的限制
这个方案也不是万能的。
如果某个客户端完全不支持自定义 base URL，或者使用无法通过 base URL 覆盖的 WebSocket 通道，就不一定能被观察到。
例如 Codex 如果使用 ChatGPT 登录模式，可能会走 chatgpt.com 的 WebSocket 通道，这时 OPENAI_BASE_URL 不会生效，dashboard 里就看不到请求。需要切换到 API key 模式 才适合用这种方式观察。
还有一些 IDE 内置模型会硬编码上游地址，这类场景需要 forward proxy 或单独适配，复杂度会更高。
所以更准确地说，ccglass 适合观察那些支持自定义 API endpoint 的 AI Coding Agent 和 LLM 客户端。
隐私和安全边界
因为这个工具会看到完整 prompt、上下文和响应，所以隐私边界必须讲清楚。
ccglass 默认本地运行：
- dashboard 是本机地址
- 没有 SaaS 后台
- 不上传日志
- 捕获记录保存在本机
- 用户可以自行删除、导出和分析
但这不代表可以无脑在任何环境使用。对于包含生产密钥、客户数据、内部源码的项目，仍然应该谨慎处理日志保存和分享。
我的目标不是收集数据，而是让开发者能在自己的机器上看清 Agent 行为。
总结
AI Coding Agent 的能力正在快速增强，但围绕它们的调试和可观测工具还没有完全跟上。
当 Agent 只是补全几行代码时，看不到内部细节问题不大。但当它开始读项目、改文件、执行命令、调用工具、持续多轮工作时，我们就需要更工程化的观察手段。
ccglass 是我对这个问题的一次尝试：用一个本地 reverse proxy 和 dashboard，把 AI Coding Agent 发给模型的真实请求展示出来。
项目已开源：
https://github.com/jianshuo/ccglass
如果你也在使用 Claude Code、Codex、OpenCode 或类似的 AI Coding Agent，我很想知道：你最想观察 Agent 的哪一部分行为？是 prompt、tool call、token 成本，还是完整 的执行链路？
