1. 前言

在上一篇文章中，我们深入剖析了 Permission, Approval & Sandbox 的设计——Agent 如何在拥有强大执行能力的同时，通过多层防御体系保证安全可控。如果说 Agent Loop 是 Agent 的"心跳"，Tool System 是"双手"，Context Management 是"记忆系统"，SubAgent System 是"团队协作能力"，Permission & Sandbox 是"免疫系统"，那么 Observability & Operations（可观测性与运维）就是 Agent 的"神经系统"——它决定了 Agent 在生产环境中能否被监控、追踪、调试和治理。

当 Agent 真正部署到生产环境——作为 CLI 工具被数千名开发者日常使用、作为后台服务持续运行数周、作为编码助手修改关键代码——可观测性变成了Agent的基本能力。

可观测性不是简单的打日志，报个监控，而是一组更根本的问题：

  • Agent 的一次运行，事后能不能完整回放和审计？
  • Agent 正在做什么，当前处于什么状态，有没有卡住？
  • 子 Agent、后台任务、定时调度——这些异步执行单元能不能被追踪？
  • 出问题后，第一现场在哪里？如何区分是模型问题、工具问题、上下文问题还是系统问题？
  • Token 消耗、API 延迟、工具调用耗时——这些成本指标能不能被量化和管理？
  • 会话能不能被恢复、归档、导出、切换？这些运维动作是不是系统的一等能力？

本文是 Agent 实现原理系列的第六篇，继续参考 Codex CLI、Claude Code、nanobot、pi 四个主流开源项目的实现，从工程角度总结 Agent 可观测性与运维体系的设计原则和关键权衡。

2. 可观测性是 Agent Runtime 的骨架

2.1 从"打点日志"到"多层信号体系"

Agent 的运行过程不是一条直线，而是一棵分叉的树——有主会话、有子 Agent、有后台任务、有定时调度、有工具调用链、有压缩边界、有权限决策点。单靠几条零散的 log，在出问题时根本无法还原"当时到底发生了什么"。

更深一层看，可观测性之于 Agent，就像飞行数据记录仪之于飞机——不是为了日常飞行时盯着看，而是为了两件事：

  1. 事后可恢复：会话中断了能继续，系统崩溃了能重建状态
  2. 事中可诊断：运行时能判断 Agent 是正常推理、卡在工具执行、还是在等待用户审批

因此，一个 production-grade Agent Runtime 的可观测性，不是"有空再补点日志"，而是和主执行链同等级的基础设施。它至少需要覆盖五种不同粒度：会话级（transcript、session metadata）、任务级（background task status、task output）、工具级（tool call 轨迹、shell output、permission 事件）、平台级（analytics、tracing、metrics）、运维级（状态快照、健康检查、成本追踪）。

2.2 可观测性的通用分层模型

综合四个项目的实现，Agent 可观测性可以抽象为五层信号体系：

flowchart TD
    A["会话级：transcript / session metadata / resume state"] --> B["任务级：background task lifecycle / progress / notification"]
    B --> C["工具级：tool call events / execution traces / permission decisions"]
    C --> D["平台级：metrics / tracing / analytics / cost tracking"]
    D --> E["运维级：status snapshot / health check / debug artifacts / repair tools"]

这五层共同回答四个生产问题：

  1. 现在正在发生什么（实时事件流 + 进度追踪）
  2. 事情结束后能否重放和归因（持久化 transcript + rollout + session tree）
  3. 横向规模上能否统计延迟、失败、资源消耗（metrics + cost tracker）
  4. 出故障后是否有修复、恢复和治理手段（resume / repair / backfill / archive）

这四组能力不是彼此独立的优化项，而是同一条 runtime 数据面上的不同投影，记录、展示、恢复、控制，其实是同一条 runtime 数据面的不同消费方式。

以 MCP（Model Context Protocol）工具的接入为例，OpenAI Agents SDK 将 MCP 集成明确分为两种模式1：hosted MCP（平台托管，工具调用经由平台中转，trace 天然在平台侧闭环）和 local MCP（runtime 直接持有连接，经由 stdio 或 streamable HTTP）。这不只是部署方式的差异，更是观测边界的差异——托管模式下平台自然持有完整的调用链记录，本地模式下 trace 的完整性和审批流则由 runtime 自己负责。因此，可观测性的设计不是从"怎么记日志"开始的，而是从"能力的边界画在哪里"开始的。 选择在哪个层面接入外部能力，同时也就选择了观测责任的归属。

3. 主流项目的可观测性与运维设计

3.1 Claude Code2：以 Transcript 为账本的多层信号体系

Claude Code 的可观测性体系是四个项目中最完整的。它最核心的设计是把 transcript 当作 runtime ledger 而非聊天记录。

它持久化的内容远不止 user/assistant 文本，还包括 compact boundary、file history snapshot、context collapse snapshot、content replacement record 等运行时状态。这使得 transcript 同时承担恢复、审计、排障三个角色——它本质上是会话的事件账本，而非 UI 的副本。

第二个关键设计是每个子 Agent 都有独立的 sidechain transcript。后台 agent 不再是黑箱，而是拥有独立 transcript、metadata 和 task output 映射的可恢复运行单元。这正是子 Agent 异步 spawn、later re-entry 和 resume 能力的根基。

在平台遥测层面，Claude Code 采用了 Analytics / OTel / Perfetto 三层并存 的策略：Analytics 负责低成本的产品行为统计并严格去敏，OTel 把关键运行事件接到标准外部平台，Perfetto 则面向深度性能排障输出高保真时间线。三层各司其职，不是互相替代。此外，本地调试被拆成 debug（工程诊断）、error log（故障证据）和 diagnostics（IDE 级代码质量检测）三条独立线，职责清晰不混杂。

运维入口方面，/status（运行现场概览）、/doctor（安装与环境健康）、/cost（贯穿会话生命周期的成本追踪）三者覆盖了从"实例是否健康"到"运行是否正常"到"花了多少钱"的完整运维面。

但也要看到，这套体系的完整是以复杂度为代价的——六层信号、三条调试线、三层遥测，更像是实践中不断堆叠的结果，而非一次性的顶层设计。

3.2 Codex CLI3：事实-索引-指标-控制面的完整闭环

Codex CLI 的可观测性设计从一开始就为平台化部署而规划，它最突出的设计是实时事件和持久化记录共用同一份结构化 payload。事件先写入 Rollout 持久化，再投递到实时 event channel——“你看到的就是被记录的”，避免了实时视图和事后审计不一致的经典问题。

典型事件从 TurnStarted、TurnComplete 到 GuardianAssessment 覆盖十余种类型，构成前端、app-server 和协作层共同的观测入口。

其次，Codex 的 Rollout 分级保留策略体现了明确的治理意识：核心事件（turn 生命周期、token 统计）标记为 Limited，排障关键事件（Error、GuardianAssessment）标记为 Extended，而瞬时 UI 事件（审批弹窗、hook 触发）根本不持久化。这个取舍的本质是在"回放价值"和"存储噪音"之间做裁剪。

Codex 独有事实-索引分离的设计哲学：Rollout JSONL 是不可变事实账本，State DB（SQLite）是建立在 Rollout 之上的可重建查询索引。内建 reconcile、read_repair、backfill 等修复能力，当索引坏了可以修复。

此外，Metrics 覆盖 API/Turn/Tool/Thread 四级，Trace context 支持 W3C 标准跨组件传播，Thread watch 机制将内部状态投影为稳定的外部通知，运维动作（resume、archive、unarchive）作为系统一等协议能力。

整体来看，Codex 的可观测性设计是四个项目中最有顶层规划感的——“事实-索引-指标-控制面"的分离贯穿始终，每一层都有明确的职责边界和重建路径。

3.3 pi4：清晰原语 + Extension 集成的观测框架

pi 的可观测性设计与前三个项目有根本不同：它不内建完整 observability platform，而是提供一组稳定的观测原语，让宿主自己接入生产监控体系。 它没有 Prometheus exporter、没有 OTEL pipeline、没有中心化日志聚合——但运行时内部事件已经拆得足够干净，可以直接被外部系统消费。

pi 的核心设计哲学是：

把 Agent 运行过程拆成多个可独立接入的观测面——AgentSessionEvent 事件流、session tree JSONL、多粒度 hooks、RPC control plane——core 只负责生产这些原语，消费和治理交给宿主。

pi 的观测面有四个层次：运行时内存态，实时事件总线，持久化 session tree，导出与调试产物。观测粒度拆清晰，Provider 级、Message 级、Tool 级、Turn/Agent 级，不同级别粒度各自回答不同层面的问题。

运维协议方面，pi 存在两个协议 JSON mode 和 RPC mode ：JSON mode 适合 shell pipeline 和轻量集成（stdout 直接出 JSONL），RPC mode 把 stdin 作为 control plane、stdout 作为 event plane——非常适合生产宿主一方向下命令、另一方向收状态。

整体而言，pi 的路线不是"自带完整监控平台”，而是"先把运行时事件做干净，再让宿主接入"。这种设计对 extension 生态的依赖最高，但也给了宿主最大的灵活性。

3.4 nanobot5：学术级的"本地优先"模型

nanobot 的可观测性设计没有统一的 tracing 平台，而是靠多个独立信号面拼出一套"本地优先、文件优先、日志优先"的可观测模型。

它的核心思路可以概括为：

日志是第一现场，session JSONL 是第二事实来源，/status 是轻量运行时快照，AgentRunResult 是执行级归一信号。适合小规模、自托管、人工值守的生产场景。

nanobot 的信号体系由四组组件拼成：运行日志，会话快照，执行追踪，后台运维。每一层都有不同粒度的日志点，但目前仍靠人工 grep 而非结构化查询。

但nanobot没有统一 metrics 管道、没有标准 tracing、没有 trace id / correlation id 贯穿日志、没有结构化审计事件中心、没有内建 dashboard/告警/SLO。

3.5 四项目可观测性横向对比

维度Claude CodeCodex CLInanobotpi
持久化模型Transcript 多类别 ledger + sidechain transcriptRollout JSONL + State DB + Logs DB 三层append-only session JSONLSession tree JSONL（branch-aware）
实时事件消息流（assistant/progress/attachment/tombstone）EventMsg 统一事件流（TurnStarted/TokenCount/Error/GuardianAssessment 等）logger + stream delta + tool_eventsAgentSessionEvent 产品级事件总线
任务/后台观测ProgressTracker + TaskOutput + task_notificationThreadWatchManager + app-server notificationcron job JSON + heartbeat decision chainsteering/follow-up queue + agent events
Metricscost-tracker + analytics + OTel eventsSessionTelemetry + 分层 metrics（API/Turn/Tool/Thread）AgentRunResult.usage + /status snapshotgetSessionStats() + getContextUsage()
TracingSession tracing（span 树）+ PerfettoOTEL traces + W3C trace context 跨组件传播tool_events（缺 span id/duration）通过 event 时序推断（无独立 tracing）
运维入口/status + /doctor + /costThreadWatchManager + resume/archive/unarchive/reconcile/status + cron/jobs.json + HEARTBEAT.mdRPC control plane + session ops
修复能力compact boundary 恢复 + session memory 重建reconcile_rollout + backfill + read_repair无内建修复（依赖人工）无内建修复（依赖 session file 回放）
去敏与治理analytics metadata 禁字符串、prompt logging 受控、transcript 大小上限EventPersistenceMode 分级、超大输出裁剪、logs DB retentionsession 保存时清 runtime context、截断超长 result事件流和 session file 无内建去敏（由 extension 层处理）
整体定位多层信号面、贯穿全生命周期的生产级观测平台化五层体系、“事实-索引-指标-控制面"完整闭环本地优先、文件优先、日志优先，人工值守清晰原语 + Extension 集成，宿主自建监控

4. 关键设计维度

4.1 持久化与回放

不同项目在持久化和回放方面都聚焦同一核心目标：让一次 Agent 运行在事后可恢复、可审计、可回放。

项目持久化载体记录粒度回放能力
Claude CodeTranscript（多类别 ledger）记录粒度最细，甚至包括 compact boundary、file history snapshot、context collapse snapshot核心恢复能力，resume 直接依赖
Codex CLIRollout 为事实来源、State DB 为可查询索引、Logs DB 为系统运行日志用 EventPersistenceMode（Limited / Extended）做分级，ExecApprovalRequest 和 HookStarted/Completed 这种瞬时 UI 事件不持久化resume + fork + thread history build
nanobotSession JSONL（append-only）保存时做清洗，但缺少分级策略和修复能力支持 session 恢复，但无 fork/repair
piSession tree JSONL（branch-aware）entry 含 id/parentId/timestamp，含治理动作 entrybranch 回放 + switch session

4.2 实时事件流：

这里的关键权衡是：实时事件流应该服务于谁？

  • Codex 和 pi 的选择是把实时事件流设计为"外部可消费的协议”——事件有结构化 schema、有时序保证、可以从 stdout 或 RPC channel 订阅。这让外部系统（IDE 面板、Web UI、worker supervisor）可以基于事件流构建自己的观测视图
  • Claude Code 的事件流更偏内部消费——消息流服务于 UI 渲染、transcript 持久化、子 Agent 回流，但不以"外部订阅"为主要设计目标
  • nanobot 的实时信号仍然是"给人看"的——日志、进度文本、tool hints——没有形成结构化事件协议

4.3 Metrics 与 Cost

生产力的 Agent 一旦进入生产环境，Agent 的成本和延迟就是治理对象。Codex 的分层指标中，API 层看 provider/transport 延迟、Turn 层看端到端/TTFT/token usage、Tool 层看工具调用耗时，为排障提供了清晰的分层定位能力：能区分"模型慢"“网络慢"“工具慢"“编排慢”。

Claude Code 的 cost-tracker 设计也值得注意——成本被当作一个贯穿会话生命周期的运维指标面，resume 时恢复之前的成本状态。这是"成本不是算完就忘，而是随会话滚动的持续指标"这一理念的体现。

nanobot 和 pi 则只提供了内存级的统计接口。这说明大多数项目应该从"先有结构化统计"起步，在确实有多实例集中监控需求时再引入标准 metrics pipeline。

4.4 Tracing：从"排障工具"到"质量数据管道”

四个项目对 tracing 的实现程度差异最大，说明这个方面的设计还在积极探索中。需要看到，tracing 的工程定位从"排障工具"已经转变为"质量数据管道”，每一次运行都在为后续的评估和优化积累证据。

四个开源项目目前离这个闭环都还有距离，Codex 的 rollout 作为可回放事实账本最接近这个愿景。建设路径是渐进式的：先做 tool_events 结构化记录，再引入 span 树和 trace context，当数据积累起来之后，trace grading 和 eval pipeline 是自然的下一个步骤。

4.5 调试与故障定位

四个项目的故障定位路径差异，本质反映了对"什么是最可靠证据"的不同理解。但所有项目都验证了同一条核心原则：业务事实和运行机制要分开看。

Transcript / Rollout / Session JSONL 回答"Agent 当时看到了什么、做了什么决策"——这是业务事实。Debug log / tracing 回答"系统在执行这些决策时内部发生了什么"——这是运行机制。两者互补，不能互相替代。排障时优先看业务事实还原决策链，再看运行机制定位根因。

Codex 的分层排查策略最为实用：查"Agent 为什么那样做"看 Rollout，查"线程在哪、状态如何"看 State DB，查"系统异常、异步竞争"看 Logs DB 和 tracing，查"性能瓶颈"分三层看——API metrics（区分模型慢/网络慢）→ Turn metrics（端到端耗时）→ Tool metrics（工具调用耗时）。

4.6 运维控制面：从"看"到"控"

可观测性的最终目的是治理。四个项目的运维控制能力差异巨大，但可以提炼出一条核心分水岭：运维动作是系统的一等协议能力，还是旁路脚本？

Codex 的选择是最彻底的——resume、archive、unarchive、reconcile、interrupt 都是正式 API，背后有合法性校验、元数据修复和状态通知。更关键的是它的"可修复"哲学：rollout 是事实来源，state DB 是可重建索引——索引坏了能修。Claude Code 和 pi 在 session 恢复和 abort 方面做得不错，但归档、修复等高级运维能力欠缺。pi 的 steer/follow-up 队列则提供了一种独特的在线治理：不仅知道"有没有输入"，还知道"这些输入会在哪个执行边界生效"。

4.7 去敏与治理：可观测性本身也需要约束

可观测性系统本身也可能成为隐私和合规的风险面。四个项目的共识是：不是所有状态都值得永久保存，不是所有东西都无脑上报，存储必须有硬上限。

Claude Code 在这方面最严格——analytics metadata 默认禁止字符串，prompt logging 受环境变量控制，progress message 不进入 transcript 主链，span 有 TTL 和 orphan 清理。Codex 的分级保留策略同样务实：瞬时 UI 事件根本不持久化，logs DB 设 10 天 retention。nanobot 在 session 保存时做清洗（截断超长 result、清 data URL、剥离 runtime context）。pi 则把这层责任交给了 extension。

5. 设计共识

综合四个项目的工程实践，可以提炼出以下七条经过验证的设计共识：

  1. 持久化记录是第一现场。Transcript / Rollout / Session JSONL 的目标不是"把聊天记下来"，而是让一次运行在事后可恢复、可审计、可回放。如果持久化不可靠，其他一切观测能力都是空中楼阁。

  2. 实时事件和持久化记录应共用同一份结构化 payload。Codex 和 pi 都实践了这一点——“你看到的就是被记录的”，避免了实时视图和事后审计不一致。

  3. 业务事实和运行机制要分开看。Transcript 回答"Agent 做了什么决策"，debug log / tracing 回答"系统内部发生了什么"。两者互补，排障时先看前者还原决策链，再看后者定位根因。

  4. 持久化需要分层：事实层（不可变账本）→ 索引层（可重建查询）→ 日志层（系统运行记录）。Codex 的 Rollout → State DB → Logs DB 三层模型最完整。核心原则：事实层是唯一真相源，索引坏了可以从事实际重建。

  5. Metrics 是分层治理工具，不是展示品。至少覆盖 API 层（区分模型慢/网络慢）、Turn 层（端到端/TTFT/token）、Tool 层（耗时和失败率）。三层定位能力是区分"哪里慢"的前提。

  6. 从 trace 到 eval 是观测的下一跳。Tracing 的建设路径是渐进式的：先结构化 tool_events，再 span 树和 trace context，最后 trace grading → eval pipeline。Tracing 的终点不是"漂亮的火焰图"，而是"可驱动行为改进的质量数据"。

  7. 可观测性本身需要治理。瞬时事件不应永久保存，存储必须有硬上限，上报必须有去敏。运维动作（resume、archive、repair、export）应该是系统的一等协议能力，不是人工搬文件的旁路脚本。

这些共识本质上都在解决同一个问题：如何把 Agent 运行过程从"只在当下可见的交互"升级成"可恢复、可审计、可排障、可计量、可治理的生产运行单元"，并最终让它成为"可通过评估持续优化的工程系统"。

6. 总结

Observability & Operations 是 Agent 从"能跑 demo"到"可生产部署"的最后一道门槛，也是最容易被低估的一道。Demo 阶段的 Agent 可能只需要一个 console.log 和一段漂亮的控制台输出，但生产系统必须把运行过程拆成多个独立可观测、可消费、可治理的信号面。

Observability & Operations 的核心原则已经清晰：让每次 Agent 运行都可恢复、可审计、可排障、可计量、可治理——并且让这些记录成为驱动行为改进的质量数据。 把"运行时黑箱"变成"可观测生产单元"，再进一步变成"可通过评估持续优化的工程系统"——这不仅是工程能力的升级，更是 Agent 从"开发者玩具"走向"生产基础设施"的必经之路。

这也是本系列的最后一篇。从 Agent Loop 的心跳、Tool System 的双手、Context Management 的记忆、SubAgent System 的团队协作、Permission & Sandbox 的免疫系统，到本文 Observability & Operations 的神经系统——我们完整地走过了 Agent Runtime 的六大核心子系统。每一个子系统都不是孤立的设计问题，而是同一个根本追问的不同侧面：如何把一个"会调 LLM 的程序"升级成"可长期运行的 Agent Runtime"。

参考文献

  1. OpenAI, “Integrations and observability — Agents SDK,” https://developers.openai.com/api/docs/guides/agents/integrations ↩︎

  2. Anthropic, “Claude Code,” https://code.claude.com/docs ↩︎

  3. OpenAI, “Codex CLI,” https://github.com/openai/codex ↩︎

  4. pi, https://github.com/badlogic/pi-mono ↩︎

  5. nanobot, https://github.com/HKUDS/nanobot ↩︎