网关和服务恢复

这些章节介绍如何修复 Gateway 服务、其远程和 Control UI 的前置条件，以及其启动时使用的凭据。

Gateway 服务恢复¶

运行 openclaw gateway status --deep 以检查已安装的服务及其运行时，然后再选择恢复操作。对于缺失的服务，使用 openclaw gateway install；对于已安装但未加载的服务，使用 openclaw gateway start；或者从目标安装运行 openclaw gateway install --force 以替换其服务定义。外部管理的服务仍属于其管理程序。

Doctor 还会将服务的包路径和版本与活动 CLI 进行比较，而不需要 Gateway 连接。更新最终化和独立 openclaw doctor --fix 会通过原生安装程序协调符合条件的、此前正在运行的受管服务；更新期间的 Doctor 会报告漂移，并将发布延迟到最终化阶段。Doctor 可以自动刷新已验证且可写的打包服务中的仅安装漂移。它还会通过更新安装程序的备份事务修复已识别的过期原生策略，例如缺少 systemd KillMode=mixed 或 Scheduled Task 重启重试次数为零，然后再恢复因维护而停止的 Gateway。Doctor 会报告已更改的键和备份路径；受支持的自定义设置会在重写后保留。自动原生策略修复会保留未知的操作员编辑和不确定的定义，供操作员审查。其他命令或凭据更改仍需要交互式确认。在独立 openclaw doctor --fix 成功之后，如果已停止的受管 Gateway 的服务指向当前安装，并且最终检查明确验证了其所有权和离线状态，则会启动该 Gateway 并验证就绪状态。如果该检查失败、超时，或所有权不确定，Doctor 会记录原因并保持服务停止。在手动启动之前，使用 openclaw gateway status --deep 检查它。 更新期间的 Doctor 将激活留给更新程序。指向其他安装的已停止服务会保留其定义和停止状态；从目标安装运行报告中的配置感知 openclaw gateway install --force 命令以协调它（安装可能会启动服务）。当未配置端口时，它会保留服务的配置和显式服务端口。源代码检出、部署拥有的覆盖项以及不可用的原生检查不会授予自动安装修复权限；Doctor 会报告不匹配项和下一个修复操作。

如果 Doctor 在安装期间失去维护所有权，它会停止进一步的安装或激活，并在能够验证替换项的所有权时恢复其捕获的服务定义。警告会报告定义是未更改、已恢复还是需要检查；在当前维护或更新完成后，按照报告的状态和安装程序命令操作。未验证的恢复会保持恢复待定，而不是声称可以安全重启。

当显式修复停止受管 Gateway 时，Doctor 会等待该进程在服务停止期限内释放共享状态生命周期所有权，然后再修复状态。如果所有权仍被持有，Doctor 会发出警告、恢复服务并拒绝不安全的修复。在 macOS 上，失败的激活尝试会恢复 LaunchAgent 注册，以便其 KeepAlive 策略可以恢复；错误会报告作业是否已加载，如果 bootstrap 也失败，则提供恢复命令。模糊的 kickstart 错误后，如果探测确认作业不存在，则使用 bootstrap 恢复；成功激活后正常完成。对于仍保持加载的作业，其失败会保持可见。

Doctor 在获取两个维护协调器后重新检查更新准入。如果它必须在修复开始前取消，则会在其原生服务托管仍然有效时撤销其自身的停止操作。修复后的正常恢复仍需要当前更新准入。

如果 Doctor 的输出管道关闭（例如，openclaw doctor --fix | head -20），或者 Doctor 在维护期间收到 SIGINT、SIGTERM 或 SIGPIPE，它会等待已准入的修复工作和服务恢复完成后再退出。普通修复错误也会使用当前保存的配置恢复 Doctor 停止的受管服务。待批准的提示会取消，而不会中断已准入的写入。具体的数据风险、丢失的服务权限以及未验证的子进程清理仍会阻止不安全的激活，并报告恢复操作。

对于遗留服务或冲突的 systemd 作用域，请交互式运行 openclaw doctor 以审查发现并确认受支持的清理。清理会报告它移除或跳过了哪些内容；它不保证会安装替换服务。显式修复维护会跳过此单独的清理流程。

如果 Doctor 为修复停止了受管 Gateway，失败或超时的恢复探测会产生警告，Doctor 仍会尝试启动该服务并验证就绪状态。实时维护托管和更新准入仍然适用；观察到的服务命令、账户或管理器更改需要操作员审查。显式的所有权拒绝会作为拒绝报告，而不会尝试启动被拒绝的服务。在 systemd 上，Doctor 会在停止服务前保留原生管理器和单元标识，并在激活时重新验证它。如果无法捕获该标识，Doctor 会让服务保持运行并报告检查警告；实时状态写入器仍会阻止不安全的离线修复。

当服务检查阻止修复时，Doctor 和 gateway status --deep 会指明失败的原生探测：

• Linux 检查期限已过期： 管理器探测或其托管/准入保护用尽了检查预算。这并不意味着用户会话总线缺失。检查报告的恢复结果，并在恢复后运行 openclaw gateway status --deep。
• Linux 用户会话总线不可用： 检查服务账户的 XDG_RUNTIME_DIR 和 DBUS_SESSION_BUS_ADDRESS。仅有一个可用的 systemctl --user 命令是不够的：有效的服务检查还会使用 busctl --user。在 Debian/Ubuntu 上，安装 dbus-user-session，然后从该账户的用户会话运行 systemctl --user start dbus.socket。
• 探测无法启动（EACCES/EPERM）： 以服务账户身份检查可执行文件权限和目录访问权限。原生探测从文件系统根目录运行，因此通过 sudo -u 继承的不可访问操作员目录不会阻止检查。
• macOS GUI 域不可用： 在管理其 LaunchAgent 之前，请以目标用户身份登录桌面。gui/<uid> 的错误 125 并不能证明存在系统 LaunchDaemon。
• macOS 系统域不可用或检测到系统 LaunchDaemon： 让 root 检查 sudo launchctl print system/<label>，并通过其部署所有者停止自定义守护进程。若要保留该监督程序，请以状态拥有账户身份运行 Doctor，并使用现有的 OPENCLAW_SERVICE_REPAIR_POLICY=external 策略。保持与服务使用的 HOME、OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH 选择器相同。参见 现有系统 LaunchDaemons。

OpenClaw 不会管理自定义的系统 LaunchDaemons。以 root 身份运行 Doctor 并使用其他账户的 HOME，不会增加该能力，并且可能创建由 root 拥有的状态文件。

在任一平台上，当外部 supervisor 拥有 Gateway 时，请让该所有者停止它，并以状态拥有账户的身份运行 Doctor，同时设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。该现有策略会跳过原生维护检查和服务变更；它会保留 Gateway/状态协调器以及 agent 数据库租约检查。关闭和重启仍由部署所有者负责。原生探测失败永远不会被当作 Gateway 已停止的证明。

健康诊断同样将原生服务检查留给该外部所有者。它们仍会检查所选端口、运行中的 Gateway 所有权以及启动迁移活动。当这些均不存在时，Doctor 会及时报告不可用的 Gateway，而不是等待无关的原生服务管理器。运行中或正在启动的 Gateway 仍保留共享的就绪预算。

对于诸如 openclaw@.service 且带有 User=%i 的系统模板，检查会遵循当前账户的实例（openclaw@<user>.service），同时保留共享模板。在系统服务所有者停止其实例后，以该账户身份运行 Doctor。

Doctor 会使用共享的 60 秒就绪预算等待正在启动的本地 Gateway，无论是在其初始检查时还是在批准的重启之后。等待期间，它会报告观察到的启动阶段。如果在截止时间时 Gateway 仍报告正在启动，则会产生非失败的“仍在启动”结果；Doctor 会保持其运行，并且不会提供另一次重启。没有启动证据的连接失败仍然是诊断失败。当已安装的更新器调用候选 Doctor 时，这也适用。

插件初始化和数据库启动检查可能使冷启动在负载较高或较旧的主机上耗时超过十秒。在请求单独的重启之前，请让现有 Gateway 完成启动。远程 Gateway 诊断仍会使用已配置的远程目标。

远程 Gateway 恢复¶

当 gateway.mode: "remote" 时，Gateway 健康检查失败不会触发本地服务安装、启动、重启或 bootstrap 提示。请检查远程 URL、凭据以及 SSH 隧道或网络连接。如果 Gateway 本身需要恢复，请在运行它的主机上运行服务命令。回环远程 URL 可以是 SSH 隧道；这不会使 Gateway 成为本地服务。

有关连接检查，请参阅远程访问。其他 Doctor 配置和状态检查仍遵循所选的姿态。

Control UI 资产¶

对于源码安装，Doctor 可以构建缺失的 Control UI 资产，或在协议变更后重新构建过期资产。其手动构建命令包含检测到的 checkout 路径（pnpm --dir <checkout> ui:build），因此你可以从另一个目录运行显示的命令。请使用完整命令（包括其带引号的路径），而不是在不相关的项目中运行 pnpm ui:build。

没有 UI 源码的打包安装会收到重新安装指引，而不是源码构建命令。Doctor 不会下载源码 checkout 来修复打包安装。

无效的 Gateway 令牌¶

Doctor 会标记为空白或包含字面字符串 undefined 或 null 的活动 Gateway 令牌。Gateway 会在启动时拒绝这些值。要替换内联令牌，请运行 openclaw doctor --fix --generate-gateway-token，然后重启 Gateway。对于 SecretRef，请改为轮换外部密钥源；doctor 会保留其引用，并保持 password、none 和 trusted-proxy 认证模式不变。缺失的令牌仍会使用正常的启动令牌生成流程。

已知的脱敏占位符（包括 __OPENCLAW_REDACTED__）也是无效凭据。即使较旧的 Gateway 进程仍使用其先前的内存令牌正常工作，Doctor 和 gateway status --deep 也会指明受影响的引用。对于由存储支持的 Gateway 令牌，请运行 openclaw doctor --fix（或 openclaw doctor --generate-gateway-token）。Doctor 会验证数据库备份，重新生成被引用的值，保留 SecretRef 以及该条目当前的 secret/env 类型和允许的主机，并打印备份路径。备份期间发生更改的凭据会被保留。重启 Gateway，然后使用新令牌重新连接或重新配对设备。

显式令牌生成会报告其跳过健康 SecretRef 的情况。其他占位符密钥需要从其提供商处进行真实替换；Doctor 会报告它们，而不会删除其存储值。

在 trusted-proxy 模式下，被脱敏的内联或环境提供的可选密码不会阻止代理认证。启动、Doctor 和 status 会警告本地密码回退不可用。替换或移除可选密码并重启；Doctor 会保留 trusted-proxy 模式，而不是生成令牌。

macOS：launchctl 环境变量覆盖¶

如果你之前运行过 launchctl setenv OPENCLAW_GATEWAY_TOKEN ...（或 ...PASSWORD），当本地配置未提供凭据时，该值会提供回退凭据。已配置的内联凭据或活动 SecretRef 优先于其匹配的环境回退。过期的回退值在被选中时可能导致持续的“unauthorized”错误。

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD