日志与可观测性：如何看懂一次失败的调用

Agent 失败时最没用的问题是它为什么没回我更有效的问题是请求有没有进 Gateway session 路由对不对 run 有没有 accepted 模型调用有没有发出去 工具有没有启动 失败发生在 provider、tool、channel还是消息投递OpenClaw 的可观测性就是把一次看似模糊的失败拆成可定位的层。先说结论先按链路定位再看日志细节一次失败可以按这条路径排查入口消息 ↓ Gateway RPC / channel event ↓ Session routing ↓ Agent run accepted ↓ Context build ↓ Provider request ↓ Tool calls ↓ Final reply ↓ Channel delivery不要一上来就翻全文日志。先判断失败在哪一层再看对应证据。日志在哪里OpenClaw 有两个主要日志表面Console output 终端或 Gateway Debug UI 里看到的输出 File logs Gateway 写出的 JSONL 文件默认文件日志在/tmp/openclaw/openclaw-YYYY-MM-DD.log推荐用 CLI tailopenclaw logs --follow openclaw logs --follow --jsonControl UI 的 Logs tab 也会 tail 同一份 Gateway file log。日志级别和 verbose 不一样这是很多人会踩的坑。--verbose 主要影响 console verbosity 和 WebSocket log style logging.level 决定 file log 写到什么详细程度如果你想把 debug/trace 级别信息写进文件应该改{ logging: { level: debug } }而不是只加--verbose。关键线索id、session、subsystem、level看日志时优先找这些字段time level subsystem message agent_id session_id channel request id / run id / task id error code durationsession_id能帮你确认消息有没有进对上下文subsystem能告诉你是 gateway、channel、model、tool、browser、sandbox 哪一层duration 能帮你区分“卡住”和“失败”。Doctor、Health、Status 的分工常用排查命令openclaw doctor openclaw health openclaw status openclaw gateway health openclaw gateway probe可以这样理解doctor 检查配置、迁移、常见错误并给修复建议 health 看 Gateway 当前健康快照 status 看本地配置、连接、模型、通道、使用概况 probe 从客户端视角确认 Gateway 是否可达真实场景用户说“没回复”排查顺序可以是1. openclaw healthGateway 是否活着 2. openclaw logs --follow有没有收到 channel event 3. 搜 session_id是否路由到正确 session 4. 看 acceptedrun 有没有被创建 5. 看 provider模型是超时、429、认证失败还是不可用 6. 看 tool event工具是否被 approval、sandbox 或 policy 拦住 7. 看 delivery最终回复是否生成但发送失败很多“没回复”其实不是模型没想出来而是最终投递失败、channel rate limit、工具 approval 卡住或者 session 被路由到另一个会话。常见误解误解一没有终端输出就是没有日志不一定。文件日志和 console 是两个表面。误解二verbose 会自动写更多文件日志不会。文件日志由logging.level控制。误解三看到模型报错就一定要换模型先看是不是 rate limit、auth profile、timeout、context too large 或 tool schema 太大。误解四只看最终错误就够了不够。Agent 失败通常是链路问题要看从入口到投递的完整轨迹。最后总结可观测性的价值不是让日志变多而是让失败可以分层定位。一句话总结先定位失败层再读取对应日志先看结构化线索再看自然语言错误。本节作业运行openclaw logs --follow观察一条正常请求经过哪些 subsystem。用openclaw health和openclaw doctor分别解释它们解决的问题。找一条失败日志标出 session、channel、level、subsystem。画出“用户没收到回复”的排查链路。下一节预告下一节讲 Provider 抽象为什么 OpenClaw 可以接不同模型。参考资料OpenClaw DocsLoggingOpenClaw DocsGateway loggingOpenClaw DocsDebuggingOpenClaw DocsDoctorOpenClaw DocsHealth checks原文链接日志与可观测性如何看懂一次失败的调用 | Harries Blog™