配置 Gateway

基于官方 OpenClaw Gateway 配置教程，面向新手讲清 openclaw.json、严格 schema、热加载、重启边界和排障顺序。

OpenClaw 的配置中心是 ~/.openclaw/openclaw.json。它使用 JSON5，可以写注释和 trailing comma，但校验非常严格：未知字段、类型错误、非法值都不会被悄悄忽略。

这对新手是保护。配置错了就拒绝启动，比带着半坏状态继续运行更安全。

先理解：配置文件管什么

openclaw.json 管的是 Gateway 和 Agent 的运行方式。常见配置包括 channels、models、tools、skills、sandbox、session、media、logging、UI、cron、hooks、heartbeat、Gateway 端口、绑定地址、auth、Tailscale 和 TLS。

缺少配置文件时，OpenClaw 会使用安全默认值。但只要你开始接入渠道、远程访问、共享入口或自动化，就应该明确写配置。

不要把默认配置路径做成 symlink 后期待 OpenClaw 永久保留它。官方说明原子写配置时可能替换路径本身。外置配置应使用 OPENCLAW_CONFIG_PATH 指向真实文件。

怎么修改配置

新手优先走 openclaw onboard 或 openclaw configure。它们适合第一次配置和常规调整。

知道字段含义后，可以用 openclaw config get、openclaw config set、openclaw config unset 做单点修改。

需要可视化时，用 Control UI 的 Config tab。它会基于 live config schema 渲染表单，也有 Raw JSON editor 作为兜底。

直接编辑 ~/.openclaw/openclaw.json 适合已经能读懂校验错误的人。编辑前先备份，编辑后跑验证。

严格 schema 怎么用

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

你可以用 openclaw config schema 查看机器可读契约，用 openclaw config validate 检查当前配置，用 openclaw doctor 定位问题，用 openclaw doctor --fix 尝试有限修复。

如果 Control UI 或工具要做配置界面，不要靠手写示例猜字段，应该以 schema 输出和 config.schema.lookup 为准。

热加载和重启边界

Gateway 会监听配置文件，多数业务配置可以热加载，例如 channels、agents、models、routing、hooks、cron、heartbeat、session、messages、tools、browser、skills、UI、logging、identity 和 bindings。

通常需要重启的是 Gateway server 和基础设施层，例如端口、绑定地址、auth、TLS、HTTP 入口、discovery、canvasHost 和 plugins。

默认 reload 模式是 hybrid：能热加载的直接应用，需要重启的自动重启。hot 只热加载并提示 warning，restart 每次变化都重启，off 关闭监听。

新手不要把“保存了配置”理解为“一定已经完全生效”。遇到端口、auth、TLS、插件这类变化，要确认是否发生了重启。

Config RPC 不要整份覆盖

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

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

怎么判断 Gateway 拒绝启动的原因

本地 Gateway 应该由配置明确表达 local mode。官方 CLI 文档说明，如果配置文件存在但 gateway.mode 缺失，Gateway 会把它看成可疑损坏配置，而不是替你猜测为 local。

所以遇到 Gateway 拒绝启动，不要先删配置文件。先跑 doctor、validate、logs，确认是 schema 错误、模式缺失、端口冲突、auth 问题，还是重启边界问题。

doctor --fix 只适合修复明确可修的常见问题，不能替你决定安全策略。

最小配置怎么理解

官方最小示例通常只表达结构：默认 workspace、某个 channel、某种 DM policy 或 token 引用。它不是生产安全完成。

真实接入时还要继续补 allowlist、session 隔离、模型、sandbox、审计、日志脱敏、远程访问保护和凭据来源。

新手不要复制最小配置就上线。最小配置只是让你理解字段位置。

新手常见坑

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

怎么验收

你能说清当前配置文件路径，且它是普通文件而不是危险 symlink。

你能用 validate 确认 schema 通过，用 doctor 确认没有明显风险。

你能区分本次改动是热加载生效，还是需要 Gateway 重启。

你能证明敏感值来自 env、secret ref 或本机凭据，而不是被提交到仓库。

你能在配置出错时根据日志定位具体字段，而不是重装或删除整个目录。