OpenClaw 核心配置详解:从入门到精通,看这一篇就够了

OpenClaw 核心配置详解：从入门到精通，看这一篇就够了

很多新手刚接触 OpenClaw，对着 openclaw.json 不知道从哪下手，每个配置块都是干嘛的？哪些必填哪些选填？今天我把四个核心配置块一个个给你讲明白，看完你就能自己动手配了。

•--

🦞 环境准备

你只需要：

•已经安装好 OpenClaw（不会装看我之前发的安装教程）

•一个文本编辑器（VS Code、Vim 都行）

•知道配置文件在哪：一般在 ~/.openclaw/openclaw.json

•坑点提前说： JSON 语法对逗号引号要求很严，改完可以去 JSONLint 验证一下格式，少个逗号都会启动失败。

•--

🦞 内容讲解：四个核心配置块

OpenClaw 的配置文件就四个核心块：

1.models → 大模型从哪来

2.agents → 有哪些智能体

3.channels → 消息渠道（飞书/电报等）怎么接

4.bindings → 消息路由给谁

我们一个个来：

1️⃣ `models` 配置：大模型供应商

•一句话作用： 告诉 OpenClaw 你有哪些大模型可以用，API 密钥是什么。

JSON

"models": {
  "mode": "merge",
  "providers": {
    "volcengine": {
      "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
      "apiKey": "${API_KEY}",
      "api": "openai-completions",
      "models": [
        {
          "id": "ark-code-latest",
          "name": "Ark-Code-Latest",
          "contextWindow": 256000,
          "maxTokens": 8192
        }
      ]
    },
    "openai": {
      "apiKey": "sk-xxxxxx",
      "baseUrl": "https://api.openai.com/v1",
      "api": "openai-chat",
      "models": [
        {
          "id": "gpt-4o",
          "name": "GPT-4o",
          "contextWindow": 128000,
          "maxTokens": 4096
        }
      ]
    }
  }
}

•字段逐个说：

字段	必须填？	作用
`mode`	✅	`merge` = 和默认配置合并（推荐），`replace` = 完全替换默认
`providers`	✅ 至少一个	每个模型供应商一个块，比如 volcengine/openai/xai
`.apiKey`	✅	API 密钥，可以用 `${ENV_VAR}` 从环境变量读取
`.baseUrl`	大部分需要	API 入口地址，官方 OpenAI 可以不填（用默认），第三方兼容需要填
`.api`	✅	API 类型：`openai-chat`/`openai-completions`/`anthropic` 等
`.models[]`	✅	这个供应商下有哪些模型可以用
`models[].id`	✅	模型 ID，后面智能体配置要引用这个
`models[].name`	✅	模型显示名字
`models[].contextWindow`	✅	上下文窗口大小，单位 tokens
`models[].maxTokens`	✅	单次回复最大 tokens

•实战技巧：

•安全第一： API 密钥别直接写在配置里，放 ~/.openclaw/.env 环境变量，用 ${VAR_NAME} 引用，git 也不会提交上去

•合并模式： 一般用 merge 就行，OpenClaw 默认已经带了很多公共模型配置，你只需要加自己的 API Key

•多模型混用： 可以同时配多个供应商，编码用火山，聊天用 GPT-4o，完全没问题

•--

2️⃣ `agents` 配置：智能体列表

•一句话作用： 定义你有哪些智能体，每个智能体干自己的活，上下文不串。

JSON

"agents": {
  "defaults": {
    "model": { "primary": "volcengine/ark-code-latest" },
    "maxConcurrent": 4
  },
  "list": [
    {
      "id": "main",
      "name": "主会话",
      "workspace": "~/.openclaw/workspace",
      "default": true
    },
    {
      "id": "article",
      "name": "写文章",
      "workspace": "~/.openclaw/workspace/article",
      "model": { "primary": "volcengine/ark-code-latest" },
      "default": false
    }
  ]
}

•字段逐个说：

字段	必须填？	作用
`defaults`	❌ 推荐填	所有智能体的默认值，不用每个都重复写
`defaults.model.primary`	推荐填	默认用哪个模型，格式 `供应商ID/模型ID`
`defaults.maxConcurrent`	❌	最大并发会话数，一般 2-8 够了
`list[]`	✅ 至少一个	智能体列表
`list[].id`	✅	智能体 ID，路由绑定要用
`list[].name`	✅	显示名字
`list[].workspace`	✅	工作目录，不同智能体放不同目录，数据隔离
`list[].model`	❌	不填就用 defaults 里的
`list[].default`	✅ exactly one	哪个是默认兜底智能体，只能有一个标记 `true`

•实战技巧：

•按任务拆分： 写文章一个智能体，读研报一个智能体，开发项目一个智能体，互不干扰

•默认只一个： 必须有且只有一个智能体标记 default: true，不然启动会报错

•工作区隔离： 不同智能体一定要用不同 workspace，不然文件和记忆会串

•--

3️⃣ `channels` 配置：消息渠道接入

•一句话作用： 配置你用什么聊天渠道（飞书、微信、WhatsApp 等），每个渠道的密钥是什么。

JSON

"channels": {
  "feishu": {
    "enabled": true,
    "defaultAccount": "article",
    "groupPolicy": "allowlist",
    "dmPolicy": "allowlist",
    "accounts": {
      "article": {
        "appId": "cli_xxxx0",
        "appSecret": "xxxxxx",
        "allowFrom": ["ou_xxxx"]
      }
    }
  },
  "telegram": {
    "enabled": true,
    "defaultAccount": "main",
    "accounts": {
      "main": {
        "token": "123456:ABC-def"
      }
    }
  }
}

•字段逐个说：

字段	必须填？	作用
`channel.`	✅ 至少一个	`feishu`/`telegram`/`whatsapp`/`signal`/`discord` 等
`.enabled`	✅	开不开这个渠道，`true`/`false`
`.defaultAccount`	✅	默认用哪个账户
`.groupPolicy`	✅	群组访问策略：`open` 任何人都能聊，`allowlist` 只允许列表里
`.dmPolicy`	✅	私聊访问策略，同上
`.accounts`	✅ 至少一个	这个渠道下的账户列表，一个渠道可以有多个 bot
`accounts[].appId/appSecret`	飞书	飞书应用的 AppID 和 AppSecret
`accounts[].token`	电报	Telegram Bot Token

•实战技巧：

•隐私安全： 自己用就开 allowlist，只把你的 ID 放进去，别人用不了你的 bot

•多 bot 分离： 一个用途一个 bot，写文章一个 bot，聊天一个 bot，好管理

•允许列表： allowFrom 里面放用户 ID 或群组 ID，只有这些人能发消息过来

•--

4️⃣ `bindings` 配置：路由绑定

•一句话作用： 告诉 OpenClaw，"这条消息该给哪个智能体处理"。

OpenClaw 路由匹配优先级：越精确越优先 → 精确对端 > 账户 > 渠道 > 默认

JSON

"bindings": [
  {
    "agentId": "article",
    "match": {
      "channel": "feishu",
      "accountId": "article"
    }
  },
  {
    "agentId": "main",
    "match": {
      "channel": "telegram"
    }
  }
]

•四种常用匹配方式：

优先级	方式	适用场景	写法示例
1️⃣	精确对端	特定用户/群组走特定智能体	`match: { channel: "feishu", peer: { kind: "user", id: "ou_xxx" } }`
2️⃣	账户级别	不同 bot 走不同智能体	`match: { channel: "feishu", accountId: "article" }`
3️⃣	渠道级别	整个渠道走同一个智能体	`match: { channel: "telegram" }`
4️⃣	默认兜底	其他情况兜底	不用写，找 `default: true` 的智能体

•字段逐个说：

字段	作用
`agentId`	命中之后转给哪个智能体，要和 `agents.list[].id` 对应
`match`	匹配条件，所有条件都满足才命中

•实战技巧：

•多 bot 就用账户级别： 这是最常用的方案，一个 bot 绑定一个智能体，清晰明了

•同一个 bot 分给不同人： 用精确对端匹配，你用 article，你朋友用 main，互不干扰

•记不住优先级： 就记住一句话——越具体越优先

•--

🦞 完整可运行配置示例

给你一个完整能直接用的配置，复制过去改改 API Key 就能跑：

JSON

{
  "models": {
    "mode": "merge",
    "providers": {
      "volcengine": {
        "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "apiKey": "${API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "ark-code-latest",
            "name": "Ark-Code-Latest",
            "contextWindow": 256000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "volcengine/ark-code-latest" },
      "maxConcurrent": 4
    },
    "list": [
      {
        "id": "article",
        "name": "文章写作",
        "workspace": "~/.openclaw/workspace/article",
        "default": true
      }
    ]
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "defaultAccount": "article",
      "groupPolicy": "allowlist",
      "dmPolicy": "allowlist",
      "accounts": {
        "article": {
          "appId": "cli_xxxxxx",
          "appSecret": "YOUR_APP_SECRET",
          "allowFrom": ["ou_xxxxx"]
        }
      }
    }
  },
  "bindings": [
    {
      "agentId": "article",
      "match": {
        "channel": "feishu",
        "accountId": "article"
      }
    }
  ]
}

•--

🦞 成果展示：配置完怎么验证？

第一步：检查 JSON 格式

去 https://jsonlint.com/ 粘贴你的配置，显示 Valid JSON 就 OK，有错误按照提示改。

第二步：重启 Gateway

Bash

openclaw gateway restart

第三步：检查启动日志

Bash

tail ~/.openclaw/gateway.log

看不到报错就是启动成功了。如果有报错，日志会告诉你哪个配置错了，照着改就行。

第四步：发消息测试

在你的渠道（比如飞书）发一条消息，如果能正常回复，说明配置完全正确 ✅

•--

🚀 三个进阶方向

1.多模型自动 fallback：配置多个模型，主模型挂了自动切备用，高可用

2.按对话长度选模型：短对话用 GPT-4o，长上下文用 Claude 3，省钱效果又好

3.权限分级：给不同用户不同智能体，你自己用全权限，给朋友用只读权限

0.--

❓ 五个常见问题

•Q：改完配置不生效怎么办？

A：一定要重启 Gateway！配置只在启动的时候加载一次，不改不重启永远不生效。

•Q：提示 "No default agent found" 是什么错？

A：你没标记哪个智能体是 default: true，必须 exactly one 有这个标记。

•Q：提示 JSON 语法错怎么办？

A：一般就是少了逗号或者多了逗号，最后一个数组元素后面不能有逗号，去 JSONLint 一验就出来。

•Q：API Key 放环境变量怎么读？

A：在 ~/.openclaw/.env 里写 API_KEY=xxxx，配置里写 "apiKey": "${API_KEY}"，OpenClaw 自动读。

•Q：我只有一个智能体还要配 bindings 吗？

A：不用，不配的话自动走默认智能体，省事。

•--

•作者：小飞哥的龙虾

•OpenClaw 技术运营专家，一人公司实践派

•关注我，分享更多 OpenClaw 实战干货

OpenClaw 核心配置详解：从入门到精通，看这一篇就够了

🦞 环境准备

🦞 内容讲解：四个核心配置块

1️⃣ models 配置：大模型供应商

2️⃣ agents 配置：智能体列表

3️⃣ channels 配置：消息渠道接入

4️⃣ bindings 配置：路由绑定

🦞 完整可运行配置示例

🦞 成果展示：配置完怎么验证？

第一步：检查 JSON 格式

第二步：重启 Gateway

第三步：检查启动日志

第四步：发消息测试

🚀 三个进阶方向

❓ 五个常见问题

1️⃣ `models` 配置：大模型供应商

2️⃣ `agents` 配置：智能体列表

3️⃣ `channels` 配置：消息渠道接入

4️⃣ `bindings` 配置：路由绑定