夜雨聆风一个文件管所有
OpenClaw 的配置极简到令人意外。整个系统——Gateway 端口、接入的消息平台、AI 模型的 API Key、Agent 的行为规则、工具权限策略、记忆系统的后端——全部集中在一个文件里：
~/.openclaw/openclaw.json一个文件，管所有。
这个设计是刻意为之的。分散在多个配置文件里的系统，备份麻烦、迁移麻烦、版本管理麻烦，更重要的是——出了问题你不知道去哪里找。一个文件，一个备份，一条 git commit，换台机器直接复制过去，全部搞定。
但"一个文件"不代表简单。这个文件背后有一套精心设计的加载、校验、拆分、热更新机制，值得仔细拆开来看。
为什么选 JSON5
标准 JSON 的最大痛点是不能写注释。一个真实的 OpenClaw 配置文件里，你需要记录"这个 API Key 是哪个账号申请的"、"这个端口为什么改成了非默认值"、"这个通道暂时禁用是因为什么"。如果不能在配置里写注释，这些信息要么丢失，要么另开一个说明文档，与配置文件逐渐失去同步。
OpenClaw 选择 JSON5 格式，解决了这个问题。JSON5 是 JSON 的超集，完全向后兼容标准 JSON，但额外支持几件事：单行和多行注释（// 和 /* */）、末尾逗号（数组和对象最后一项后面可以有逗号）、无引号的简单键名。
实际配置文件看起来像这样：
{// Gateway 端口，改动需要重启gateway: {port: 18789,bind: "loopback", // 只监听本地，不对外暴露},// 默认 Agent 配置agents: {defaults: {workspace: "~/.openclaw/workspace",model: "claude-sonnet-4",},},}
注释和末尾逗号让配置文件从"机器格式"变成了"人类可维护的文档"。这个区别在几个月后你翻出来修改时会非常明显。
JSON5 的解析由 src/config/io.ts 里的 parseConfigJson5() 函数负责，这是整个配置加载流水线的第一步。
Zod：校验的牙齿
JSON5 解析完拿到一个原始对象之后，下一步是校验。OpenClaw 用 Zod 库做这件事，Schema 定义在 src/config/zod-schema.ts 里，主入口是 OpenClawSchema。
这里有一个设计决策非常强硬，值得单独拿出来说：Zod Schema 对每一个对象都使用 .strict() 模式。
.strict() 的含义是：对象里不能有任何 Schema 里没有定义的键。一旦出现未知键，校验立刻失败，Gateway 拒绝启动，并在错误信息里精确指出哪个键是问题所在。
没有警告模式，没有"忽略未知键"的宽容选项。要么完全合法，要么不启动。
这个看起来严苛的选择，背后有充分的理由。配置文件的常见错误有两类：一类是写错了键名（比如把 workspace 写成了 workSpace），另一类是把已经被废弃的旧键名还留在配置里。如果 Schema 对未知键保持沉默，你永远不知道你的配置修改有没有真正生效——也许你一直在修改一个系统压根不认识的键，而 Agent 的行为毫无变化。
.strict() 让这类错误立刻暴露，而不是变成几周后才发现的隐形 bug。
官方运维指南因此给出了一条铁律：手动编辑配置文件之前，先做备份。
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak如果因为未知键导致 Gateway 无法启动，恢复备份或者运行 openclaw doctor --fix，后者会自动扫描并移除无效键。
配置加载的完整流水线
从磁盘到内存，一份 OpenClaw 配置经历了一条五步流水线，定义在 src/config/io.ts 和 src/config/validation.ts 里。
第一步，JSON5 解析。parseConfigJson5() 读取文件，处理注释和末尾逗号，转换为标准 JS 对象。
第二步，遗留配置迁移。migrateLegacyConfig() 检查有没有旧版本的配置键，如果有，自动映射到新的键名。这是一个幂等操作——运行多次结果相同。每次大版本升级后，旧配置不需要手动修改，迁移系统会自动处理。
第三步，环境变量展开。配置文件里任何字符串值都可以使用 ${VAR_NAME} 语法引用环境变量，这一步把所有占位符替换成实际的值。环境变量来源有三处，按优先级排列：当前进程的环境变量、当前目录的 .env 文件、~/.openclaw/.env 全局回退文件，后者不会覆盖前者。
第四步，Zod 校验。OpenClawSchema.safeParse() 对整个对象做结构验证，包括类型检查、必填字段检查、以及 superRefine() 里定义的跨字段约束（比如：如果你在 bindings 里引用了某个 Agent ID，这个 ID 必须在 agents.list 里存在）。
第五步，插件 Schema 合并。buildConfigSchema() 把已安装插件贡献的额外 Schema 片段并入主 Schema，校验插件配置是否合法。
校验结果被封装成一个 ConfigSnapshot 对象，包含 valid（是否合法）、config（解析后的配置对象）、issues（错误列表）、metadata（配置文件的修改时间、内容哈希等）字段，缓存在 ConfigIO 单例里。
$include：拆分大型配置
配置文件默认只有一个，但实际使用中，一个配置了十几个通道、几十个模型账号的文件会变得相当臃肿。OpenClaw 提供了 $include 指令来拆分文件：
{gateway: { port: 18789 },agents: { $include: "./agents.json5" },broadcast: {$include: ["./clients/work.json5", "./clients/personal.json5"]},}
单个文件引用时，$include 所在的键会被该文件的内容完整替换。数组引用时，多个文件按顺序深度合并，后面的文件覆盖前面的同名字段。$include 可以嵌套，最深支持 10 层，循环引用会被检测并报错。相对路径相对于当前文件所在目录解析。
这个机制让"一个文件管所有"变成了"一个主文件组织所有"——逻辑上仍然是单一配置来源，物理上可以按关注点拆成多个文件分开维护。
SecretRef：密钥不应该出现在配置文件里
现在来讲 OpenClaw 配置系统里最重要的安全设计：SecretRef。
AI 助手的配置天然涉及大量敏感凭证——Anthropic API Key、OpenAI API Key、Telegram Bot Token、WhatsApp 账号凭证、Google Calendar OAuth Token。这些东西如果明文写在 ~/.openclaw/openclaw.json 里，有一个隐患：任何时候你把这个文件备份到云盘、分享给朋友调试、提交到 git 仓库，凭证就泄漏了。
SecretRef 是 OpenClaw 的解法。它允许配置文件里的任何敏感字段不写入实际值，而是写一个"引用声明"，告诉系统去哪里找这个值。
{models: {auth: {anthropic: {apiKey: { env: "ANTHROPIC_API_KEY" } // 从环境变量读取},openai: {apiKey: { file: "~/.secrets/openai-key" } // 从文件读取},custom: {apiKey: { exec: "pass show openai/api-key" } // 执行命令获取}}}}
三种引用方式对应三种场景：env 适合通过 CI/CD 或 dotenv 注入密钥的场景；file 适合把密钥放在权限严格的独立文件里（配合 chmod 600）；exec 适合使用 pass、1Password CLI、Vault 等密码管理器的场景。
SecretRef 字段在 Schema 里通过 .register(sensitive) 标记，这个标记有两个作用：一是在 openclaw config get 命令输出时自动遮蔽值（显示为 [SECRET]）；二是在 Web UI 的配置编辑页面对这些字段做特殊处理，防止密钥被意外回显到屏幕上。
这个机制让 ~/.openclaw/openclaw.json 本身可以安全地进行版本管理——文件里存的只是引用路径，而不是实际凭证。
热更新：大多数改动不需要重启
OpenClaw 的 Gateway 是一个常驻进程。如果每次改一个配置项都要重启整个 Gateway，所有通道连接会断开，正在进行的对话会中断，用户体验很差。
热更新机制解决了这个问题。Gateway 在启动时用 Node.js 的 fs.watch() 监听 openclaw.json 文件变化，检测到变化后先用 resolveConfigSnapshotHash() 计算内容哈希，确认是真实内容变化而不只是文件元数据更新，然后走一遍完整的加载流水线，把新配置热应用到运行中的系统。为了避免你快速编辑时触发多次重载，变化检测有一个防抖延迟，默认 300 毫秒，可以通过 gateway.reload.debounceMs 调整。
绝大多数配置字段都支持热更新，包括所有通道配置、Agent 配置、模型配置、工具策略、Skill 配置、Cron 任务等。
但有少数字段改动后必须重启，不触发热更新：Gateway 的端口和绑定地址（gateway.port、gateway.bind）、认证配置（gateway.auth）、插件列表（plugins）、以及设备发现配置（discovery）。这些字段涉及底层网络绑定或进程级初始化，无法在不重启的情况下安全变更。
还有两个例外稍显反直觉：gateway.reload 和 gateway.remote 这两个字段虽然在 gateway 下，但改动它们不会触发重启。这是为了避免在你调整重载行为本身时意外地重启 Gateway。
多级优先级：defaults 与 per-agent 覆盖
配置系统的最后一个重要机制是多级覆盖。OpenClaw 支持在一套配置里运行多个 Agent，每个 Agent 可以有自己的个性化配置，同时共享全局默认值。
agents.defaults 是基准层，为所有 Agent 设置默认值——默认模型、默认工作目录、默认工具策略、默认上下文压缩阈值。agents.list[] 里的每一个条目是覆盖层，用 id 字段标识 Agent，只需要写出与默认值不同的字段，其余自动继承 defaults。
{agents: {defaults: {model: "claude-haiku-4", // 默认用便宜快速的模型workspace: "~/.openclaw/workspace",},list: [{id: "coder",model: "claude-sonnet-4", // 编码 Agent 升级到更强的模型tools: { profile: "coding" },},{id: "researcher",model: "gemini-2-pro", // 研究 Agent 用 Gemini}]}}
解析时，src/agents/agent-scope.ts 里的 resolveAgentConfig() 负责把 defaults 和对应的 list 条目深度合并，输出一个完整的 Agent 配置对象。
需要注意的是，有几类配置只能在 agents.defaults 层设置，不能在 agents.list[] 里覆盖——比如上下文压缩配置、浏览器 Profile 默认值、thinking 档位。在单个 Agent 配置里设置这些字段会被 Gateway 静默忽略。openclaw doctor --fix 会检测并提示这类无效的 per-agent 覆盖。
小结
OpenClaw 的配置系统表面上是"一个 JSON5 文件"，实际上是五步加载流水线（解析→迁移→环境变量展开→Zod 校验→插件合并）、$include 文件拆分、SecretRef 密钥引用、fs.watch() 热更新、以及多级 defaults/per-agent 覆盖的综合体。
它的核心设计理念是：对人类友好，对错误零容忍。JSON5 让配置可读可维护，Zod 的 .strict() 让错误无处遁形，SecretRef 让密钥不必出现在配置文件里，热更新让日常调整不打断正在运行的服务。
下一篇，我们深入 Gateway 内部，看它作为整个系统的 WebSocket 控制平面，具体是怎么运作的。
源码参考：src/config/io.ts · src/config/zod-schema.ts · src/config/validation.ts · src/config/legacy-migrate.ts · src/agents/agent-scope.ts基于 commit bf6ec64f 版本
