OpenClaw 中文文档
本页内容

本页内容

查看 Markdown以纯文本查看本页在 ChatGPT 中打开针对本页提问在 Claude 中打开针对本页提问

网关

配置验证和检查

Gateway 拒绝了无效配置

当 Gateway 启动失败并提示 Invalid config，或者热重载日志显示它跳过了一次无效编辑时使用。

启动会自动迁移旧密钥以及符合条件的单文件配置中的已知替换项，并且仅在整个结果（包括插件）验证后才继续。它保留 .bak 环中的先前配置。使用 $include 的配置、Nix 管理的配置、由较新版本编写的配置以及仍然无法验证的配置需要操作员修复。请参阅 旧版配置密钥迁移。

bash
openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

查看以下内容：

  • Invalid config at ...
  • config reload skipped (invalid config): ...
  • Config write rejected: ...
  • 活动配置旁边带有时间戳的 openclaw.json.rejected.* 文件。
  • 如果 doctor --fix 修复了损坏的直接编辑，则 A 带时间戳的 openclaw.json.clobbered.* 文件。
  • 对于每个配置路径，OpenClaw 会保留最新的 32 个 .clobbered.* 文件，并轮转更旧的文件。
发生了什么
  • 该配置在启动、热重载或 OpenClaw- 写入期间未验证。
  • Gateway 启动使旧密钥保持不变，并拒绝需要修复的配置，并带有 openclaw doctor --fix 提示。
  • 热重载会跳过无效的外部编辑，并保持当前运行时配置生效。
  • OpenClaw- 拥有的写入在提交之前拒绝 invalid/destructive 有效负载并保存 .rejected.*。
  • openclaw doctor --fix 拥有旧密钥修复。它还可以删除非 JSON 前缀或恢复最后一次已知的良好副本，同时将被拒绝的有效负载保留为 .clobbered.*。
  • 当同一个配置路径发生多次修复时，OpenClaw 会轮转较旧的 .clobbered.* 文件，以便最新修复后的负载仍然可用。
  • 如果 OpenClaw 无法保存 .clobbered.* 副本，则会延迟恢复并发出警告，并且活动文件保持不变。解决快照锁定或存储问题后重试恢复。
检查和修理
bash
CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor
通用签名
  • .clobbered.* 存在 → doctor 在修复活动配置时保留了一个损坏的外部编辑。
  • .rejected.* 存在 → OpenClaw- 拥有的配置写入失败的架构或提交前的破坏检查。
  • 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让医生修复prefixed/clobbered配置或恢复最后一次已知的良好状态。
  2. 只从 .clobbered.* 或 .rejected.* 中复制你想保留的键，然后使用 openclaw config set 或 config.patch 应用它们。
  3. 重启前先运行 openclaw config validate。
  4. 如果你手动编辑，请保留完整的 JSON5 配置，而不是只保留你想修改的部分对象。

相关：

网关检查警告

当 openclaw gateway probe 已经探测到某些内容，但仍然打印警告块时使用。

bash
openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

查看以下内容：

  • JSON 输出中的 warnings[].code 和 primaryTargetId。
  • 警告是否与 SSH 回退、多网关、缺失的 scope，或未解析的身份验证引用有关。

警告含义：

  • ssh_tunnel_failed → SSH 设置失败，但该命令仍尝试直接 configured/loopback 目标。
  • multiple reachable gateway identities detected → 不同的网关有响应，或者 OpenClaw 无法证明可达目标是同一个网关。SSH 隧道、代理 URL，或配置为指向同一个网关的远程 URL，会被视为一个具有多种传输方式的网关，即使传输端口不同也是如此。
  • probe_scope_limited → 连接有效，但详细信息 RPC 范围有限；将设备身份与 operator.read 配对或使用凭据。
  • Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → 连接有效，但完整诊断 RPC 设置超时或失败。将此视为具有降级诊断功能的可访问网关；比较 --json 输出中的 connect.ok 和 connect.rpcOk。
  • Capability: pairing-pending 或 gateway closed (1008): pairing required → 网关应答，但该客户端仍需要 pairing/approval 才能正常操作员接入。
  • 未解析的 gateway.auth.* / gateway.remote.* SecretRef 警告文本 → 在此次命令路径中，失败目标的身份验证材料不可用。

相关：

本页有帮助吗？