配置 Gateway

这一章继续看 Gateway 自身怎么配置。前面“理解配置结构”解决的是新手认知；这一篇解决运行时问题：Gateway 为什么拒绝猜你的模式、哪些配置能热加载、程序化改配置为什么要 patch、启动失败先看什么。

1. Gateway 配置管的是控制面

openclaw.json 既管 Agent，也管 Gateway。Gateway 相关配置尤其敏感，因为它决定：

• WebSocket 监听在哪个地址和端口。
• Control UI、Canvas、A2UI 是否可访问。
• 认证、TLS、Tailscale、trusted proxy 怎么工作。
• reload mode 如何应用配置变化。
• health、diagnostics、logs 怎么暴露状态。
• 远程 CLI 和节点怎么连接。

flowchart TD
    Config["openclaw.json"]
    Mode["gateway.mode"]
    Network["bind / port / auth / TLS"]
    Reload["reload mode"]
    Control["Control UI / Canvas / A2UI"]
    Health["health / diagnostics"]
    Remote["remote target"]

    Config --> Mode
    Config --> Network
    Config --> Reload
    Config --> Control
    Config --> Health
    Config --> Remote

    style Config fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Network fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Reload fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

2. gateway.mode=local 是启动护栏

官方 Gateway CLI 现在有一个关键护栏：默认情况下，Gateway 拒绝在 ~/.openclaw/openclaw.json 里缺少 gateway.mode=local 时启动。openclaw onboard --mode local 和 openclaw setup 应该写入这个字段。

如果配置文件存在但缺少 gateway.mode，Gateway 会把它看成可疑损坏配置，而不是替你猜成 local。

这解决的是一个真实风险：配置被 clobber（被错误覆盖）后，系统不能带着半坏状态继续启动。第一次配置用 openclaw onboard --mode local 或 setup；临时开发启动才考虑 --allow-unconfigured；发现 gateway.mode 缺失时当作损坏配置修复，不要手动猜；远程模式要明确配置 gateway.mode 和 gateway.remote。

3. 修改 Gateway 配置的四个入口

优先级按“新手安全”排序：

常用 CLI：

openclaw config get gateway.mode
openclaw config set gateway.reload.mode hybrid
openclaw config validate

直接编辑适合小范围、可回滚的改动。编辑后立刻跑：

openclaw config validate
openclaw doctor

4. strict schema 怎么用

OpenClaw 用 schema 校验完整配置。配置不合法时，Gateway 不应该继续运行。

你可以把排障命令分成三层：

配置界面、Agent 自动化或脚本不要靠猜字段；应该以 config.schema.lookup 和完整 reference 为准。

5. 热加载和重启边界

Gateway 会监听配置文件。默认 reload mode 是 hybrid：能热加载的直接应用，需要重启的自动重启。

reload mode：

6. Config RPC 不要整份覆盖

程序化更新配置时，优先走“查 schema、拿当前配置和 hash、做 patch”的流程。只有真的要替换完整配置时，才用 full apply。

推荐思路：

config.schema.lookup
  ↓
config.get + hash
  ↓
config.patch
  ↓
validate / health / status

为什么不整份覆盖？因为 Gateway 配置里可能有你没有加载到的 channel、plugin、auth、remote、diagnostics、session 配置。全量覆盖最容易误删其它配置。

官方也对控制面写 RPC 做了速率限制，避免坏脚本高频刷配置。自动化脚本不要循环反复全量覆盖 openclaw.json。

7. health、status、doctor 分别看什么

这些命令经常被混用，实际职责不同：

health 主要判断 Gateway 当前能不能回答和渠道是否健康；doctor 更像修理工，负责配置迁移、状态修复、服务审计和修复建议。

8. 重启不要只会 kill

前台运行：

openclaw gateway

安全重启：

openclaw gateway restart --safe

普通重启：

openclaw gateway restart

强制重启：

openclaw gateway restart --force

--safe 会让运行中的 Gateway 先检查活跃工作、队列、回复投递、embedded runs 和 task runs。如果有阻塞，会报告并等待活跃工作 drain。--force 只在你明确接受立即中断时使用。

9. Gateway 拒绝启动时怎么排

遇到 Gateway 拒绝启动，不要先删配置文件。按这个顺序：

flowchart TD
    Fail["Gateway 启动失败"]
    Validate["openclaw config validate"]
    Doctor["openclaw doctor"]
    Logs["openclaw logs"]
    Mode["检查 gateway.mode"]
    Port["检查端口 / auth / TLS"]
    Fix["只修一个字段"]
    Start["重新启动或 safe restart"]

    Fail --> Validate
    Validate --> Doctor
    Doctor --> Logs
    Logs --> Mode
    Mode --> Port
    Port --> Fix
    Fix --> Start

    style Fail fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Fix fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Start fill:#dcfce7,stroke:#22c55e,stroke-width:2px

先确认是 schema 错误、模式缺失、端口冲突、auth 问题、TLS 问题、插件问题，还是热加载边界。doctor --fix 只适合修复明确可修的常见问题，不能替你决定安全策略。

10. 新手常见坑

• 直接编辑后不验证：Gateway 可能拒绝启动，或者热加载失败。
• 把 unknown key 当注释：strict schema 会拒绝未知字段。
• 用 symlink 管默认配置：OpenClaw 原子写可能替换路径。
• 不区分热加载和重启字段：auth、TLS、端口等变化要确认重启。
• 程序化更新时全量覆盖：容易丢失其它配置。
• 把 token 写死在配置里再提交：应该用 env、SecretRef 或本机凭据管理。
• Gateway 启动失败就删除配置：这会丢掉线索，应该先 doctor 和 validate。
• 用 restart --force 处理所有问题：可能中断正在运行的任务。

11. 本章自检

1. 为什么缺少 gateway.mode=local 时 Gateway 不应该替你猜？
2. health、status、doctor 的职责差异是什么？
3. 程序化改配置为什么优先 patch，而不是 full apply？

12. 接下来去哪

13. 官方资料

• Configuration
• Health checks
• Doctor
• Gateway CLI