跳转至

配置验证与检查

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 或覆盖检查。
  • 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 并重试一次。非交互式启动会改为打印修复命令。

  1. 运行 openclaw doctor --fix,让 doctor 修复带前缀/被覆盖的配置,或恢复最后已知良好配置。
  2. 仅从 .clobbered.* 或 .rejected.* 复制预期键,然后使用 openclaw config set 或 config.patch 应用它们。
  3. 重启前运行 openclaw config validate。
  4. 如果手动编辑,请保留完整的 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、缺失作用域或未解析的认证引用。

警告含义:

  • ssh_tunnel_failed → SSH 设置失败,但命令仍尝试了直接配置的目标或回环目标。
  • multiple reachable gateway identities detected → 不同的 Gateway 作出了响应,或 OpenClaw 无法证明可达目标是同一个 Gateway。指向同一 Gateway 的 SSH 隧道、代理 URL 或配置的远程 URL 被视为具有多个传输的同一个 Gateway,即使传输端口不同。
  • probe_scope_limited → 连接成功,但详细 RPC 受作用域限制;请配对设备身份,或使用具有 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 警告文本 → 对于失败目标,此命令路径中认证材料不可用。

相关:

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