OpenClaw 101｜15｜Observability and QA

OpenClaw 101 是一组面向 Agent Engineering 的系统拆解文章。它不把 OpenClaw 当成单一聊天产品，而是把它当作一个长期运行的 Personal Agent OS 来观察。

这一篇讲 Observability and QA。Agent QA 不能只靠单元测试。真实问题常发生在 live transport、streaming、tool call、threading、UI rendering 和长任务恢复之间。

读完本文，你应该能回答

• 一个 Agent OS 出错时应该从哪里查？
• run event、transcript、tool log、provider usage 分别提供什么证据？
• QA 应该覆盖哪些真实路径，而不是只测模型回复？
• 读完整个系列后，如何评估另一个 Agent 系统？

本篇在系列中的位置

收束篇，说明长期运行 Agent 如何被观察、测试、复盘和改进。OpenClaw 101 的主线是：先看控制面，再看执行面和状态边界，再进入上下文、能力系统、长期记忆、自动化、真实设备、扩展和 QA。本篇收束全系列，把 Gateway、Session、Loop、Context、能力系统和扩展重新汇总成一套评估框架。

贯穿案例

后文会反复使用同一个任务来落地抽象机制：用户在手机上对 OpenClaw 说：“帮我看一下这个 repo 的测试为什么失败；如果需要跑命令就先做，修好后在聊天里提醒我。”

在本篇中，重点观察这个任务在 Observability and QA 这一层会遇到的边界：谁接收它，谁拥有状态，谁能触发工具，谁记录结果，以及失败后从哪里恢复。

诊断信号表

核心判断

Observability 的目标是把一次 Agent run 变成可解释、可回放、可验证的证据链。

如果只看表面，很多 Agent 框架都像是“模型 + 工具 + UI”。但真正决定系统稳定性的，是这些边界如何被拆开：谁拥有状态，谁能触发副作用，谁负责恢复，谁暴露观察面，谁承担长期维护成本。

在 OpenClaw 里，Observability and QA 不是一个孤立模块，而是 Gateway、Session、Context、Tools、Plugins、Memory 之间的连接点。理解这个连接点，比记住某个命令或配置项更重要。

运行路径

一条真实消息进入系统后，大致会经过这些步骤：

• Gateway 产生 lifecycle、assistant、tool、chat、presence、health events。
• Transcript 保存用户消息、assistant 输出、工具结果和 compaction artifact。
• usage tracking 记录 provider/token/cost 信号。
• QA lanes 用 mock provider 或 live transport 覆盖不同渠道。
• Mantis 通过视觉端到端复现 bug，保存 before/after 证据。
• review 阶段检查 public page、image refs、SVG=0、泄露扫描、标题和正文一致性。

这些步骤看起来很多，但它们解决的是同一个问题：让 Agent 的行为从“模型临场发挥”变成“系统可控制、可观察、可恢复的运行过程”。

可迁移伪实现：Observability and QA

下面的伪代码是机制抽象，不对应 OpenClaw 的真实 API 或文件结构。

type Evidence = {
  runId: string
  sessionId: string
  events: RunEvent[]
  transcript: TranscriptSlice
  artifacts: Artifact[]
  publicVerification?: VerificationResult
}

async function reviewRun(runId) {
  return collectEvidence(runId).then(assertExpectedBehavior)
}

这段伪代码的重点不是函数名，而是边界：输入先被标准化，状态通过明确的 store 或 lane 管理，副作用通过 runtime 或 policy 执行，结果再回到 transcript、event stream 或 delivery target。

设计取舍

• 最终文本正确不代表系统正确；送达、thread、附件、权限都可能错。
• live QA 成本高，但能发现 mock lane 看不到的渠道问题。
• 证据应该绑定到 run、session、artifact，而不是只存在于控制台日志。

这些取舍解释了 OpenClaw 为什么不像一个最小 demo。最小 demo 追求路径短，长期系统追求边界清晰。路径短会让第一个 demo 很快跑起来；边界清晰才会让系统在多渠道、长会话、多人入口、插件扩展和自动化场景下不崩。

评估清单

评估任何 Agent 框架的 Observability and QA 设计，可以看这几个问题：

• 这个层级是否有明确 owner，还是散落在多个客户端或插件里？
• 它是否把状态、权限、运行时副作用和展示逻辑分开？
• 它是否能被观测、被调试、被回放？
• 它失败时是否有恢复路径，而不是只给用户一个模型错误？
• 它是否避免把 provider/channel/tool 的私有细节写死进 core？

如果这些问题没有答案，系统一旦从单用户 demo 走向真实使用，很快就会在上下文污染、重复副作用、权限失控、长任务丢失和调试困难中付出代价。

收束

到这里，OpenClaw 101 的主线就完整了：Gateway 接住世界，Agent Loop 执行工作，Session 维护状态，Context 决定模型输入，Tools/Skills/Plugins 扩展能力，Memory/Compaction 支撑长期运行，Channels/Nodes/Automation 把系统带入真实生活，Security/Operations/QA 让它可以被持续使用。

References

• QA overview
• Mantis
• Usage tracking
• Agent loop
• Gateway architecture