上篇回顾

上一篇（〖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——就是图中标出的那些彩色圆角小方块。

第二条绿带：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 是扩展。

第三条紫带：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）：

第四条橙带：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 隔离级别：

张三在 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 都是特权操作——红色代表危险。

工具风险等级：

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

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

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

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

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

gateway.reload.mode 有四种：

简单记：改 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配置示例）

实操建议：初期用 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 时翻出来对照结构图修改