健康检查

无需猜测即可验证 Gateway 与频道健康状况的简短指南。内容涵盖 CLI 健康检查、HTTP 探测端点、专门的 health 命令以及运行时间监控。

快速检查¶

• openclaw status - 本地摘要：网关可达性/模式、更新提示、已关联频道的认证时长、会话 + 近期活动。
• openclaw status --all - 完整本地诊断（只读、彩色，可安全粘贴用于调试）。
• openclaw status --deep - 向正在运行的网关请求实时探测（health 且 probe:true），在支持的情况下包括按账户的频道探测。
• openclaw status --usage - 显示模型提供方的用量/配额快照。
• openclaw health - 向正在运行的网关请求其健康快照（仅限 WS；CLI 无法直接连接频道套接字）。
• openclaw health --verbose（别名 --debug）- 强制进行实时健康探测并打印网关连接详情。
• openclaw health --json - 机器可读的健康快照输出。
• 在任何频道中发送独立聊天命令 /status，即可在不调用 agent 的情况下获得状态回复。
• 日志：运行 openclaw logs --follow（或 openclaw --profile <profile> logs --follow），并过滤 web-heartbeat、web-reconnect、web-auto-reply、web-inbound。

对于 Discord 和其他聊天提供方，会话行并不代表套接字活性。openclaw sessions、Gateway 的 sessions.list 以及 agent 的 sessions_list 工具读取的是已存储的会话状态。提供方可能在生成任何新的会话行之前就已重新连接并显示频道状态健康。请使用上面的频道状态和健康命令进行实时连接检查。

每个 agent 的会话计数和近期活动仅包含该 agent 自己的会话，即使多个 agent 共享同一个 SQLite 会话存储也是如此。status 在聚合时对每个物理存储只计数一次。顶层健康会话摘要代表默认 agent；当没有默认 agent 时，代表第一个配置的 agent；它并不是 fleet 的总数。正在运行的 Gateway 会从其常驻的会话行投影中提供干净的健康与状态会话摘要。存储水合（store hydration）和精确的脏行刷新保留现有的只读 SQLite 回退机制。

深入诊断¶

当大型 fleet 的模型准备超出启动预算时，openclaw health --json 会报告 modelRuntime.degraded: true。pendingAgents 列出仍在准备的 agent，stage 标识当前获取阶段。Gateway 保持运行，已完成的 agent 仍可使用。后台准备会在所有运行时就绪后清除降级状态。

健康与状态收集会将快速的会话存储读取分组为短小的工作切片，避免繁忙的后台准备延迟每一次独立读取。慢速读取会在让出其他 Gateway 工作之前完成其事务。

• 磁盘上的凭据：ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json（mtime 应较新）。
• 会话存储：ls -l ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。计数和近期收件人通过 status 显示。
• 重新链接流程：当日志中出现状态码 409-515 或 loggedOut 时，运行 openclaw channels logout && openclaw channels login --verbose。QR 登录流程在配对后遇到状态 515 时会自动重启一次。
• 诊断功能默认启用（diagnostics.enabled: false 可禁用）。内存事件记录 RSS/堆的字节计数以及阈值/增长压力。活跃度警告在进程运行但已饱和时记录事件循环延迟/利用率、CPU 核心比率，以及活动/等待/排队中的会话数量。超大负载事件记录被拒绝/截断/分块的内容以及大小和限制，绝不记录消息文本、附件内容、webhook 正文、原始请求/响应正文、令牌、cookie 或机密值。
• 同一个心跳驱动着有界稳定性记录器：openclaw gateway stability（或 Gateway 的 diagnostics.stability RPC）。Gateway 致命退出、关闭超时和重启启动失败会将最新快照持久化到 ~/.openclaw/logs/stability/ 下。使用 openclaw gateway stability --bundle latest 检查最新的 bundle。
• 如需提交 Bug 报告，请运行 openclaw gateway diagnostics export 并附上生成的 zip：其中包含 Markdown 摘要、最新的稳定性 bundle、经过脱敏的日志元数据、经过脱敏的 Gateway 状态/健康快照以及配置结构。聊天文本、webhook 正文、工具输出、凭据、cookie、账户/消息标识符和机密值均会被省略或脱敏。参见 Diagnostics Export。

健康监控器配置¶

• channels.<provider>.healthMonitor.enabled：对特定频道禁用 health-monitor 重启，同时保持全局监控启用。
• channels.<provider>.accounts.<accountId>.healthMonitor.enabled：多账户覆盖项，优先级高于频道级设置。
• 这些按频道的覆盖项目前适用于支持它们的频道：Discord、Google Chat、iMessage、IRC、Microsoft Teams、Signal、Slack、Telegram 和 WhatsApp。
• 崩溃的频道首先由其自身的自动重启退避机制恢复（日志中的 auto-restart attempt N/10）。健康监控器会一直保持不干预，直到该阶梯以 giving up after 10 restart attempts 结束，然后接管成为最后一个重启所有者。

入站接入健康¶

频道连接性和入站准入是相互独立的故障域。频道可以保持健康的传输连接（正常发送回复），但其持久化入站队列不可用，导致没有一条入站消息被准入。

• 当频道无法打开其持久化入站队列时，其启动会失败，网关将该账户记录为无法接收。openclaw channels status 会报告 Channel cannot admit inbound events; its durable ingress queue is unavailable. Outbound may still work.
• 无论传输状态如何，这样的账户都是 不健康 的，就绪检查会将其报告为失败。之前它会报告 health: healthy，健康监控器也从未干预它。
• 恢复仍然是自动的。入站判定描述的是该账户最近一次启动尝试，并会在下一次启动时清除，因此普通的重启路径同样适用于瞬时队列打开失败的恢复。这些重启在日志中记录为 health-monitor: restarting (reason: ingress-unavailable)，而不是通用的 stuck。
• 如果重启持续重复，说明原因并非瞬时问题。请检查日志中的入站失败：例如，某个插件拒绝了 openChannelIngressQueue 能力，这时需要操作员干预，而不是再次重启。
• 从不报告入站状态的频道不受影响：没有信号并不代表损坏。这里没有流量陈旧性启发式规则，因此一个真正安静的频道绝不会因为未收到任何消息而被标记为不健康。

HTTP 探针¶

网关暴露了三对无需认证的 GET/HEAD 探针：

当启动边车尚未完成时，/startupz 返回 503 并附带 status: "starting"；在排空期间返回 503 并附带 status: "draining"；其他情况返回 200 并附带 status: "started"。当流量准入需要使用可用的代理时，请使用 /readyz。被拒绝的默认或系统代理数据库会在任何迁移结果之后保持就绪状态为 false，并在 agentDatabases 中提供 failing: ["agent-database:<id>"] 以及准确的准入原因和修复提示。被拒绝的可选代理可以保持隔离，同时健康的代理继续处理请求。网关的就绪公告使用相同的就绪决策。

损坏的 Telegram 或其他通道账户也可能使 /readyz 返回 503，而 /startupz 仍保持 started。两个探针不能互相替代：仅完成启动并不代表代理或通道可用。

远程未认证的启动响应仅包含 ok 和 status。本地直连和已认证的调用者在启动尚未完成时还会收到 version、uptimeMs 和 pendingReason。就绪详情同样遵循仅限本地或已认证调用者的规则，因为其中可能指明发生故障的子系统。

共享状态完整性故障¶

终态共享状态准入失败会立即使 /ready 和 /readyz 返回 503，包括启动后由 SQLite 工作进程发现的故障。详细响应包含 failing: ["state-database"] 和 stateDatabase.reason，并附有记录的拒绝原因。这会绕过缓存的通道健康状态；探针直接读取准入所有者的记录结果，而无需查询 SQLite。

/healthz 仍报告 HTTP 存活状态。需要检测网关正在运行但无法准入工作的监管程序必须监控 /readyz。

插件替换恢复¶

在插件替换或恢复期间，/readyz 返回 503。详细响应包含 failing: ["plugin-reload"] 和一个 pluginReload 对象，其中包含受影响的 pluginIds、当前 phase（reloading、recovering 或 failed），以及任何恢复 deadlineAtMs 和可操作的 reason。这些由所有者报告的事实会绕过通道就绪缓存，因此失败的替换不会仅表现为一般的通道中断或过期的健康结果。

当替换操作暂停通道准入时，健康监控器不会尝试重启通道。成功回滚后，先前的插件配置会重启其通道，常规就绪检查也随之恢复。如果自动恢复到达截止时间，phase: "failed" 会保留失败原因和后续操作。准入暂停会被解除，使监控器能够重启可调用通道；插件如果仍持有已准入工作或清理所拥有的资源，则需要按照报告中的修复或重试操作后才能重新启动。有关恢复契约，请参阅配置热重载。

CPU 压力与事件循环延迟¶

详细就绪状态可包含最新已完成的 eventLoop 诊断快照。采样器拥有观察窗口；健康检查读取不会重置待处理的测量值。在第一个窗口完成之前，没有任何快照可用。其 cpuCoreRatio 衡量整个网关进程的用户和系统 CPU 时间，包括工作进程和原生线程，除以经过的墙钟时间。单位为核心当量：1 表示一个 CPU 核心在该时间间隔内被完全占用，并行工作可产生大于 1 的值。它不是宿主机总 CPU 容量的百分比。

health RPC 在返回缓存摘要或发布新收集的摘要时，也会读取最新完成的样本。慢速通道检查不会冻结其 CPU 或延迟读数。如果采样器重置，健康响应会省略 eventLoop，直到新窗口完成，而不会重新启用缓存的样本。

可选的 cpuBreakdown 区分独立的原生计数器：

• hostUtilization 是 os.cpus() 报告的宿主机 CPU 时间繁忙比例，范围从 0 到 1，横跨 hostCpuCount 个逻辑 CPU。这包括其他进程，并非网关的 CPU 配额或容器限额。
• mainThreadCoreRatio 使用 process.threadCpuUsage() 衡量网关主线程，而非事件循环利用率。
• workerCoreRatio 汇总任务池和 SQLite broker 所拥有的工作进程的 Worker.cpuUsage() 计数器。它不包括子进程、远程工作进程，或由这些所有者之外创建的工作进程。
• otherThreadsCoreRatio 是估算残差：进程 CPU 减去已衡量的主线程和受跟踪工作进程 CPU，下限为零。它包括未跟踪的工作进程和原生线程，而不是一个已衡量的工作进程类别。

线程值使用与 cpuCoreRatio 相同的核心当量单位。工作进程读取是异步的，且必须在每个采样边界 100 ms 内完成；这些并非跨线程的原子测量。残差会随测量偏差而变化。超时的请求绝不会延迟事件循环采样，且每个受跟踪工作进程最多有一个未完成的原生请求，即使在监控器重置后也是如此。启动、工作进程创建/退出、宿主机 CPU 拓扑变化、计数器重置和采集失败都需要在发布受影响的速率之前重新建立基线。缺失字段表示不可用，而非零。

主线程和主机计数器在 Node 和 Bun 上独立采集。 在 Bun 上，受跟踪的 worker CPU 和剩余值会被省略：其 worker API 在原生计数器采集失败时可能报告零。任何平台上不支持或失败的原生 API 都会使相应字段缺失。

Control UI 的 CPU 框通过 system.info.eventLoop 读取同一个采样器。 其详情浮层将主机使用率与进程和线程分解分开显示。进程和线程百分比使用 100% 表示一个完全占用的核心；主机使用率使用 100% 表示所有报告的逻辑 CPU。在首次完整测量之前，或不可用时，数值显示为短横线。

事件循环延迟和利用率单独描述主线程。cpu 降级原因报告进程 CPU 压力，并以延迟作为佐证；它不会识别消耗 CPU 的线程，也不会证明主线程挂起。请结合 CPU 压力检查延迟测量值。eventLoop 诊断本身不会改变就绪结果。

正常运行时间监控¶

外部正常运行时间监控服务应使用专用的 /health 端点，而不是 /v1/chat/completions。

• 应使用： GET /health - 即时响应，不创建会话，不调用 LLM，返回 {"ok":true,"status":"live"}
• 不要使用： 将 /v1/chat/completions 用于健康检查 - 每个请求都会创建一个完整的 agent 会话，包括技能快照、上下文组装和 LLM 调用

当未提供 x-openclaw-session-key 请求头或 user 字段时，/v1/chat/completions 会为每个请求生成一个新的随机会话。每 15 分钟 ping 一次的监控服务每天会创建约 96 个会话，每个会话消耗 4-22KB。长期来看，这会导致会话存储膨胀，并可能导致上下文窗口溢出。

监控服务配置示例¶

• BetterStack： 将健康检查 URL 设置为 https://<your-gateway-host>:<port>/health
• UptimeRobot： 添加一个新的 HTTP 监控器，URL 为 https://<your-gateway-host>:<port>/health
• 通用： 只要 Gateway 的 HTTP 服务器处于活动状态，任何对 /health 的 HTTP GET 都会返回 200 和 {"ok":true,"status":"live"}

故障处理¶

• logged out 或状态 409-515 -> 使用 openclaw channels logout 重新关联，然后使用 openclaw channels login。
• 无法访问 Gateway -> 启动它：openclaw gateway --port 18789（如果端口被占用，请使用 --force）。
• 没有入站消息 -> 确认已关联的手机在线，并且发送者被允许（channels.whatsapp.allowFrom）；对于群聊，请确保允许列表 + 提及规则匹配（channels.whatsapp.groups、agents.entries.*.groupChat.mentionPatterns）。

专用 “health” 命令¶

openclaw health 向正在运行的 gateway 请求其健康快照（CLI 不直接使用通道套接字）。默认情况下，它返回一个新的缓存 gateway 快照，并且 gateway 会在后台刷新该缓存；--verbose 会强制改为实时探测。 连接和缓存健康读取共享一分钟的后台刷新周期，因此重复的诊断连接不会每次都重建健康快照。针对缺失或过期健康的显式实时探测和刷新仍会立即执行。 快照描述已加载和已配置的通道。仅存储凭据不会激活通道或将其添加到 Gateway 健康中；请使用通道设置来启用它。 该命令在可用时报告关联凭据/认证年龄、每个通道的探测摘要、会话存储摘要和探测持续时间。实时探测使用有界的账户并发和由 Gateway 拥有的截止时间，因此一个慢账户会返回结构化超时，而已完成的同级结果仍可用。如果 gateway 无法访问或 Gateway 调用本身超时，该命令会以非零状态退出。

队列警告¶

成功的健康 RPC 会报告顶层 ok: true。该值表示 Gateway 生成了快照；它并不意味着每个投递队列都已清空。请检查 deliveryQueues.ingressPressure，以查看可能阻塞后续事件的持久入站通道。如果未找到受压通道，则省略该字段。

入站压力使用保守的内置诊断阈值，而不是任何插件的权威重试或认领策略。只有当活动待处理或已认领行已达到至少八次尝试并记录了投递错误，或者已认领行在 30 分钟内未刷新其认领时，才会出现持久通道。普通重试 1-7 不存在。没有记录错误的认领恢复增量也不存在，而活动认领保持不存在，因为其认领时间戳会被刷新。没有持久通道键的行会被省略，因为它们无法证明后续事件被阻塞；运行时会在真实的派生通道重试后持久化一个派生通道。

每个结果按通道账户分组，并报告受压通道、待处理、已认领和阻塞计数，以及最早受影响的接收时间。受压通道中的所有活动行都会计入这些计数。快照从不包含通道 ID、事件 ID、负载、认领所有者或令牌、记录错误，或会话和目标标识符。

选项：

• --json：机器可读的 JSON 输出
• --timeout <ms>：覆盖默认的 10 秒 Gateway 连接超时；它不会扩大 Gateway 内部实时探测截止时间
• --verbose：强制实时探测并打印 gateway 连接详情
• --debug：--verbose 的别名

健康快照包括：ok（布尔值）、ts（时间戳）、durationMs（探测时间）、每个通道的状态、agent 可用性、会话存储摘要，以及可选的投递队列警告。

相关¶

• Gateway 运行手册
• 诊断导出
• Gateway 故障排除
• openclaw health — 从 CLI 通过 RPC 请求此快照