配置验证和探针

Gateway 拒绝无效配置¶

当 Gateway 启动失败并报错 Invalid config，或热重载日志显示它跳过了无效编辑时，使用本节。

启动过程会自动迁移符合条件的单文件配置中的确定性遗留键，并且仅当整个结果（包括插件）通过校验后才继续。它会在 .bak 环中保留先前的配置。使用 $include 的配置、由 Nix 管理的配置、由较新版本写入的配置，以及仍未能通过校验的配置，都需要操作员进行修复。参见遗留配置键迁移。

openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor

查找以下内容：

Invalid config at ...
config reload skipped (invalid config): ...
Config write rejected: ...
在活动配置旁边有一个带时间戳的 openclaw.json.rejected.* 文件。
如果 doctor --fix 修复了损坏的直接编辑，则会出现带时间戳的 openclaw.json.clobbered.* 文件。
OpenClaw 会为每个配置路径保留最新的 32 个 .clobbered.* 文件，并轮换较旧的文件。

发生了什么

配置在启动、热重载或 OpenClaw 自身的写入过程中未能通过校验。
Gateway 启动时保持遗留键不变，并拒绝需要修复这些键的配置，同时给出 openclaw doctor --fix 提示。
热重载会跳过无效的外部编辑，并保持当前运行时配置继续生效。
OpenClaw 自身的写入会在提交前拒绝无效/破坏性负载，并保存 .rejected.* 文件。
openclaw doctor --fix 负责修复遗留键。它还可以移除非 JSON 前缀，或恢复最后已知的良好副本，同时将拒绝的负载保留为 .clobbered.* 文件。
当同一配置路径发生多次修复时，OpenClaw 会轮换较旧的 .clobbered.* 文件，使最新修复的负载仍然可用。

检查并修复

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

常见特征

.clobbered.* 存在 → doctor 在修复活动配置时保留了损坏的外部编辑。
.rejected.* 存在 → OpenClaw 自身的配置写入在提交前未通过 schema 或 clobber 检查。
Config write rejected: → 写入尝试丢弃必需的结构、使文件急剧缩小，或持久化无效配置。
config reload skipped (invalid config): → 直接编辑未通过校验，并被运行中的 Gateway 忽略。
Invalid config at ... → 在 Gateway 服务启动之前启动即失败。
missing-meta-vs-last-good、gateway-mode-missing-vs-last-good 或 size-drop-vs-last-good:* → OpenClaw 自身的写入被拒绝，因为与最后已知的良好备份相比，它丢失了字段或体积。
Config last-known-good promotion skipped → 候选配置包含被屏蔽的机密占位符，例如 ***。

修复选项

在自动遗留键迁移不够充分时，交互式启动可以提供运行 openclaw doctor --fix 并重试一次的选项。非交互式启动则会打印修复命令。

运行 openclaw doctor --fix，让 doctor 修复带前缀/被覆盖的配置，或恢复最后已知的良好配置。
仅从 .clobbered.* 或 .rejected.* 复制需要的键，然后用 openclaw config set 或 config.patch 应用它们。
重启前运行 openclaw config validate。
如果手动编辑，请保留完整的 JSON5 配置，而不只是你想要更改的部分对象。

Gateway 探测警告¶

当 openclaw gateway probe 能到达目标，但仍打印警告块时，使用本节。

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

查找以下内容：

检查 JSON 输出中的 warnings[].code 和 primaryTargetId。
判断警告是否与 SSH 回退、多个 Gateway、缺少 scope，或未解析的 auth ref 有关。

常见特征：

SSH tunnel failed to start; falling back to direct probes. → SSH 设置失败，但命令仍然尝试了已配置/回环目标。
multiple reachable gateway identities detected → 不同的 Gateway 做出了响应，或者 OpenClaw 无法证明可达目标是同一个 Gateway。指向同一 Gateway 的 SSH 隧道、代理 URL 或已配置的远程 URL 会被视为具有多种传输方式的同一个 Gateway，即使传输端口不同。
Read-probe diagnostics are limited by gateway scopes (missing operator.read) → 连接成功，但详细 RPC 受到 scope 限制；请配对设备身份，或使用具有 operator.read 的凭据。
Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → 连接成功，但完整的诊断 RPC 集合超时或失败。可将其视为可到达但诊断能力下降的 Gateway；比较 --json 输出中的 connect.ok 和 connect.rpcOk。
Capability: pairing-pending 或 gateway closed (1008): pairing required → Gateway 已响应，但该客户端在正常操作员访问前仍需要配对/审批。
未解析的 gateway.auth.* / gateway.remote.* SecretRef 警告文本 → 在此命令路径中，失败目标所需的认证材料不可用。