以远程调用和真实健康检查管理 OpenClaw 网关，不把端口存在当健康｜OpenClawGateway

以远程调用和真实健康检查管理 OpenClaw 网关，不把端口存在当健康

我可以知道网关现在是否真的响应，并在故障时使用官方生命周期恢复，而不是见到端口就报好、见到历史非零就盲目重启。

当前情况：上次网关健康检查成功，也保留间歇超时；本轮未探测运行状态，旧成功不能证明现在持续可用。

项目快照核对于 2026-09-19 05:12（中国时间）；具体测试保留各自日期，页面不实时探测运行状态。

用途与实际影响

这项功能怎样使用

为什么需要它

端口可能由错误程序占着，旧任务失败也可能已恢复。要判断能否使用，需把网关响应、健康、监听位置和任务结果分开看。

举个实际例子

我可以说：“只读检查网关，健康就不要动；如果不健康，先告诉我是没启动、重复监听还是对外暴露，再决定怎样修。”系统不会把端口存在直接当成健康。

最后我会得到什么

交回网关能否响应、是否健康以及后台任务的实际状态；需要恢复时使用官方启动或重启，并再次读回。监听异常时不强行结束陌生进程。

正常时

配置可读，网关确实响应健康检查，本机监听和常驻任务都符合预期。

发现问题时

历史上有两次网关请求超时后自行恢复，也有偏慢响应；这份旧样本与当前健康分开保留。

入口不可用或证据不足时

监听位置或数量异常、网关不响应或任务缺失时停止自动恢复，交回具体层级。

从哪里开始

在已接通本机 OpenClaw 管理入口的 AI 对话中说“查 Gateway 健康”；需要恢复时再明确要求按现役入口修复。

需要准备什么

本次只查健康还是修复故障
看到的具体报错或症状

从开始到拿到结果

1
看网关是不是真的响应
检查配置、网关回应、健康和后台任务；端口亮着不足以证明能处理任务。
2
只修已确认的故障
健康就不动作；不健康时按官方入口启动或安全重启已识别的网关，监听异常先停。
3
修完再看一遍
重新检查网关和任务结果；仍失败就交回故障所在层，不强行结束陌生程序。

技术实现与依据

这里保留实现、关键条件、精确入口、历史记录和验证结果。

配置、远程调用、健康检查与单一回环端口 18789 通过；网关任务运行中，历史结果非零；心跳最近为 0

关键规则与设计选择

Gateway 当前可用结论来自 RPC/health，而不是只看 18789。

Heartbeat（心跳任务）最近 0 支持其最近一次执行成功，但不能擦除 Gateway 任务历史非零。

Update Disabled（更新任务停用）是设计状态；不能被 guardian（常驻核对器）当故障修复为启用。

-Repair 会改变 Windows 注册，本轮没有执行或证明真实故障自愈。

本模块用到的名词

safe restart（安全重启）: 由 OpenClaw 官方命令安排的重启；可能立即完成，也可能 deferred/coalesced（延迟/合并）。
LastTaskResult（上次任务结果）: 计划任务的历史退出结果，不是当前 Gateway health。
guardian（常驻核对器）: 默认只读检查 Windows 注册；只有显式 -Repair 才重注册。

专业定义

这条轴负责让一个且仅一个本机网关稳定常驻，并在真正不健康时才恢复。

解决什么

避免误杀占用端口的其他进程、重复拉起多个 Gateway，或用一次计划任务状态掩盖实际 RPC。

当前怎样实现

tools/_common.ps1 检查监听地址与唯一 PID（进程标识），并用 openclaw health --json --verbose 判断 ok（通过）与事件循环。
openclaw_heartbeat.ps1 健康时 exit 0（退出码 0）；无监听用 official start（官方启动），单一不健康监听用 official restart --safe（官方安全重启）。
guardian 默认只读；-Repair 优先 PCConfig 受控启动器，通用环境才走 openclaw gateway install。

执行流程

1
运行 config validate（配置校验）、gateway status --require-rpc（要求远程调用的网关状态）和 health（健康检查）。
2
检查 18789 监听者数量与地址。
3
读取 Gateway、Heartbeat、Update 各自 State（状态）和历史结果。
4
健康则不动作；不健康时按监听拓扑选择 start/restart 或失败关闭。
5
恢复请求后再次读 RPC/health 和任务姿态。

边界

不结束未知端口进程。
不把 Task State 当唯一健康标准。
不在非管理员环境偷偷降级执行 -Repair。

失败与恢复

18789 有非 loopback（本机回环）监听: 立即失败，不继续启停，避免改变错误或暴露的拓扑。
存在多个监听 PID（进程标识）: 停止并报告 unexpected listener count（监听者数量异常），不按任意 PID 猜主进程。
safe restart（安全重启）返回 deferred/coalesced（延迟/合并）: 结束当前请求并交给独立状态回读，不在调用进程死等。

真实入口

tools/_common.ps1

唯一 Gateway 生命周期与 health 实现

openclaw_heartbeat.ps1

按健康与监听拓扑恢复

openclaw_silent_boot_guardian.ps1

只读常驻检查与显式 -Repair

如何验证

9月9日03:40:41Z和03:42:43Z官方RPC超时；来源03:50Z和03:55Z回读exit0/rpc.ok=true/rpc.kind=read，8.465/9.499秒，同一Gateway PID未动。
9月7日配置与任务状态保留原日期；9月9日来源只读复核唯一回环监听与服务running，并确认临时health客户端已结束，不把一次恢复说成根治。
没有做真实重启、-Repair、故障注入或自愈验收。