〖OpenClaw系列〗配置文件 openclaw.json 详解

上篇回顾

上一篇（〖OpenClaw系列〗三种方式安装和启动OpenClaw）我们讲了三种安装方式——Docker、二进制、源码编译。装好之后打开浏览器看到控制台界面，这时候你最想问的应该是：下一步干什么？

答案就一句话：配 openclaw.json。

如果你还不清楚 OpenClaw Gateway 是什么、它能做什么，建议先阅读第1篇：AI网关是什么、能做什么，建立基础认知后再回来。

这个文件是 OpenClaw 的神经中枢。模型用哪个、Agent 行为怎么定、接哪些渠道、开哪些工具——全在这里。这篇把每一个你现阶段需要知道的配置项讲清楚。

先上全景：一个文件控制五个维度

编辑配置文件之前，先看清权力有多大。看一眼这张图：

左边的蓝色卡片是你的 openclaw.json，右边五个彩色横条是它控制的五个模块。每条带的左侧竖杠颜色不同，对应不同的配置领域。箭头表示配置读取顺序——Gateway 启动时，从左到右依次把配置加载进去。

下面的文章沿着这五条彩色带展开，每讲一个模块，你都可以回来看图中对应的颜色区域。

配置文件在哪里：openclaw.json 路径详解

OpenClaw 的配置文件只有这一个：

~/.openclaw/openclaw.json

装完 Gateway 之后这个文件不会自动生成。没有配置文件时，OpenClaw 用内置默认值跑——能启动，但什么都干不了（没指定模型、没开通渠道）。

你需要手动创建它。格式不是 JSON，是 JSON5。

JSON5 比 JSON 友好：支持注释、尾逗号、不加引号的 key。换句话说，你可以像写配置一样写它，不用像写代码一样写它。

// 这是合法的 JSON5
{
  // 单行注释
  agents: {
    defaults: {
      model: "anthropic/claude-sonnet-4-6",  // 尾逗号 OK
    },
  },
}

注意：OpenClaw 的配置校验极其严格。字段名写错一个字母，Gateway 直接拒绝启动。配错了怎么排查——末尾「踩坑」部分有解决步骤。

第一条蓝带：agents —— AI 的大脑怎么配（OpenClaw配置示例）

看全景图里最上面的蓝色横条，这就是 agents 模块。它定了 AI 用哪个模型、工作区在哪、超时多久、模型挂了怎么办。

术语说明：agents 在 OpenClaw 中指"智能体"，是 AI 能力的封装单元。它连接大语言模型（LLM），提供对话、推理和工具调用能力。Gateway 可以同时运行多个 Agent，每个 Agent 独立管理自己的配置、上下文和工具权限。

最小配置：

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-6" },
    },
  },
}

这个配置只有三行，但已经能让 Gateway 跑起来——你可以在 Control UI 里跟 AI 对话了。

完整一点的：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",     // 工作区根目录
      model: {
        primary: "anthropic/claude-sonnet-4-6", // 主模型
        fallbacks: ["openai/gpt-5.2"],          // 备用模型
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
      thinkingDefault: "low",         // 思考深度
      timeoutSeconds: 600,            // 超时（秒）
      maxConcurrent: 3,               // 最大并发
      heartbeat: {
        every: "30m",                 // 心跳间隔，"0m" 禁用
        target: "last",               // 发给谁
        prompt: "HEARTBEAT",          // 心跳词
      },
    },
  },
}

看图里蓝色高亮的 model、workspace、heartbeat、fallbacks、timeout——就是图中标出的那些彩色圆角小方块。

字段	作用	对应图中位置
workspace	工作目录，放 SOUL.md 和 skills	蓝色条里的蓝色 pill
model.primary	主模型，格式 提供商/模型名	标蓝的圆角块
model.fallbacks	主模型挂了换这个	标蓝的圆角块
models	别名表，定义了才能用命令切	图中标注为 fallback 那行
heartbeat	定时自检，适合主动提醒场景	最右边那个

第二条绿带：gateway —— 门户怎么开（OpenClaw配置示例）

图中第二条绿色横条，控制 Gateway 监听在哪、谁可以接入。这是安全的第一道防线。

{
  gateway: {
    port: 18789,                    // 端口
    bind: "loopback",               // loopback | network
    auth: {
      mode: "token",                // off | token | password
      token: "your-gateway-token",  // 共享密钥
    },
    reload: {
      mode: "hybrid",               // hybrid | hot | restart | off
      debounceMs: 300,              // 防抖
    },
  },
}

图中绿色高亮的 port、bind、auth、reload 是核心，旁边灰色的 tailscale、controlUi 是扩展。

字段	作用	安全建议
port	默认 18789，被占用则改	-
bind	loopback（仅本机）最安全；改 network 前先配 auth	暴露到局域网必开认证
auth.mode	off 不验证、token 共享密钥、password 用户名密码	生产环境用 token 或 password
reload.mode	hybrid 自动热加载 + 自动重启最推荐	默认即可

第三条紫带：channels —— AI 从哪里收消息（OpenClaw配置示例）

紫色横条是多渠道接入。每加一个渠道（Telegram/WhatsApp/Discord…），就在这个紫色区域加一段配置。

{
  channels: {
    telegram: {
      enabled: true,                   // 启用
      botToken: "123456:ABCDEF",      // Bot Token
      dmPolicy: "pairing",            // 私聊策略
      allowFrom: ["123456789"],       // 白名单
      groups: {
        "*": { requireMention: true }, // 群组需 @ 才回复
      },
    },
  },
}

图中紫色条里的彩色 pill 就是目前支持的渠道：Telegram（紫）、WhatsApp（紫）、Discord（紫）、Slack（灰）、Signal（灰）。后面的文章逐一讲如何申请 Token、配置 Webhook。

术语说明：dmPolicy 全称 Direct Message Policy，即"私信策略"，控制陌生人如何与你的 AI 助手建立私聊。OpenClaw 把"谁可以私聊我的 AI"作为安全首要考量，默认采用最严格的配对模式。

dmPolicy 四种模式（对应图中的小标签 dmPolicy、allowFrom、groups）：

模式	含义	安全等级
pairing	陌生人需配对码验证	★★★ 推荐
allowlist	仅 allowFrom 列表内可对话	★★★ 固定人群用
open	任何人可私聊（需 allowFrom: ["*"]）	★ 公开服务
disabled	不处理私聊	- 仅群聊

第四条橙带：session —— 记忆怎么管（OpenClaw配置示例）

橙色横条控制 AI 的"记忆"：不同人的对话是混在一起还是各自独立、多久清一次上下文。

{
  session: {
    dmScope: "per-channel-peer",    // 会话隔离
    reset: {
      mode: "daily",                // off | daily | idle
      atHour: 4,                    // daily: 每天几点重置
      idleMinutes: 120,             // idle: 不活动多久重置
    },
  },
}

图中橙色条标注了 dmScope、reset、sendPolicy、threadBindings——这些是核心记忆策略。

dmScope 隔离级别：

值	含义	适用场景
main	所有人共享一个会话	单人用
per-channel-peer	每人每渠道独立	多人用，推荐

张三在 WhatsApp 聊的内容，李四在 Telegram 完全看不到——靠的就是 per-channel-peer 这个设置。

第五条红带：tools —— 工具与权限（OpenClaw配置示例）

红色横条是工具白名单。OpenClaw 能做的事很多：读写文件、执行命令、浏览器操作。但默认全关，需要在这里显式开启。

{
  tools: {
    allow: ["exec", "process", "read", "write", "edit"],
    deny: ["browser", "canvas"],
    exec: { timeoutSec: 1800 },
    elevated: {
      enabled: true,
      allowFrom: { whatsapp: ["+15555550123"] },
    },
  },
}

图中红色高亮的 exec、browser、read/write、allow、deny、elevated 都是特权操作——红色代表危险。

工具风险等级：

工具	能力	风险	图中颜色
read/write/edit	读写文件，改代码	低	红（但标注为 read/write）
exec	执行 shell 命令	中	红，配合 sandbox 用
browser	操控 Chrome 浏览器	高	红，图中单独标注

初学者建议：先用 allow: ["read", "write", "edit"]，熟悉了再逐步放开 exec 和 browser。

配置热重载：改了不用重启（OpenClaw配置示例）

OpenClaw 的一个设计亮点是热重载。大部分配置改了之后自动生效。

术语说明：热重载（Hot Reload）指在不停止服务的情况下应用配置变更。OpenClaw 监听 openclaw.json 文件变化，校验语法后自动将新配置推送到运行中的 Gateway，无需手动重启进程。

什么能热加载、什么必须重启（看图理解：蓝色/绿色/紫色/橙色/红色的横条内容都能热加载；左侧 port、bind、plugins 改后要重启）：

可热加载（图中五条彩色带）	需重启
agents、channels、session、tools 等	gateway.port、gateway.bind、gateway.auth、plugins

gateway.reload.mode 有四种：

模式	行为
hybrid（默认）	安全配置热加载 + 关键配置自动重启。推荐
hot	只热加载，需重启时打日志提醒
restart	任何改动都重启
off	关闭了，手动重启后生效

简单记：改 Agent/模型/渠道/会话/工具行为不需要重启；改 Gateway 本身（端口/绑定/认证）要重启。hybrid 模式下重启是自动的。

Secret 管理：别在配置文件里写 Key（OpenClaw配置示例）

API Key 明文写在 openclaw.json 里是危险的。

环境变量替换（在配文中用 ${VAR}）：

{
  env: {
    OPENAI_API_KEY: "${OPENAI_API_KEY}",  // 从环境变量读
    vars: { GROQ_API_KEY: "gsk-..." },    // 或直接写 env 块
  },
}

更复杂的用 SecretRef：

{
  models: {
    providers: {
      openai: {
        apiKey: {
          source: "env",    // 可选 env | file | exec
          id: "OPENAI_API_KEY",
        },
      },
    },
  },
}

.env 文件：OpenClaw 自动加载 ~/.openclaw/.env 和当前目录的 .env，优先级是已有变量 > .env。

配置拆分：$include 结构化管理（OpenClaw配置示例）

当你接上五六个渠道、配了多个 Agent，配置文件会变成几百行。用 $include 拆分：

术语说明：$include 是 OpenClaw 在 JSON5 基础上扩展的指令，用于将配置分散到多个文件。主文件保持简洁，各模块配置独立维护，便于版本控制和多人协作。

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  channels: {
    $include: [
      "./channels/telegram.json5",
      "./channels/whatsapp.json5",
    ],
  },
}

规则：

• 单文件：替换当前对象
• 数组：按顺序深度合并，后面覆盖前面
• 嵌套最多 10 层

对应回全景图：左边 openclaw.json 仍然是总入口，实际内容分散在多个 .json5 文件里。

三种修改配置的方式（OpenClaw配置示例）

方式	命令	适合场景	效果验证
直接编辑	vi ~/.openclaw/openclaw.json	批量改、熟悉后日常用	保存后自动热加载
CLI	openclaw config set agents.defaults.heartbeat.every "2h"	快速改单个值	自动校验语法
Control UI	http://localhost:18789 → Config 标签	初期探索、可视化编辑	表单 + Raw JSON 双模式

实操建议：初期用 Control UI 看图式界面熟悉各字段含义，熟悉后用 CLI 快速改单值，最终沉淀为直接编辑文件 + 版本控制。

踩坑：OpenClaw配置常见问题

坑 1：字段名写错，Gateway 拒绝启动

OpenClaw schema 校验极严。agents 写成 agent、丢掉一个逗号——统统报错。

排查：openclaw doctor，会逐行提示哪里错了。

坑 2：改了 port 但没生效

gateway.port 属于 Gateway 本身配置，改后要重启。hybrid 模式下自动重启；hot 模式下手动 openclaw gateway restart。

坑 3：dmPolicy 选了 open

很多人觉得"我自己用反正"。如果你的 Gateway 暴露在公网（Tailscale Funnel），任何人都能给 AI 发消息。默认用 pairing 最安全。

坑 4：workspace 路径不存在不报错

找不到 AGENTS.md 时，Agent 会用内置默认 prompt，不会报错，但行为跟你预期不同。确认路径存在且可读写。

坑 5：models 别名不在白名单里

models 是模型切换的白名单。想用 /model 命令切换，必须先在 models 里定义别名。不定义也能用——只是不能通过命令切。

常见问题（FAQ）

Q：配置后 Gateway 起不来，怎么看报错？

openclaw doctor        # 查看具体配置错误
openclaw logs          # 查看详细日志

Q：多个 Gateway 实例能共存吗？

可以。每个实例用不同的 port 和 OPENCLAW_STATE_DIR 环境变量，完全隔离。

Q：配置文件里的 ${VAR} 变量读不到怎么办？

Gateway 启动时如果发现环境变量不存在，直接报错退出。确保变量已 export，或写在 .env 文件。

总结：OpenClaw配置核心要点

openclaw.json 是 OpenClaw 的唯一配置入口，JSON5 格式。看全景图复习：五个彩色带控制五种能力：

1. agents（蓝色） — 不配这个，AI 没有大脑
2. gateway（绿色） — 配好端口和认证，安全第一
3. channels（紫色） — 至少接一个渠道，AI 才有耳朵和嘴巴
4. session（橙色） — 多人使用时配好 dmScope 隔离
5. tools（红色） — 逐步放开，别一开始全开特权

热重载让大部分改动不用重启，hybrid 模式最省心。敏感信息用环境变量或 SecretRef，别明文写 Key。

30 行配置够用，300 行不嫌多——随着接入渠道增多，用 $include 拆分管理。

---

下一篇预告

〖OpenClaw系列〗onboard 新手引导全流程拆解

配置文件讲完了。下一篇我们跑一遍 openclaw onboard——这个交互式向导到底做了什么、每一步生成的配置对应今天讲的哪个模块。

本文是系列第3篇，前序文章：第1篇：AI网关是什么 | 第2篇：安装和启动

---

📌 觉得有用？点个「在看」 👇
👨‍💻 关注「敏叔侃技术」，每周更新 OpenClaw 实战干货
⭐ 收藏这篇文章，配 openclaw.json 时翻出来对照结构图修改