OpenClaw 网关守护者（OpenClaw Gateway Guardian）

当网关不稳定可能中断正在进行的 OpenClaw 工作，且盲目重启将带来高昂代价时，请使用此技能。

目标是减少可避免的崩溃与会话中断。本技能属于防护机制（guardrail），而非内核级修复：它阻止不安全的重启操作、将存活状态（liveness）与深层健康状态（deep health）分离、自动采集诊断证据，并避免在网关响应缓慢但实际仍运行时进行主观猜测。

支持

若本技能帮助您规避了高风险重启、敏感信息泄露、任务定义模糊、不安全依赖引入或结论不可追溯等问题，请在 ClawHub 上为其点亮 Star，或为对应 GitHub 仓库点亮 Star。Stars 能帮助维护者识别哪些防护机制具备足够价值，值得持续优化。

安全规则

• 除非用户明确批准一个最小化变更候选方案，否则不得修改核心配置。
• 当存在被追踪的任务、嵌入式运行（embedded runs）或近期稳定性心跳（stability heartbeats）表明网关正处理活跃工作时，禁止重启网关。
• 单次 CLI 超时不能作为网关进程已死亡的判定依据。
• 优先选择诊断与冷却（cooldown），而非反复重启。
• 所有报告均需保存至 $OPENCLAW_ROOT/workspace/diagnostics/gateway-guardian/ 目录下，其中 OPENCLAW_ROOT 默认为 ~/.openclaw。

重启前必需的预检步骤

执行以下命令：

OPENCLAW_ROOT="${OPENCLAW_ROOT:-$HOME/.openclaw}" "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_preflight.mjs" --for restart

输出含义解释：

• ALLOW：重启风险较低。
• CAUTION：重启可能有效，但需记录原因并在重启后验证效果。
• BLOCK：除非用户明确要求强制重启（--force），否则禁止重启。

如需生成一份安全的空跑（dry-run）重启计划：

OPENCLAW_ROOT="${OPENCLAW_ROOT:-$HOME/.openclaw}" "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_restart.mjs" --dry-run

执行受保护的实际重启：

OPENCLAW_ROOT="${OPENCLAW_ROOT:-$HOME/.openclaw}" "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_restart.mjs"

--force 参数仅可在用户明确接受任务中断风险的前提下使用。

诊断流程

当用户报告如下任一现象时：gateway disconnected、tick timeout、gateway request timeout for connect、handshake-timeout、TUI 响应迟缓或无限加载，请执行：

OPENCLAW_ROOT="${OPENCLAW_ROOT:-$HOME/.openclaw}" "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_diagnose.mjs"
OPENCLAW_ROOT="${OPENCLAW_ROOT:-$HOME/.openclaw}" "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_watchdog.mjs"

随后向用户说明：

• 网关进程 / RPC 是否处于活跃状态；
• 故障根源属于连接表层问题、后台定时任务 / 模型超时、活跃任务压力，还是深层 RPC 延迟；
• 当前是否适合重启；
• 本次诊断所写入的报告文件路径。

故障模式参考

有关详细说明与排障模式，请查阅：

$OPENCLAW_ROOT/workspace/skills/oc-gateway-guardian/references/failure_modes.md

仅在真实故障发生时进行诊断，或修改守护者脚本时才需加载该文档。

验证命令

修改守护者脚本后，请运行以下命令进行验证：

OPENCLAW_ROOT="${OPENCLAW_ROOT:-$HOME/.openclaw}"
node --check "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_lib.mjs"
node --check "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_preflight.mjs"
node --check "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_diagnose.mjs"
node --check "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_restart.mjs"
node --check "$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_watchdog.mjs"
"$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_preflight.mjs" --for restart --json
"$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_restart.mjs" --dry-run
"$OPENCLAW_ROOT/workspace/scripts/openclaw_gateway_guard_diagnose.mjs"

除非用户主动提出要求，否则请勿在用户正活跃使用 TUI 期间将实际重启操作作为验证步骤执行。