夜雨聆风OpenClaw 核心配置详解：从入门到精通，看这一篇就够了
很多新手刚接触 OpenClaw，对着 openclaw.json 不知道从哪下手，每个配置块都是干嘛的？哪些必填哪些选填？今天我把四个核心配置块一个个给你讲明白，看完你就能自己动手配了。
🦞 环境准备
你只需要：
~/.openclaw/openclaw.json🦞 内容讲解：四个核心配置块
OpenClaw 的配置文件就四个核心块：
models → 大模型从哪来agents → 有哪些智能体channels → 消息渠道（飞书/电报等）怎么接bindings → 消息路由给谁我们一个个来：
1️⃣ models 配置：大模型供应商
"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 |
~/.openclaw/.env 环境变量，用 ${VAR_NAME} 引用，git 也不会提交上去merge 就行，OpenClaw 默认已经带了很多公共模型配置，你只需要加自己的 API Key2️⃣ agents 配置：智能体列表
"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 配置：消息渠道接入
"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 放进去，别人用不了你的 botallowFrom 里面放用户 ID 或群组 ID，只有这些人能发消息过来4️⃣ bindings 配置：路由绑定
OpenClaw 路由匹配优先级：越精确越优先 → 精确对端 > 账户 > 渠道 > 默认
"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 | 匹配条件，所有条件都满足才命中 |
🦞 完整可运行配置示例
给你一个完整能直接用的配置，复制过去改改 API Key 就能跑：
{
"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
openclaw gateway restart第三步：检查启动日志
tail ~/.openclaw/gateway.log看不到报错就是启动成功了。如果有报错，日志会告诉你哪个配置错了，照着改就行。
第四步：发消息测试
在你的渠道（比如飞书）发一条消息，如果能正常回复，说明配置完全正确 ✅
🚀 三个进阶方向
❓ 五个常见问题
A：一定要重启 Gateway！配置只在启动的时候加载一次，不改不重启永远不生效。
A：你没标记哪个智能体是 default: true，必须 exactly one 有这个标记。
A：一般就是少了逗号或者多了逗号，最后一个数组元素后面不能有逗号，去 JSONLint 一验就出来。
A：在 ~/.openclaw/.env 里写 API_KEY=xxxx，配置里写 "apiKey": "${API_KEY}"，OpenClaw 自动读。
A：不用，不配的话自动走默认智能体，省事。
