OpenClaw 出现 split brain 安装、较新配置守卫拒绝操作时如何修复 PATH 与服务？

OpenClaw 出现 split brain 安装、较新配置守卫拒绝操作时如何修复 PATH 与服务？

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

这篇文章处理一个具体的故障：OpenClaw 更新完成后，Gateway 服务意外停掉，或者日志里显示正在运行的那个openclaw二进制，比最后一次写入openclaw.json的版本更旧。此时较新配置守卫会拒绝执行进程/服务变更，导致你重启不了网关、装不回服务。读完按下面步骤走，可以把 PATH 指回较新安装并重装 Gateway 服务，让服务恢复运行。

这个故障为什么会出现

OpenClaw 每次写配置都会打一个版本戳meta.lastTouchedVersion。读命令可以检查一份由更新版 OpenClaw 写出的配置，但从更旧的二进制执行"进程和服务的变更操作"会被拒绝。被拦下来的操作包括：Gateway 服务的 start/stop/restart/uninstall、强制服务重装、服务模式下的 Gateway 启动，以及gateway --force端口清理。

换句话说，"读"没事，"改"被卡住，根因就是你 shell 里解析到的openclaw是一个旧安装。

先确认版本分叉

按顺序执行，确认"当前 PATH 上的二进制"和"最后一次写配置的版本"之间确实存在分叉：

which openclaw openclaw --version openclaw gateway status --deep openclaw config get meta.lastTouchedVersion

判断依据：

• which openclaw给出的路径，是不是你期望的那个较新安装；
• openclaw --version与openclaw config get meta.lastTouchedVersion输出的版本号是否一致。若后者更新，就说明配置是更新版写的，而你正在跑旧二进制；
• openclaw gateway status --deep用于看服务当前到底起没起来（--deep会顺带扫描系统级服务）。

主路径：把 PATH 指回较新安装并重装服务

第 1 步，修 PATH。调整PATH，让openclaw解析到较新的那个安装，然后重新执行你原本想做的操作（例如openclaw gateway start）。这一步是必须做的：守卫拦下的都是"从旧二进制发起"的变更，PATH 没指对，后面重装也会被拒。

第 2 步，从较新安装重装 Gateway 服务。确认openclaw已指向新安装后，执行：

openclaw gateway install --force openclaw gateway restart

install --force会重写受管理的启动器和服务环境，restart让服务用新安装拉起。

第 3 步，清理仍指向旧二进制的残留。用which -a openclaw列出 PATH 上的所有openclaw位置，删除那些仍指向旧二进制的系统包残留或旧 wrapper 条目。这是可选但推荐的一步：只要 shell 里还能解析到旧二进制，问题会复发。

验证服务已恢复

重装并重启后，用下面的命令确认服务真的起来并在提供服务，而不只是"能连上"：

openclaw gateway status --deep openclaw doctor

健康信号（来自 runbook 的命令阶梯）：

• openclaw gateway status显示Runtime: running、Connectivity probe: ok，并有一行Capability: ...；
• openclaw doctor报告没有阻塞性的配置/服务问题。

如果Runtime仍不是 running，或doctor仍报服务问题，说明 PATH 或残留 wrapper 没清干净，回到第 1、3 步复查which -a openclaw的每一项。

可选分支：如果你其实是在故意降级

上面主路径假设"较新安装才是正确目标"。如果你的本意就是降级到旧版，请不要删守卫、也不要覆盖它去用旧代码跑已迁移的状态——应走文档给出的降级路径（见 Downgrade）：

• 降级不会回滚配置或数据库迁移；一旦状态迁移超出旧版支持的范围，支持的恢复方式是用匹配的 OpenClaw 版本恢复一份经过校验的更新前备份；
• 若目标版本还能读当前状态，用受管的回滚路径预览并执行：

openclaw update --tag <known-good-version> --dry-run openclaw update --tag <known-good-version>

<known-good-version>替换为你确认能读取当前状态的那个版本 tag。updater 会做兼容性检查并要求确认降级；若保存的 channel 是extended-stable，执行精确的一次性 tag 时需要加--channel stable。文档明确：不要绕过 newer-schema 或 newer-config 的拒绝。

恢复期间，为防止自动更新器立即把新版再拉回来，可在 Gateway 环境设置OPENCLAW_NO_AUTO_UPDATE=1。恢复后先验证再清理：

openclaw --version openclaw health openclaw gateway status --deep --json openclaw doctor --lint --json openclaw update cleanup --dry-run

边界与注意事项

• 不要删除meta.lastTouchedVersion，也不要用覆盖守卫的方式让旧代码跑在已迁移的状态上。
• Doctor 的服务修复同样受此约束：当配置最后由更新版写入时，Doctor 会拒绝从旧 OpenClaw 二进制改写、停止或重启 Gateway 服务（见 gateway-and-services）。所以"修好 PATH、指回新安装"是让 doctor / install 重新生效的前提。
• 本文对应的检索入口是 Troubleshooting runbook 的 "Split brain installs and newer config guard" 一节；若你的现象是protocol mismatch反复刷日志（回滚后新客户端还在连旧 Gateway），那是另一条排查路径，不要混用本文的服务重装步骤。

完成以上步骤后，openclaw gateway status --deep应稳定显示Runtime: running，openclaw doctor不再报阻塞问题，服务即恢复。若仍无法启动，把openclaw gateway status --deep、openclaw logs --follow和openclaw config get meta.lastTouchedVersion的输出一起对照，确认 PATH 解析与配置版本戳是否一致。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw