本地调试AI Coding Agent会话与失败MCP调用

当同时开启多个AI编程助手会话时，最直接的调试困境是：哪个会话卡住了，它最后一次操作了什么？ 如果从原始日志入手，意味着需要手动匹配会话ID、项目路径，再逐条追查工具调用记录。这个过程繁琐且容易出错。

Agent Observatory 是一款本地终端与浏览器仪表盘工具，专为检查 Codex 和 Claude Code 的会话记录而设计。它同时接收来自自定义埋点Agent的 OpenTelemetry 数据。视图围绕会话、活动、已记录的 MCP 调用、追踪链路和主机进程进行组织，提供了一条更直观的排查路径。

Agent Observatory 终端演示（使用合成示例数据）

快速上手体验

环境准备与启动

使用该工具需要 Python 3.11+ 和 uv 包管理器。在已有 Codex 或 Claude Code 会话记录的机器上，执行以下命令即可启动：

uvx --from agent-observatory-cli agent-observatory

终端界面会首先打开。按下 b 键可切换到本地浏览器仪表盘。接收器监听 127.0.0.1:14318，捕获的数据存储在本地 SQLite 文件中。这种本地优先的设计意味着会话数据不会离开你的机器。

uv 与 uvx 是什么

uv 是用 Rust 编写的 Python 包管理与项目管理工具，定位为 pip、pip-tools、virtualenv 等工具的一体化替代品，以速度快和依赖解析可靠著称。uvx 是随 uv 一同安装的命令行工具，用于在隔离的临时环境中直接运行某个 Python 包提供的可执行程序，而无需事先手动创建虚拟环境或全局安装。

文章中 uvx --from agent-observatory-cli agent-observatory 的含义是：从 agent-observatory-cli 这个包中取出名为 agent-observatory 的命令并运行。这带来了“零安装试用”的体验——不必污染现有环境，也便于快速升级或弃用。这也是文章要求 Python 3.11+ 的原因：该工具依赖较新的语言特性，旧版本解释器无法运行。

会话视图：定位卡住的任务

打开 Agents 视图并选择一个会话。列表行会显示运行时类型、会话ID、项目名称、观察到的状态、最后更新时间，以及来源报告的最新任务。详情视图进一步补充模型信息、使用量和近期工作记录。

一个关键设计细节：只有当来源明确报告等待状态时，会话才会被标记为 waiting。仪表盘不会推断未记录的原因。这避免了调试工具本身产生误导性信息。

MCP调用检查：定位失败的工具调用

打开 MCP Calls 视图，可以看到所选范围内有调用记录的服务器列表。检查单次调用可读取其记录的参数、返回值、耗时和关联的追踪链路。沿着追踪链路，可以查看周围的操作和错误证据。

需要注意的是，MCP视图并不列出机器上所有已配置的服务器，它只展示有实际调用记录的那些。对于排查“某个MCP调用为什么失败”这类问题，这恰恰是最需要的视图。

MCP 协议简介

MCP（Model Context Protocol）是 Anthropic 提出的一种开放协议，用于让 AI 助手以标准化方式连接外部工具、数据源和服务。一个 MCP 服务器通常暴露若干“工具”（tools），AI 在处理任务时可以调用这些工具来完成读写文件、查询数据库、访问 API 等操作。

正因为 MCP 调用是 Agent 与外界交互的关键环节，它也是最容易出错的地方：参数不合法、服务器超时、权限不足或返回值格式异常都可能导致任务停滞。因此本工具把 MCP 调用单列为一个视图，并关联到追踪链路，让开发者能直接看到“哪次调用、传了什么参数、返回了什么、耗时多久”，而不必在散落的原始日志中拼凑上下文。

非内置运行时的接入方式

如果你的Agent不是受支持的本地运行时，可以通过发送 OTLP/HTTP 遥测数据，或使用项目提供的 Python 和 JavaScript 客户端进行埋点。可见的详情取决于该Agent实际发出的数据字段。

OpenTelemetry 与 OTLP/HTTP 是什么

OpenTelemetry（简称 OTel）是一套与厂商无关的开源可观测性标准，定义了如何生成、采集和导出三类遥测数据：Traces（追踪链路）、Metrics（指标）和 Logs（日志）。OTLP（OpenTelemetry Protocol）是它的传输协议，其中 OTLP/HTTP 通过标准 HTTP 请求发送数据，默认端口通常为 4318。

在本工具的场景中，OTLP/HTTP 的意义在于：任何能按此协议导出的 Agent——无论它是用什么语言或框架写的——都可以把会话、工具调用和追踪信息推送到本地接收器（127.0.0.1:14318），无需依赖 Codex 或 Claude Code 的内置记录格式。这解释了为什么文章强调“可见的详情取决于该Agent实际发出的数据字段”：OTel 只传输发送方主动上报的内容，接收端无法凭空补全未上报的字段。

首次运行的检查清单

如果仪表盘显示为空，可以先启动一个 Codex 或 Claude Code 任务，确认工具能读取其本地会话记录。对于其他运行时，需要先配置遥测导出。项目的“第一分钟指南”文档记录了各视图和快捷键绑定。

上面的演示图使用的是合成记录。实际捕获的内容可能包含提示词、工具参数和项目详情。在录制或分享真实会话之前，务必查阅项目的隐私与捕获边界文档。

适用场景与能力边界

这套工作流在任务看似停滞或工具返回结果异常时特别有用：识别会话，检查最后记录的动作，然后沿调用链深入追踪。

但它同样清楚地展示了证据的边界。如果来源没有记录等待原因或MCP调用，仪表盘无法重建这些信息。这种诚实的能力声明，反而让工具在实际调试中更值得信赖——你不会被虚假的推断误导。

对于使用AI编程助手的开发者而言，这类本地观测工具填补了一个实际空白：在日志与调试器之间，提供了一层针对Agent会话的可视化检查能力。