跳转到主要内容
从业务任务关联到 Session、Run、Runtime 和云资源操作,而不是用一个“Agent 状态”覆盖所有层次。控制平面活着、Runtime 可达、Run 完成和资源删除分别需要证据。

从哪个标识开始

应用保存业务 request ID、Session ID、Run ID、幂等键和事件 cursor。Console 中按对应 Session / Run 查看输入、初始化、事件、工具活动和资源状态。Run origin 可携带 request_id、message_id、channel,帮助关联来源;它不代替认证或业务归属。

一次排障路线

假设界面长时间没有输出:先查询原 Run,而不是重提任务。如果是 waiting_authorization / waiting_approval,找到具体调用和待决定操作。如果处于 provisioning,检查 Sandbox 创建操作和执行阶段。如果 Runtime unreachable,观察原 invocation 的恢复状态,避免启动第二份进程。如果 Run 已完成,检查客户端事件 cursor 和最终结果读取。 可用 SDK 调用包括 run、events / stream、tool_calls / toolCalls、session_initialization / sessionInitialization。读取事件时每页有上限,需要继续补读;数据返回为空不证明执行终止。

排查实例:云恢复完成后的执行失败

对一条既有真实失败的只读复查,将 Modal/OpenClaw OCI Run 的持久事件与同一 Session 的资源操作关联起来。事件顺序为 run.provisioning → workspace.inputs_verified → run.running → harness.starting → harness.running → harness.exited → run.failed。终态诊断为 harness_execution_failed,退出码 1,Runtime 状态 exited。 对应云端 create 与 restore 操作均为 completed;两条 delete 操作均为 completed,checkpoint 为 deleted。这将故障定位在资源准备之后的 Harness 执行阶段,不能据此判断资源分配失败或仍有资源未清理。仅凭诊断码也不能认定 Harness 的底层根因。应保留原 Run,在再次提交任务前调查私有执行历史。本次复查没有创建 Run 或云资源。 排查自己的故障时,查询已保存的 Run 并保留 session_id,遍历 resource operation 分页,只选择同一 Session 的记录,不取整个租户里最新的操作。读取相关 operation 的详情与复核记录,再对照事件阶段与操作状态。实际标识保留在私有事故记录中。下面列出其他可能观察到的情况: 资源详情提供 kind、state、provider_resource_id、provider_operation_id、provider_build_id、attempt_count、review_state、last_checked_at、next_check_at、reason 与过滤后的 failure。未获得回执时部分字段可能为空,缺少 Provider ID 不证明请求没有效果。真实 ID 保存在私有事故记录;公开报告保留因果顺序,不携带账户秘密或任务内容。 需要可分享的健康摘要时,npm run local -- diagnostics /absolute/new-report.json 创建具有私有权限的新文件,并拒绝覆盖。该允许列表投影刻意省略资源 ID 与私有端点,不能替代私有关联记录。分享前仍须检查报告。

日志与错误的解释

本地启动日志位于私有工作区的 service.log。故障诊断保留受控 category、数字 HTTP status,以及允许的 transport code,例如 ECONNRESET、ETIMEDOUT。实现刻意排除任意上游 message、URL、body 和随意 code,避免将凭据或用户数据泄漏到诊断。 这些字段帮助定位层次,不自动确定根因。401 可能来自不同服务,网络 reset 不能证明远端操作未执行。记录阶段、时间和关联 ID,再结合对应对象状态判断。

监控和告警

基于实际查询建立持续检查:等待时间过长的 Run、不可达 Runtime、未知创建 / 删除、closing 未完成、凭据入口异常、产物导出失败。阈值根据部署和任务性质配置,不在文档中编造统一 SLA。 当前指南不假设已提供 Prometheus endpoint 或 OpenTelemetry exporter。需要接入自己的监控系统时,从实际 API 和受控日志构建采集,先确认字段稳定性与权限。 验证故障诊断时,应能从一个业务请求定位原 Run、执行阶段与相关操作;日志不泄露秘密;修复后保留原任务身份和恢复证据。依据:诊断过滤、恢复架构。下一步:故障排查、资源对账、事件与状态。