跳转至

网关、服务与安全检查

检查 8-17 涵盖网关服务迁移、设备配对、安全警告、工作区状态、网关身份验证和健康状态,以及监督进程。

包根目录中有效的 openclaw-install-owner.json 标记标识应用拥有的安装。Doctor 会报告宿主名称和更新提示,并将包、捆绑 UI 和运行时替换交由该宿主处理,包括独立 CLI 检查应用拥有的 Gateway 服务时。对于 OpenClaw.app 负载,请更新应用以更新 Gateway;常规配置和状态检查仍然适用。

修复后,Doctor 会在有限的就绪预算内等待受管理的 Gateway。如果服务管理器仍报告其正在运行,但其监听器尚未打开,Doctor 会带警告和退出码 0 完成。一分钟后检查 openclaw gateway status。已停止或失败的服务仍会报告恢复失败;启动缓慢不会撤销已完成的修复。

检查 8-17

8. 网关服务迁移和清理提示

交互式运行 openclaw doctor,以审查旧版网关服务(launchd/systemd/schtasks)并确认受支持的清理。显式修复维护会跳过此单独的清理流程。移除与安装分开报告;当预期的原生服务缺失时,使用 openclaw gateway install。Doctor 还可以扫描多余的类网关服务并打印清理提示。以配置文件命名的 OpenClaw 网关服务被视为一等服务,不会被标记为 “extra”。

清理预览仅包括用户范围内的旧版 launchd 服务和已识别的旧版 systemd 单元名称。旧版 Windows 服务、无法识别的 Linux 单元名称以及系统范围内的服务仍作为发现项保留,供人工审查。

Windows 额外服务提示使用只读 schtasks /Query 检查。节点主机在诊断中仍然可见;仅发现某服务并不会使其成为移除目标。无法读取的无关计划任务不会阻止发现或测试运行时准备,无论它们是否正在运行。对于选定的任务、已识别的 OpenClaw 启动器以及包含 OpenClaw 启动器内容的自定义别名,如果无法验证其命令,仍会报告检查不完整。

Linux 用户服务清理会在停止或禁用服务失败时保留单元文件。中断的状态检查不允许仅删除文件;该回退仅在 systemctl 不可用时报告。

在 Linux 上,如果缺少用户级网关服务,但存在系统级 OpenClaw 网关服务,doctor 不会自动安装第二个用户级服务。使用 openclaw gateway status --deep 或 openclaw doctor --deep 检查,然后移除重复项;当系统监督进程拥有网关生命周期时,设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。

8b. 启动 Matrix 迁移

当 Matrix 频道账户存在待处理或可操作的旧版状态迁移时,doctor(在 --fix / --repair 模式下)会创建迁移前快照,然后运行尽力而为的迁移步骤:旧版 Matrix 状态迁移和旧版加密状态准备。这两个步骤均非致命;错误会被记录,启动继续。如果没有显式修复(--fix、--repair 或 --yes),此检查会被跳过。

8c. 设备配对和身份验证漂移

Doctor 将设备配对状态作为常规健康检查的一部分进行检查,并报告:

  • 待处理的首次配对请求
  • 已配对设备的待处理角色或范围升级
  • 公钥不匹配修复:设备 ID 仍然匹配,但设备身份不再与已批准记录匹配
  • 已配对记录缺少已批准角色的有效 Token
  • 已配对 Token 的范围偏离已批准的配对基线
  • 当前机器的本地缓存设备 Token 条目早于网关侧 Token 轮换,或携带过期的范围元数据
  • 已弃用的 identity/device-auth.json 文件仍然存在,并阻止检查本地缓存 Token,包括在远程 Gateway 模式下;停止 Gateway 并运行 openclaw doctor --fix 以完成迁移或清理
  • 本地 Gateway 上已弃用的 devices/*.json 和 nodes/*.json 存储;停止 Gateway 并运行 openclaw doctor --fix,在节点能力之前导入设备批准并归档原始文件。现有 SQLite 记录优先;无法读取的源保留在原处以供修复。

Doctor 不会自动批准配对请求或自动轮换设备 Token。它会打印确切的后续步骤:

  • 使用 openclaw devices list 检查待处理请求
  • 使用 openclaw devices approve <requestId> 批准确切的请求
  • 使用 openclaw devices rotate --device <deviceId> --role <role> 轮换新 Token
  • 使用 openclaw devices remove <deviceId> 移除并重新批准过期记录

这区分了首次配对、待处理的角色/范围升级以及过期的 Token/设备身份漂移,从而堵住常见的“已配对但仍提示需要配对”漏洞。

仅当配置请求节点执行或浏览器节点目标、允许节点命令、通过 CIDR 或 SSH 验证选择加入远程配对,或显式启用/配置 device-pair 插件时,才会检查节点托管前提条件。插件的捆绑默认值、空节点设置和仅拒绝策略不会请求托管。因此,仅本地的回环 Gateway 不会收到节点托管警告;远程客户端配置文件将这些检查交给服务器。显式配对和加入码请求仍会报告源不可达。此仅诊断变更不会重写配置或更改更新修复。

9. 安全警告

Doctor 仅在发现警告时发出安全说明,例如提供商在未设置允许列表的情况下向 DM 开放,或危险配置的策略。使用 openclaw security audit 获取完整的安全清单。

缺少多智能体 DM 路由所有权会作为发现项报告。它不会阻止其余频道安全检查或待处理状态迁移。在期望该路由正常工作之前,配置所报告的账户绑定。Telegram 账户发现在升级预览期间保留旧版默认智能体账户选择,无需环境智能体。

10. systemd linger(Linux)

如果作为 systemd 用户服务运行,doctor 会确保 lingering 已启用,以便 Gateway 在注销后保持存活。

11. 工作区状态(技能和插件)

Doctor 会打印默认 agent 的问题和操作,而不是健康状态清单:

  • 技能:列出已允许但不可用的技能名称;使用 openclaw skills check 查看需求详情和完整计数。
  • 插件:仅报告出现错误的插件 ID;使用 openclaw plugins list 查看已加载、已导入、已禁用以及捆绑插件清单。
  • 插件兼容性警告:标记与当前运行时存在兼容性问题的插件。
  • 插件诊断:显示插件注册表发出的任何加载时警告或错误。
  • Claude CLI:仅报告二进制文件、认证、配置文件、工作区或项目目录问题;健康检查详情会被省略。
11b. Bootstrap 文件大小

Doctor 会检查工作区 Bootstrap 候选文件(AGENTS.md、SOUL.md、IDENTITY.md、USER.md、BOOTSTRAP.md 和 MEMORY.md),并在运行时过滤后对照配置的字符预算。根目录的 BOOTSTRAP.md 在工作区设置完成后会被排除。它会报告每个文件的原始字符数与注入字符数、截断百分比、截断原因(max/file 或 max/total),以及总注入字符数占总预算的比例。当文件被截断或接近上限时,doctor 会打印调优 agents.defaults.bootstrapMaxChars 和 agents.defaults.bootstrapTotalMaxChars 的提示。USER.md 是例外:它有固定的 4,000 字符上限,这些设置无法提高该上限,因此 doctor 会指明该上限,并建议改为压缩文件内容。参见 用户模型。

这包括捆绑的 bootstrap-extra-files hook 声明的文件,前提是全新 Gateway 启动时会选择该 hook,并且每个匹配的 basename 都是上述六个文件之一(例如 packages/core/AGENTS.md)。其他 basename 会被忽略。Doctor 使用每个 agent 的工作区和限制,而不导入或运行自定义 hook 处理器。它预测的是全新启动时的选择,而不是运行中的 Gateway 在 hook 重载失败后可能保留的上一代处理器。

11c. Shell 补全

Doctor 会检查当前 Shell(zsh、bash、fish 或 PowerShell)是否已安装 Tab 补全:

  • 如果 Shell 配置文件使用了缓慢的动态补全模式(source <(openclaw completion ...)),doctor 会将其升级为更快的缓存文件变体。
  • 如果配置文件中已配置补全,但缓存文件缺失,doctor 会自动重新生成缓存。
  • 如果完全未配置补全,doctor 会提示安装它(仅限交互模式;使用 --non-interactive 时跳过)。

运行 openclaw completion --write-state 可手动重新生成缓存。

11d. 过期通道插件清理

当 openclaw doctor --fix 移除缺失的通道插件时,它还会移除引用该插件的悬空通道范围配置:channels.<id> 条目、指定了该通道的心跳目标,以及 agents.*.models["<channel>/*"] 覆盖。这可防止 Gateway 启动循环:通道运行时已不存在,但配置仍要求 Gateway 绑定到该通道。

11e. 项目克隆形态

Doctor 检查以 source: "cloned" 注册的已存储项目克隆。它会报告项目名称和路径、浅克隆状态、每个 remote.*.partialclonefilter 和 remote.*.promisor 键(包括以 URL 为键的孪生键),以及存在时的 extensions.partialclone。类似地址的名称会用 *** 替换 userinfo,并省略查询字符串和片段,包括非标准 URL 的 remote-helper 和 scp 类似地址。完整克隆不会产生发现项。缺失或不可读的克隆会被报告为跳过;其他项目仍会被检查。Agent 工作区和手动注册的检出不在此检查范围内。

每个克隆使用三次本地 Git 读取,每次限制为五秒和 64 KiB 的捕获输出。Doctor 不会执行 fetch、repack 或更改克隆配置,即使使用 --fix。部分克隆支持 managed-worktree 对象预取,但完整克隆可避免 checkout 和快照恢复期间的缺失对象和浅历史故障。

要获取聚焦的只读报告,请运行:

openclaw doctor --lint --only core/doctor/project-clone-shape --json

该检查也会在普通 Doctor 和 --lint --all 中运行;它被排除在默认 lint 配置文件之外。Lint 通过 Doctor 的私有状态快照检查注册表。

请在可访问 origin 的 POSIX shell 中按 Doctor 打印的命令操作。任何步骤失败时请停止。对于具有常规 origin 键的浅部分克隆,序列如下:

cd /path/to/project-clone
git config --unset-all remote.origin.partialclonefilter
git fetch --refetch --unshallow origin
git rev-list --objects --missing=print --all | grep '^?' | cut -c2- | git fetch origin --no-tags --no-write-fetch-head --recurse-submodules=no --stdin
git config --unset-all remote.origin.promisor
git repack -a -d

在重新 fetch 之前,取消设置 所有 报告的 partialclonefilter 键,包括类似 remote.https://github.com/openclaw/openclaw.git.partialclonefilter 的键。如果仓库不是浅克隆,请省略 --unshallow;Git 会拒绝在完整历史上使用该选项。在通过 ID fetch 缺失对象之前,请保留 promisor 设置;然后取消设置所有报告的 promisor 键,以及存在时的 extensions.partialclone,再执行 repack。Doctor 会为不含 ://、:: 或 @ 的普通远程名称打印精确的 unset 命令。对于类似地址的条目,在继续之前请遵循本地查找和 unset 说明;原始键可能包含凭据,且不得复制到共享报告中。脱敏名称用于标识该条目,但不是其字面 Git 配置键。

Git 在远程键被取消设置且仓库重新打包后,仍可能保留 objects/pack/*.promisor 伴生文件。这些伴生文件无害:OpenClaw 根据 Git 配置而非这些文件来确定部分克隆修复可用性。要移除过期的磁盘标签,请先确认下面的缺失对象命令没有输出,并且 git fsck 成功:

git rev-list --objects --missing=print --all | sed -n 's/^?//p'
git fsck --full

然后仅将伴生文件移出 pack 目录,并将其保留为可恢复备份,直到下一次 Doctor 和受管 worktree 成功运行:

promisor_marker_backup="$(git rev-parse --git-dir)/retired-promisor-markers"
mkdir -p "$promisor_marker_backup"
find "$(git rev-parse --git-dir)/objects/pack" -maxdepth 1 -type f -name '*.promisor' -exec mv -n {} "$promisor_marker_backup"/ \;
git fsck --full

之后重新运行 Doctor。如果历史或对象仍然缺失,请从原始仓库恢复它们。Origin 可能不包含仅本地的快照;参见快照恢复。

12. Gateway 身份验证检查(本地 Token)

Doctor 检查本地 Gateway Token 身份验证就绪状态。

  • 如果 Token 模式需要 Token 且不存在 Token 来源,Doctor 会提供生成一个 Token 的选项。
  • 如果 gateway.auth.token 由 SecretRef 管理但不可用,Doctor 会发出警告,并且不会用明文覆盖它。
  • 当健康的 SecretRef 使生成变得不必要时,openclaw doctor --generate-gateway-token 会报告这一点。
  • 如果由存储支持的 Token 解析为已知的脱敏占位符,--fix 或 --generate-gateway-token 会验证数据库备份,并在保留其 SecretRef 的同时重新生成该条目。Doctor 会打印备份路径以及重启/重新配对指引。其他外部密钥需要在源头替换。
12b. 只读 SecretRef 感知修复

某些修复流程需要检查已配置的凭据,同时不削弱运行时 fail-fast 行为。

  • openclaw doctor --fix 针对定向配置修复,使用与 status 系列命令相同的只读 SecretRef 摘要模型。
  • 示例:Telegram allowFrom / groupAllowFrom @username 修复在可用时会尝试使用已配置的 bot 凭据。
  • 如果 Telegram bot Token 通过 SecretRef 配置但在当前命令路径中不可用,Doctor 会报告该凭据已配置但不可用,并跳过自动解析,而不是崩溃或将 Token 误报为缺失。
13. Gateway 健康检查 + 重启

引导式 Doctor 会运行健康检查,并可以为本地 Gateway 提供恢复,具体取决于服务所有权和确认。远程健康检查失败不会触发本地服务恢复,即使远程 URL 是回环 SSH 隧道。请检查远程连接,并在其主机上恢复 Gateway。已接受的交互式维护会恢复其停止的匹配服务,并保留已停止的服务。显式修复维护会恢复其停止的匹配服务。在成功独立运行 openclaw doctor --fix 之后,它还会启动并验证一个已停止的受管 Gateway,其服务指向当前安装。更新期间的 Doctor 将激活交给 updater。在两次重启之间已加载且启用的 macOS 作业不会被视为有意停止的服务。

13b. 内存搜索就绪状态

Doctor 检查为默认 agent 配置的内存搜索嵌入提供商是否就绪。行为取决于所配置的提供商:

  • 显式本地提供商:检查本地模型文件或可识别的远程/可下载模型 URL。如果缺失,建议切换到远程提供商。
  • 显式远程提供商(openai、voyage 等):验证 API key 是否存在于环境或 auth store 中。如果缺失,打印可操作的修复提示。
  • 旧版 auto 提供商:将 memorySearch.provider: "auto" 视为 OpenAI,检查 OpenAI 就绪状态,并且 doctor --fix 会将其重写为 provider: "openai"。

当有缓存的 Gateway 检查结果可用时(检查时 Gateway 健康),Doctor 会将其结果与 CLI 可见配置进行交叉引用,并记录任何差异。Doctor 不会在默认路径上启动新的嵌入 ping;如果你想要实时提供商检查,请使用深度内存状态命令。

使用 openclaw memory status --deep 在运行时验证嵌入就绪状态。

嵌入提供商就绪状态是健康检查,而不是状态迁移。Gateway 启动不会在就绪检查期间初始化内存嵌入提供商,因此 auth-profile SecretRef 可以在之后激活。如果嵌入仍然不可用,内存同步会保留现有语义索引,而不是用仅 FTS 数据替换它。就绪警告允许降级启动;导致必需状态读取不安全的错误仍会阻止 Gateway 就绪。

14. 通道状态警告

如果 Gateway 健康,Doctor 会运行通道状态检查,并报告带有建议修复的警告。

15. Supervisor 配置审计 + 修复

普通 Doctor 检查会检查已安装的 supervisor 配置(launchd/systemd/schtasks)中缺失或过时的默认值(例如 systemd network-online 依赖和重启延迟),并可以提供交互式修复。显式修复维护会跳过这个独立的服务重写阶段,但会通过原生安装器协调先前运行服务中符合条件的安装漂移。已停止的服务保留其启动器和停止状态。从预期安装运行 openclaw gateway install --force 以替换启动器和受管环境。

在 Linux 维护停止之前,策略刷新会备份过时的 OpenClaw unit 设置,确认 daemon-reload,并验证有效的 TimeoutStopSec 覆盖排空和清理(当前为 330 秒)。此刷新保留启动器、环境和操作员 drop-in;离线服务可以在不启动的情况下接收它。较短或未知的常驻关闭预算会在停止前使用有界生命周期排空。在更新截止时,报告的写入控制权会以所有者阶段拒绝停止;剩余已接受的轮次或未知控制权会产生警告,并且停止继续。

备注:

- 较旧的安装标记不会使自定义原生设置可以安全替换。自动协调仅修复缺失或已识别的已发布默认值;无法识别的基础单元、LaunchAgent 或 Scheduled Task 设置将保持不变并附带诊断信息。Linux 操作员 drop-in 永远不会被重写。
- 在 macOS 上,协调会识别由 2026.4.29 安装程序生成的完整默认 PATH,并在备份定义后将其刷新为当前服务 PATH。新增的自定义条目和其他无法识别的值仍受保护,包括对生成的环境文件内部的编辑。如果可选的 user-bin 目录自安装以来已发生变化,旧 PATH 将保持无法识别状态,而不是被丢弃。
- 如果备份或迁移子进程清理无法确认其拥有的工作已停止,则其写入托管阻塞器将在 Gateway 进程生命周期内持续存在,即使命令已报告错误。自动维护不会在超时时清除它。部署所有者必须在替换 Gateway 进程之前独立验证该工作已停止。
- 在服务修复同意之前,Doctor 会预览计划中的运行时、入口点、PATH 以及任何已记录的关闭预算修复。预览会列出修复将保留的运行时和 source-checkout 发现,并在批准的修复后重复列出它们。如果没有可用的受支持系统 Node,重新安装仍可以保留已记录的运行时并修复其他服务设置;安装受支持的系统 Node 并重新运行 Doctor 以解决该发现。当 source-checkout 启动器仍是预期安装时,它会保留。
- `openclaw doctor` 在重写 supervisor 配置前会提示。单独的 `openclaw doctor --force` 仍保持引导式:它允许激进的修复选项,但对于符合条件的服务重写仍需要交互式同意。只有在引导式托管同意后,它才会进入维护模式,并保留所有权和写入访问检查。
- `openclaw doctor --yes` 接受默认的非服务修复提示,并在上述策略刷新和安装漂移规则下进入维护模式。
- `openclaw doctor --fix` 无需提示即应用推荐修复(`--repair` 是别名;`--yes` 也会进入修复维护)。它会在插件或可变状态检查之前停止匹配的受管 Gateway,验证修复,并重启同一服务一次,即使不需要任何更改。它会协调符合条件的安装漂移,保留操作员启动器,仅启动一个受拥有的、指向当前安装的离线服务,并拒绝停止祖先 Gateway。普通交互式 Doctor 会检查 schema 兼容性,并在请求剩余修复的维护同意之前提供更新,同时保留单独的修复提示;拒绝托管会跳过修复,并在同一调用中继续只读 `--lint` 检查,使服务和持久化状态保持不变。自定义状态目录不会采用原生服务。
- 显式修复会拒绝不可用的服务检查以及可能仍在运行的未匹配服务。在其所有者停止它们并且原生管理器确认它们已离线后,Doctor 会修复其选定的状态,而不更改或启动这些服务。已禁用的 systemd 单元仍可能正在重启;Doctor 会检查运行时状态以及安装状态。
- 更新器的显式 Gateway 激活策略会将停止/重启所有权保留给更新器。Doctor 仍要求原生证明服务已离线;一个处于活动状态的 `update --no-restart` 修复会在不停止或重启该服务的情况下失败。在重试更新之前,通过其所有者停止该服务。没有该策略的旧更新父进程保留普通 Doctor 维护。
- `openclaw doctor --fix --force` 使用相同的策略刷新和安装漂移规则。使用 `openclaw gateway install --force` 请求重写;操作员拥有的 systemd drop-in 保持不变。
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` 使 doctor 对 gateway 服务生命周期保持只读。请部署所有者停止 Gateway,以状态拥有账户运行 Doctor,然后通过该所有者重启。该策略会跳过原生维护检查和服务变更,包括 install/start/restart/bootstrap、supervisor 配置重写以及旧版服务清理。它会保留 Gateway/状态协调器和 agent-database 租约检查,报告服务健康状况,并运行非服务修复。参见 [现有系统 LaunchDaemons](../index.md#existing-system-launchdaemons)。
- Doctor 和 `gateway status --deep` 会分别指明不可用的 launchd 域、缺失的 systemd 用户会话总线以及原生检查访问拒绝。Linux 指南涵盖 `XDG_RUNTIME_DIR`、`DBUS_SESSION_BUS_ADDRESS` 和 `dbus-user-session`;外部监督的部署会收到上述现有策略。参见 [Gateway 和服务恢复](../../cli/doctor/recovery.md)。
- 在活动的 Linux 服务检查中,如果其会话总线停止,OpenClaw 可以保留经过身份验证的用户管理器的私有连接。类型化命令和运行时读取仅针对该原始管理器和单元继续。缺失的初始管理器身份或已被替换的管理器仍不可用;OpenClaw 不会启动总线或选择另一个管理器。此只读恢复不会更改服务启动/停止权限。

- 在 macOS 上,同标签的系统 LaunchDaemon 会阻止用户 LaunchAgent 安装、启动、重启和 bootstrap 修复。Doctor 会报告系统所有者并停止服务恢复;`--force` 不会绕过此所有权边界。参见 [现有系统 LaunchDaemons](../index.md#existing-system-launchdaemons)。
- 在 Linux 上,当匹配的 systemd gateway 单元处于活动状态时,doctor 不会重写命令/入口点元数据。如果已停止单元的命令或工作目录被操作员拥有的 systemd drop-in 覆盖,请使用 `systemctl --user cat <unit>.service` 检查它,然后更新或移除该 drop-in;重写受管基础单元无法更改有效启动器。`Environment=` drop-in 仍受支持。Doctor 还会在重复服务扫描期间忽略非活动的非旧版额外 gateway 类单元,以便伴随服务文件不会创建清理噪音。
- 在 Linux 上,doctor 在持久化恢复的 gateway token 之前会检查对已安装和计划服务文件的权限。如果该检查阻止服务修复,则修复会保持配置和 token 不变,并报告如何恢复检查访问权限或联系部署所有者;`--force` 无法绕过它。无关的 Doctor 配置修复不受影响。
- 当服务修复必须保留从环境或旧服务恢复的 token 时,Doctor 会要求显式交互式确认,并默认选择 No。它会重用相同的共享存储条目而不更改它,或通过 secret-store 所有者保存一个新的受保护条目,然后仅将其 SecretRef 写入 `gateway.auth.token`。非交互式运行(包括 `--yes`)会跳过此步骤并发出警告。更新期间的 Doctor 仍会将服务修复推迟到更新最终化。
- 在添加存储条目之前,Doctor 会备份现有的状态数据库;其常规配置写入器会在发布前备份配置。如果配置发布失败,Doctor 会跳过服务重写并保留已保存的条目,因为已提交或并发的引用可能已经在使用它。解决报告的失败并重新运行 Doctor 以重用该条目;在引用不确定时不要删除它。
- 如果 token 身份验证需要 token,并且 `gateway.auth.token` 由 SecretRef 管理,则 doctor 服务安装/修复会验证 SecretRef,但不会将已解析的明文 token 值持久化到 supervisor 服务环境元数据中。
- Doctor 会检测由旧版 LaunchAgent、systemd 或 Windows Scheduled Task 安装内联嵌入的受管 `.env`/SecretRef 支持的服务环境值,并重写服务元数据,使这些值从运行时源加载,而不是从 supervisor 定义加载。
- Doctor 会检测在 `gateway.port` 更改后服务命令仍固定旧 `--port` 的情况,并将服务元数据重写为当前端口。
- 如果 token 身份验证需要 token,并且已配置的 token SecretRef 未解析,则 doctor 会阻止安装/修复路径并提供可操作的指导。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`,并且 `gateway.auth.mode` 未设置,则 doctor 会阻止安装/修复,直到显式设置 mode。
- 对于 Linux user-systemd 单元,doctor token 漂移检查在比较服务身份验证元数据时会同时包括 `Environment=` 和 `EnvironmentFile=` 源。
- `OPENCLAW_SERVICE_MANAGED_ENV_KEYS` 跟踪 OpenClaw 从 config、`.env` 或 SecretRefs 重新生成的值;它不是操作员保留允许列表。Systemd 会将操作员 `Environment=` 和 `EnvironmentFile=` drop-in 合并到有效环境中,并且 `gateway install --force` 会保持这些 drop-in 及其文件不变。Doctor 不会将它们的值复制到受管基础单元中,也不会建议重新安装以迁移仅操作员管理的键。无法读取或未验证的 drop-in 仍需要检查。Linux 重新安装会按现有顺序保留已接受的 PATH 条目,包括安全的额外目录;缺失的具体受管值仍会报告漂移。环境保留失败会显示 PATH 和 Telegram spool 超时的有界当前/安装程序值,其他值会被隐去。
- 当配置最后由较新版本写入时,Doctor 服务修复会拒绝从较旧的 OpenClaw 二进制文件重写、停止或重启 gateway 服务。参见 [Gateway 故障排除](../troubleshooting.md#split-brain-installs-and-newer-config-guard)。
- `openclaw gateway install --force` 会重写受管基础单元,但永远不会移除操作员拥有的 systemd drop-in;如果命令或工作目录覆盖仍然有效,它会发出警告。
16. Gateway 运行时 + 端口诊断

Doctor 会检查服务运行时(PID、上次退出状态),并在服务已安装但实际未运行时发出警告。它还会检查 Gateway 端口(默认 18789)上的端口冲突,并报告可能原因(Gateway 已在运行、SSH 隧道)。

17. Gateway 运行时最佳实践

Doctor 接受提供 WAL-reset-safe node:sqlite 的 Bun 1.4+ 运行时,并在 Gateway 服务运行在较旧或不安全的 Bun 或版本管理的 Node 路径(nvm、fnm、volta、asdf 等)时发出警告。受支持的 Bun 服务,无论已记录还是已固定,都会保留。已固定的运行时永远不会迁移。只有未固定的、不受支持的 Bun 才会提供迁移到受支持系统 Node 的选项,并需要交互式确认。由更新触发的 Doctor 运行永远不会迁移运行时。如果没有可用的受支持 Node,服务将保留在 Bun 上,Doctor 会发出警告。版本管理器路径在升级后可能失效,因为服务不会加载你的 shell 初始化。Doctor 可以提供将未固定的版本管理 Node 迁移到受支持的系统 Node 安装(Homebrew/apt/choco)。

重新安装一个已存在但未加载的服务,且没有 wrapper 或运行时固定时,Doctor 会将其运行时选择器默认设置为受支持的已记录 Node 或 Bun。 保留该运行时会保留其可执行文件,而不会创建固定;选择 另一个运行时会选择新的可执行文件。如果已记录的运行时不可用或不受支持,则回退到全新安装的默认 Node,或者在未找到受支持 Node 且未设置显式运行时、固定或 wrapper 时,回退到正在运行的受支持 Bun,而不会创建固定。

Doctor 对非交互式运行时回退使用相同的建议。 显式选择 Node 时,如果没有可用的受支持 Node,仍会在安装前失败;它不会静默替换为 Bun。当 Doctor 需要确认才能安装服务时,这一点不会改变。

服务修复期间会保留显式运行时路径固定。 Doctor 仍会检查其运行时能力,但不会将有效固定从版本管理器迁移走。使用 openclaw gateway install --runtime-path <path> --force 或 openclaw gateway install --runtime node --force 替换或移除无效固定。

服务安装和修复会识别当前名为 node、nodejs 或带版本名称(如 node24 和 node-24)的 Node 可执行文件,包括 Windows .exe 变体。每个候选项在选择前仍必须通过 Node 和 SQLite 能力检查。

新安装或修复的 macOS LaunchAgents 使用规范系统 PATH(/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin),而不是复制交互式 shell PATH,因此 Homebrew 管理的系统二进制文件保持可用,同时 Volta、asdf、fnm、pnpm 和其他版本管理器目录不会改变 Node 子进程解析到的可执行文件。Linux 服务仍保留显式环境根目录(NVM_DIR、FNM_DIR、VOLTA_HOME、ASDF_DATA_DIR、BUN_INSTALL、PNPM_HOME)和稳定的用户 bin 目录,但猜测的版本管理器回退目录仅在这些目录存在于磁盘上时写入服务 PATH。

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