跳转至

网关与服务恢复

这些章节涵盖 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 的服务指向当前安装,并且最终检查明确验证了其所有权和离线状态,它就会启动并验证就绪状态。如果该检查失败、超时,或使所有权不确定,Doctor 会记录原因并保持服务停止。在手动启动之前,使用 openclaw gateway status --deep 检查它。更新期间的 Doctor 将激活交给更新程序。指向其他安装的已停止服务会保留其定义和停止状态;从目标安装位置运行所报告的感知 profile 的 openclaw gateway install --force 命令以对其进行协调(安装可能会启动服务)。当未配置端口时,它会保留服务的 profile 和显式服务端口。源代码检出、部署拥有的覆盖项以及不可用的原生检查不会授予自动安装修复权限;Doctor 会报告不匹配以及下一步修复操作。

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

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

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

在服务检查期间,Doctor 在重新检查实时更新所有权后,会复用已记录的更新延续回执。这避免了在服务管理器的检查期限内对未更改的回执重复执行完整的数据库完整性扫描。新的延续或接管回执仍会使用经过验证的账本写入器。

在 Linux 上,嵌套的服务管理器检查共享一个截止时间核算,该核算排除了同步所有权和准入检查。因此,缓慢的数据库检查不会消耗管理器的 I/O 配额。每个权限检查仍会运行;管理器调用、取消以及服务停止和排空截止时间仍保持有界。数据库检查仍可能增加命令总耗时。

恢复后,Doctor 会使用 openclaw gateway start 所用的共享健康探针来验证 Gateway。仅有一个正在运行的进程或已拥有的监听器并不意味着它已就绪。如果服务正在运行时就绪预算到期,Doctor 会保持其运行,并警告未验证就绪状态,包括在可用时报告观察到的启动阶段。运行 openclaw gateway status --deep 或 openclaw gateway diagnostics export 以进行调查;修复仍会完成。

当已退出的容器在绑定挂载的状态目录中留下 Gateway 锁时,Doctor 会使用 Gateway 启动时的命名空间和心跳策略。对于无法验证的容器所有者,它会最多等待 95 秒,并受任何活动服务停止期限约束;一旦其最后一次续期超过 90 秒,就会回收该锁。已经过期的锁无需等待。等待消息会指明持有者的主机、PID 命名空间和续期时长。如果持有者持续续期,Doctor 会保持状态不变,并报告重试前需要等待多久。同一主机上已验证的存活持有者必须先停止,普通修复才能继续;Doctor 会指明其 PID。由更新驱动的前台关闭会保留其现有的排空预算。不要删除活动 Gateway 可能仍然拥有的锁。

一旦 Doctor 拥有维护权,它会在同一所有权范围内检查更新请求者的当前权限。其自身的维护窗口不会触发锁等待或离线维护拒绝;请求者权限撤销仍会停止修复。

当维护无法获取状态所有权时,Doctor 会包含底层的 模式或文件系统错误。来自更新版本 OpenClaw 构建的共享状态数据库 保持不变;请使用支持该数据库版本的构建重新运行 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 选择器。参见 现有系统 LaunchDaemon。

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

对于任一平台,当外部监督程序拥有 Gateway 时,请让该 所有者停止它,并以状态拥有账户身份运行 Doctor,同时使用 OPENCLAW_SERVICE_REPAIR_POLICY=external。此现有策略会跳过原生 维护检查和服务变更;它保留 Gateway/状态 协调器和代理数据库租约检查。关闭和重启仍由 部署所有者负责。失败的原生检查永远不会被视为 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 健康检查失败不会触发 本地服务安装、启动、重启或引导提示。检查远程 URL、凭据以及 SSH 隧道或网络连接。如果 Gateway 本身 需要恢复,请在运行它的宿主上运行服务命令。回环远程 URL 可以是 SSH 隧道;它不会使 Gateway 成为本地服务。

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

Control UI 资源

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

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

Doctor 会报告旧安装遗留的过时 cache/control-ui-assets 目录。openclaw doctor --fix 会删除它们;更新命令的 Doctor 检查也会执行此修复。清理失败仅为警告,不会中止 Doctor。

无效的 Gateway token

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

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

显式 token 生成会在跳过健康的 SecretRef 时进行报告。其他占位符密钥需要由其提供方提供真实替换值;Doctor 会报告它们,而不会删除其存储值。

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

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw