7. 配置文件 openclaw.json 完全解读

本节目标：知道配置文件在哪、长什么样、常改哪些字段，以及如何安全地改、改完怎么让网关认账。读完你敢动手调配置，不再怕改坏。

文件在哪

主配置就一个：

~/.openclaw/openclaw.json

所有智能体共享这份全局配置。每个智能体也能有自己的专属配置，放在 ~/.openclaw/agents/<agentId>/openclaw.json，优先级更高。

Note

配置目录是 ~/.openclaw/。记不住路径，跑 openclaw config file 直接打印出来，比手敲靠谱。

它大概长这样

一个最小可跑的配置：

{
  "models": {
    "default": "anthropic/claude-sonnet-4-5",
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-xxx"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "port": 18789
  }
}

横向看，几个顶层字段各管一摊。

常见字段扫一遍

models —— 模型和密钥。

models.default 设默认模型；models.providers 放各家 API Key 与接入点。想换脑子，主要动这里。

{
  "models": {
    "default": "openai/gpt-5.4",
    "providers": {
      "openai": { "apiKey": "sk-xxx" }
    }
  }
}

Note

上面 anthropic/claude-sonnet-4-5、openai/gpt-5.4 只是示例写法。真实可用的模型随你接入的提供商而定，请以 openclaw models list 或官方 providers 文档为准，别照抄示例 ID。

gateway —— 网关自身。

mode 填 local（本机）；port 是控制台端口，默认 18789；bind 控制监听地址，回环最安全。

channels —— 渠道开关。

每个聊天平台一个子项，如 telegram、discord、feishu。enabled 开或关，令牌之类凭据也写这儿。

agents —— 智能体定义。

agents.entries 列出多个智能体，agents.defaults 放公共默认（模型、心跳、工具权限等）。多智能体路由就靠它。

skills —— 技能开关。

控制哪些技能自动加载、去哪找技能目录。开箱自带一批内置技能，这里决定用不用。

Tip

新手别直接手编大 JSON。先用 openclaw config set 改单项，命令会帮你校验格式，不容易写崩。

用命令改更安全

查看某项：

openclaw config get models.default

修改某项：

openclaw config set agents.defaults.heartbeat.every "2h"

路径用点号（如 a.b.c）。数组或带方括号的路径，在 shell 里加引号防止被展开。

补一个常见动作——改默认模型：

openclaw config set agents.defaults.model.primary "openai/gpt-5.4"

想先试不改，加 --dry-run 做预检：

openclaw config set gateway.reload.mode hybrid --dry-run

Note

直接手编 openclaw.json 也行，但网关把它当”不可信”输入，要先校验才热加载。写错会导致启动失败或被热加载跳过。命令写入则会先校验再落盘，更稳。

改完怎么生效

不是所有改动都要重启。CLI 改完会提示三种之一：

Restart the gateway to apply. —— 必须重启。
Change will apply without restarting. —— 热加载自动生效。
No gateway restart needed. —— 跟运行无关，无需动。

要重启就：

openclaw gateway restart

涉及插件（plugins.entries）的改动一律要重启，因为 CLI 无法证明每个插件都支持热加载。

改完顺手校验：

openclaw config validate

不报错，说明形状没问题。

写坏了能救

命令写入前会校验整份配置。若新内容不合法，原配置不动，被拒的片段存成 openclaw.json.rejected.* 留在旁边，不会覆盖你好的那份。

手动改崩了，跑：

openclaw doctor --fix

它会修被前缀破坏或格式错乱的配置，或恢复上次已知良好的副本。

Tip

动大改之前，先备份：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak。一句命令，后悔药有了。

小结

配置在 ~/.openclaw/openclaw.json。
顶层常改：models、gateway、channels、agents、skills。
用 openclaw config set/get/validate 比手编安全。
改完看提示：热加载或重启网关。
写坏有 doctor --fix 和 .rejected 备份兜底。

七章走完，你已从概念、场景走到安装、启动与配置。后面的章节会深入模型接入、渠道连接与技能使用。

配置文件 openclaw.json 完全解读

7. 配置文件 openclaw.json 完全解读

文件在哪

它大概长这样

常见字段扫一遍

用命令改更安全

改完怎么生效

写坏了能救

推荐工作流

小结