用了一段时间 OpenClaw 之后，你可能会想更精细地调整它的行为——换个模型、改改会话策略、加新 Channel……这些都通过同一个文件来管理：~/.openclaw/openclaw.json。这篇把这个配置文件讲清楚。

一、配置文件基础

位置

text
1~/.openclaw/openclaw.json

格式

OpenClaw 使用 JSON5 格式，比标准 JSON 宽松：

  • 可以写注释（// 和 /* */）
  • 支持尾随逗号
  • 字段名可以不加引号
json5
 1{
 2  // 这是一个注释
 3  agents: {
 4    defaults: {
 5      model: {
 6        primary: "anthropic/claude-sonnet-4-6",  // 尾随逗号没问题
 7      }
 8    }
 9  }
10}

可以不存在

配置文件是可选的。如果没有这个文件，OpenClaw 会用内置的安全默认值启动。只有当你需要修改默认行为时，才需要编辑它。

二、四种修改方式

方式命令 / 操作适合场景
CLI 命令openclaw config set <key> <value>快速改单个值
Control UIopenclaw dashboard → 配置页面可视化编辑
引导向导openclaw onboard 或 openclaw configure初次设置
直接编辑文件用任意编辑器打开批量修改

直接编辑文件时，保存后 Gateway 会自动热重载，大多数改动无需重启。

CLI 快速操作

bash
1# 读取某个值
2openclaw config get agents.defaults.model.primary
3
4# 修改某个值
5openclaw config set agents.defaults.model.primary "openai/gpt-4o"
6
7# 删除某个值（恢复默认）
8openclaw config unset agents.defaults.model.primary

三、配置文件结构速览

json5
 1{
 2  // 模型配置
 3  agents: {
 4    defaults: {
 5      model: {
 6        primary: "anthropic/claude-sonnet-4-6",
 7        fallbacks: ["groq/llama-3.3-70b-versatile"]
 8      }
 9    }
10  },
11
12  // Channel 配置
13  channels: {
14    telegram: { enabled: true, botToken: "..." },
15    feishu: { enabled: true, accounts: { main: { appId: "...", appSecret: "..." } } }
16  },
17
18  // 会话配置
19  session: {
20    dmScope: "per-channel-peer",
21    resetPolicy: { dailyResetHour: 4, idleTimeout: "2h" }
22  },
23
24  // 工具权限
25  tools: {
26    allow: ["group:fs", "group:web"],
27    deny: ["group:runtime"]
28  },
29
30  // Skills
31  skills: {
32    entries: {
33      "web-search": { enabled: true, env: { BRAVE_API_KEY: "..." } }
34    }
35  },
36
37  // 定时任务全局设置
38  cron: {
39    enabled: true,
40    maxConcurrentRuns: 1
41  },
42
43  // Gateway 服务设置
44  gateway: {
45    bind: "127.0.0.1:18789"
46  }
47}

四、热重载说明

OpenClaw 默认使用 hybrid 热重载模式，大多数改动会立即生效，不需要重启：

改动类型是否需要重启
模型切换不需要
Channel 配置不需要
工具权限不需要
会话策略不需要
Skills不需要
Gateway 端口需要重启
插件需要重启

热重载模式可以手动调整（一般不需要）：

json5
1{
2  gateway: {
3    hotReload: "hybrid"  // hybrid | hot | restart | off
4  }
5}

五、配置校验与排错

OpenClaw 对配置文件有严格的 schema 校验，未知字段或格式错误会导致启动失败。遇到问题先运行：

bash
1openclaw doctor

它会检查常见配置问题并给出修复建议。能自动修的可以加 --fix：

bash
1openclaw doctor --fix

如果配置文件损坏无法启动，可以暂时将文件重命名备份，让 OpenClaw 用默认值启动，再逐步恢复配置。

六、环境变量优先级

OpenClaw 支持通过环境变量覆盖配置文件里的值，格式是 OPENCLAW_ 前缀加大写字段路径：

bash
1# 临时切换模型（不修改配置文件）
2OPENCLAW_AGENTS_DEFAULTS_MODEL_PRIMARY="openai/gpt-4o" openclaw gateway

优先级：环境变量 > 配置文件 > 内置默认值。

下一篇：工具权限控制——精细管理 Bot 能做什么、不能做什么。