> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 观察运行并诊断故障

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

## 从哪个标识开始

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

| 对象 | 观察重点 | 不应推断 |
| - | - | - |
| 控制平面健康 | 数据库、worker、凭据入口 | 所有云账户当前可用 |
| Session | 固定配置、生命周期、资源绑定 | 云进程一直存活 |
| Run | 阶段、等待、终态、输出 / 错误 | 终态意味着云资源已删除 |
| Runtime binding | 可达性、中断与恢复 | unreachable 等于进程已停止 |
| Sandbox | 最后观察到的云状态 | 睡眠等于资源不存在 |
| Resource operation | create/delete 意图、unknown、复核和重试信息 | 人工 acknowledged 等于清理完成 |
| Tool call | 参数、审批、dispatch 策略、结果与对账 | 超时等于没有写入 |

## 一次排障路线

假设界面长时间没有输出：先查询原 Run，而不是重提任务。如果是 waiting\_authorization / waiting\_approval，找到具体调用和待决定操作。如果处于 provisioning，检查 Sandbox 创建操作和执行阶段。如果 Runtime unreachable，观察原 invocation 的恢复状态，避免启动第二份进程。如果 Run 已完成，检查客户端事件 cursor 和最终结果读取。

可用 SDK 调用包括 `run`、`events` / `stream`、`tool_calls` / `toolCalls`、`session_initialization` / `sessionInitialization`。读取事件时每页有上限，需要继续补读；数据返回为空不证明执行终止。

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

对一条既有真实失败的[只读复查](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-docs-failure-correlation.json)，将 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 的详情与复核记录，再对照事件阶段与操作状态。实际标识保留在私有事故记录中。下面列出其他可能观察到的情况：

| 观察结果 | 如何解释 | 下一步 |
| - | - | - |
| Run 报创建错误，create operation 为 unknown | 任务观察不能证明是否已分配资源 | 保留原 operation/资源回执并对账 |
| 有 Provider 资源 ID，但 Runtime 不可达 | 分配成功和可用执行是不同阶段 | 检查该资源与 Runtime 恢复，不分配替代资源 |
| Run 失败，Session 为 closing | 任务结束，清理可能仍待完成 | 跟踪原删除与准备资源操作 |
| Run 已完成，但 UI 停止更新 | 执行可能正常，观察端可能落后 | 查询结果，并从保存 cursor 重放持久事件 |

资源详情提供 `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、执行阶段与相关操作；日志不泄露秘密；修复后保留原任务身份和恢复证据。依据：[诊断过滤](https://github.com/NexusFox88/docs/blob/main/resources/modules/diagnostics/failure.ts)、[恢复架构](https://github.com/NexusFox88/docs/blob/main/resources/docs/architecture.md)。下一步：[故障排查](https://docs.hexagon.autos/zh-CN/operate/troubleshooting.md)、[资源对账](https://docs.hexagon.autos/zh-CN/operate/reconciliation.md)、[事件与状态](https://docs.hexagon.autos/zh-CN/reference/events-and-states.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.