OpenClaw超简单12：配置文件深度解析

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

一、配置文件基础

位置

~/.openclaw/openclaw.json

格式

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

可以写注释（// 和 /* */）
支持尾随逗号
字段名可以不加引号

{
  // 这是一个注释
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",  // 尾随逗号没问题
      }
    }
  }
}

可以不存在

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

二、四种修改方式

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

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

CLI 快速操作

# 读取某个值
openclaw config get agents.defaults.model.primary

# 修改某个值
openclaw config set agents.defaults.model.primary "openai/gpt-4o"

# 删除某个值（恢复默认）
openclaw config unset agents.defaults.model.primary

三、配置文件结构速览

{
  // 模型配置
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["groq/llama-3.3-70b-versatile"]
      }
    }
  },

  // Channel 配置
  channels: {
    telegram: { enabled: true, botToken: "..." },
    feishu: { enabled: true, accounts: { main: { appId: "...", appSecret: "..." } } }
  },

  // 会话配置
  session: {
    dmScope: "per-channel-peer",
    resetPolicy: { dailyResetHour: 4, idleTimeout: "2h" }
  },

  // 工具权限
  tools: {
    allow: ["group:fs", "group:web"],
    deny: ["group:runtime"]
  },

  // Skills
  skills: {
    entries: {
      "web-search": { enabled: true, env: { BRAVE_API_KEY: "..." } }
    }
  },

  // 定时任务全局设置
  cron: {
    enabled: true,
    maxConcurrentRuns: 1
  },

  // Gateway 服务设置
  gateway: {
    bind: "127.0.0.1:18789"
  }
}

四、热重载说明

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

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

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

{
  gateway: {
    hotReload: "hybrid"  // hybrid | hot | restart | off
  }
}

五、配置校验与排错

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

openclaw doctor

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

openclaw doctor --fix

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

六、环境变量优先级

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

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

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