配置验证与检查
Gateway 拒绝了无效配置¶
当 Gateway 启动因 Invalid config 失败,或热重载日志显示其跳过了无效编辑时使用。
启动时会自动迁移符合条件的单文件配置中确定性的遗留键,并且只有当整个结果(包括插件)通过验证时才会继续。它会将之前的配置保留在 .bak 环中。使用 $include 的配置、由 Nix 管理的配置、由更新版本写入的配置,以及仍然无法通过验证的配置需要操作员修复。参见 遗留配置键迁移。
查找:
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.*文件,以便最新的已修复负载仍然可用。
检查和修复
常见特征
- 存在
.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 并重试一次。非交互式启动会改为打印修复命令。
- 运行
openclaw doctor --fix,让 doctor 修复带前缀/被覆盖的配置,或恢复最后已知良好配置。 - 仅从
.clobbered.*或.rejected.*复制预期键,然后使用openclaw config set或config.patch应用它们。 - 重启前运行
openclaw config validate。 - 如果手动编辑,请保留完整的 JSON5 配置,而不仅仅是想要更改的部分对象。
相关:
Gateway 检查警告¶
当 openclaw gateway probe 能够到达某个目标,但仍打印警告块时使用。
查找:
- 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