OpenClaw 配置与模型：两桶规则与 provider/model 引用

配置文件在哪，允许怎么写

主配置是：

~/.openclaw/openclaw.json

它是 JSON5——可以写注释和尾逗号。文件不存在时用安全默认值。有个细节值得先知道：配置文件必须是一个常规文件。OpenClaw 写配置时是"原子替换"（rename 到该路径），所以如果你把 openclaw.json 做成符号链接，被替换的会是链接的目标，而不是你预期的那份。想放到别处，就用 OPENCLAW_CONFIG_PATH 直指真实文件。

最小可用配置长这样：

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

两桶规则：根级管基础设施，agents.defaults 管行为

这是理解 OpenClaw 配置的钥匙：

• 根级键（channels、gateway、models、plugins…）= 基础设施与跨 agent 的默认值；
• agents.defaults = agent-loop 的行为（workspace、model、sandbox、compaction…）；
• agents.entries.<id> = 某个 agent 的覆盖。

为什么要分？因为一个安装里可以跑多个 agent，根级是"整台机器"的设定，agents.defaults 才是"助手怎么思考、怎么执行"。混着写会出现"我明明在根级设了 X，某个 agent 却不生效"这类困惑。

强校验：写错就拒绝启动

这条要有心理准备：OpenClaw 只接受完全符合 schema 的配置。未知键、类型错误、非法值，都会让 Gateway 拒绝启动。唯一允许的根级例外是 $schema（方便编辑器挂 JSON Schema）。

拒绝启动时，只有诊断类命令还能用：openclaw doctor、logs、health、status。修复走：

openclaw doctor          # 看具体问题
openclaw doctor --fix    # 应用修复（--repair 同义，--yes 跳过询问）

几个安全网要知道：

• 启动时会先做安全的历史键迁移，写入成功才落盘，旧配置留在 .bak 环里。
• 启动/热重载不会自动回滚到上一次的 last-known-good，只有 doctor --fix 会。
• 看起来像"误覆盖"的写入会被拦下——比如丢掉生效的 gateway.mode，或把文件缩小一半以上。被拒的载荷会尽量另存为 <path>.rejected.<时间戳> 供查看。

也就是说：配置是强类型的，不要凭记忆手写太多。用 config 命令或 Control UI。

改配置的四种方式

# 交互向导
openclaw onboard        # 完整引导
openclaw configure      # 配置向导

# 命令行单行修改
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey

Control UI 的 Config 页会用实时 schema 渲染表单（含字段说明、插件与通道的 schema），并提供 Raw JSON 作为逃生口。想直接编辑文件也行——Gateway 会监视文件并热重载（gateway.reload.mode: off|hybrid，默认 hybrid）。

config set 有几个容易踩的点：

• 对 models.providers、agents.defaults.models 这类受保护的 map，默认拒绝整体替换，需要 --merge 或 --replace。
• --dry-run 可以先看会发生什么。
• 密钥支持 SecretRef：--ref-provider/--ref-source/--ref-id。

模型引用：按第一个 / 切

配置里的模型引用（agents.defaults.model 等）解析规则是：在第一个 / 处分割。

• 常规写法：provider/model。
• 模型 ID 自带 /（OpenRouter 风格）时必须带 provider 前缀，例如 openrouter/moonshotai/kimi-k2。
• 省略 provider 时，OpenClaw 先试别名，再在该模型 id 的唯一已配置 provider 里匹配，最后才回落到配置的默认 provider。
• 如果默认 provider 不再提供配置里的默认模型，会回落到第一个已配置的 provider/model，而不是暴露一个已删除的陈旧默认。

默认模型与回退：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        fast: "openai/gpt-5.2#low",
      },
    },
  },
}

• agents.defaults.model.primary + fallbacks 决定正常路径与回退；
• agents.defaults.models 存别名，方便在命令/agent 里引用；
• modelPolicy.allow 是白名单（支持 provider/*），非空即硬限制，越界会报 Model override ... is not allowed；
• utilityModel / imageModel 给辅助任务指定更便宜的模型。

一个真实差别：用户在聊天里用 /model 选模型是严格的——模型不可达会显式失败，而不是悄悄回退。自动回退只发生在配置的 fallbacks 链上。

常用命令：

openclaw models list
openclaw models set anthropic/claude-sonnet-4-5
openclaw models status
openclaw models fallbacks

把密钥挡在配置之外

配置里不该出现明文密钥。两种做法：

1. 环境变量替换：在值里写 ${VAR}，运行时替换；
2. SecretRef：指向 env / file / exec / store，配置文件里只留引用。

原则很简单：openclaw.json 可以进你的私有备份，但不要进 git。它包含 provider 凭据、通道 token 等。真要用版本管理，就用环境变量或 SecretRef 把秘密抽出去，只提交不含秘密的骨架。

小结

• 配置是 JSON5 的 ~/.openclaw/openclaw.json，必须常规文件，别用符号链接。
• 两桶规则：根级 = 基础设施/跨 agent 默认；agents.defaults = agent 行为。
• 强校验：写错就拒绝启动，用 config 命令或 Control UI，别硬写；doctor --fix 才回滚。
• 模型引用按第一个 / 切；模型 id 自带 / 时必须带 provider。/model 选择是严格的，自动回退只走配置的 fallbacks。
• 用 ${VAR} 或 SecretRef 把密钥挡在配置外。

下一篇讲通道与配对：怎么最快把一个聊天软件接上，DM 配对和节点配对有什么本质区别，以及消息是怎么被路由到某个 agent 和会话的。