很多人第一次用 OpenClaw，最容易卡在 ~/.openclaw/openclaw.json：字段太多、改错一个就启动失败。
这篇文章把官方文档里最常用的配置项按“能用、好理解、少踩坑”的方式重新整理一遍。你可以把它当成：OpenClaw 配置的速查+上手模板。
一、先搞清楚：配置文件长什么样
- 文件位置：~/.openclaw/openclaw.json
- 格式：JSON5（支持注释、尾随逗号）
- 重要提醒：OpenClaw 对配置很严格，出现未知字段会导致 Gateway 直接拒绝启动。
配置通常由这些模块组成：
- channels：接入哪些聊天渠道（Telegram/Slack/Discord/WhatsApp…）
- agents：你有哪些 Agent、各自用什么模型
- models：模型提供商与模型列表（OpenAI/Anthropic…）
- gateway：Gateway 端口、鉴权、热重载
- cron：定时任务
- bindings：把“某个渠道/账号”路由到“某个 Agent”
- env：环境变量（API Key 等）
二、Channels：让 OpenClaw 能“接到消息”
channels 主要决定两件事：
1. 接入哪个平台（telegram/discord/slack/whatsapp…）
2. 谁可以来找你（DM 与群聊策略）
2.1 最常用的通用字段（记住这几个就够用）
- enabled：是否启用该渠道
- dmPolicy：私聊策略
- allowFrom：允许的用户列表
- groupPolicy：群聊策略
- historyLimit：保留多少条历史消息（用于上下文）
2.2 DM Policy（私聊策略）怎么选
- pairing（默认）：陌生人先拿配对码，需要管理员批准
- allowlist：只允许 allowFrom 里的人
- open：所有人都能私聊（通常不建议；需要 allowFrom: [“*”]）
- disabled：忽略所有私聊
2.3 Group Policy（群聊策略）怎么选
- allowlist（默认）：只允许配置过的群
- open：允许所有群（仍可配合“必须@我”来限流）
- disabled：拒绝所有群消息
2.4 渠道示例（照抄再改参数）
WhatsApp 示例（关键是 dmPolicy / allowFrom / textChunkLimit / mediaMaxMb / groups）：
{
"channels": {
"whatsapp": {
"dmPolicy": "pairing",
"allowFrom": ["+15555550123"],
"textChunkLimit": 4000,
"mediaMaxMb": 50,
"groups": {
"*": { "requireMention": true }
}
}
}
}Telegram 示例（关键是 botToken / groups / streaming）：
{
"channels": {
"telegram": {
"botToken": "123456:ABC...",
"dmPolicy": "pairing",
"groups": {
"*": { "requireMention": true }
},
"customCommands": [{ "command": "backup" }],
"streaming": "partial"
}
}
}Discord 示例（关键是 token / guilds / threadBindings）：
{
"channels": {
"discord": {
"token": "...",
"guilds": {
"123456789": {
"requireMention": false,
"channels": {
"general": { "allow": true }
}
}
},
"threadBindings": { "enabled": true }
}
}
}Slack 示例（关键是 botToken / appToken / slashCommand）：
{
"channels": {
"slack": {
"enabled": true,
"botToken": "xoxb-...",
"appToken": "xapp-...",
"slashCommand": { "enabled": true }
}
}
}三、Agents：你要几个“分身”，怎么分工
agents 用来定义你的 Agent 列表，以及默认行为。
一个典型配置长这样：
{
"agents": {
"list": [
{
"id": "agent_robot1",
"workspace": "~/.openclaw/workspace/robot1",
"model": "anthropic/claude-sonnet-4-6",
"identity": {
"name": "总助",
"emoji": "👔"
}
}
],
"defaults": {
"model": { "primary": "anthropic/claude-sonnet-4-6" },
"maxConcurrent": 40000
}
}
}你需要重点关注：
- list[]：有几个 Agent，就写几个对象
- id：唯一标识（后面做路由绑定会用到）
- workspace：每个 Agent 的工作目录（建议分开）
- model：这个 Agent 默认用哪个模型
四、Models：把“模型提供商”和“模型清单”写进去
models 主要做两件事：
- 配置提供商（baseUrl、apiKey 等）
- 配置该提供商下可用的模型列表（id、contextWindow、maxTokens…）
示例：
{
"models": {
"mode": "merge",
"providers": {
"anthropic": {
"baseUrl": "<https://api.anthropic.com>",
"apiKey": "sk-ant-...",
"models": [
{
"id": "claude-sonnet-4-6",
"contextWindow": 200000,
"maxTokens": 8192
}
]
},
"openai": {
"baseUrl": "<https://api.openai.com/v1>",
"models": [
{
"id": "gpt-4.1",
"contextWindow": 1000000
}
]
}
}
}
}提示：
- apiKey 通常是最容易忘/最容易写错的
- 如果模型调用失败，优先检查 models.providers.*.apiKey
五、Gateway：端口、鉴权、热重载
Gateway 是 OpenClaw 的“入口服务”。最常动的配置是端口和鉴权：
{
"gateway": {
"port": 18789,
"auth": {
"mode": "token",
"token": "your-token"
},
"reload": {
"mode": "hybrid"
}
}
}热重载模式怎么选（简单版）
- hybrid（默认）：安全变更热应用；关键变更自动重启（推荐）
- hot：只热应用安全变更，需要重启时会提示警告
- restart：任何改动都重启（最省心但打断服务）
- off：关闭热重载
六、Cron：让它“定时干活”
想每天 10 点自动写一篇文章？可以写 Cron：
{
"cron": [
{
"id": "daily-article",
"name": "公众号每日文章",
"enabled": true,
"schedule": "0 10 * * *",
"payload": {
"kind": "systemEvent",
"text": "写一篇公众号文章"
}
}
]
}你最需要盯住的字段：
- schedule：Cron 表达式
- payload.kind：事件类型
- payload.text：到点要执行的内容
七、Bindings：把“消息来源”分发给“哪个 Agent”
如果你有多个 Agent，就需要 bindings 来指定路由规则：
{
"bindings": [
{
"agentId": "agent_robot1",
"match": {
"channel": "feishu",
"accountId": "robot1"
}
},
{
"agentId": "agent_robot2",
"match": {
"channel": "discord"
}
}
]
}理解方式：
- match：匹配“从哪里来”的消息
- agentId：命中后交给哪个 Agent
八、Environment：API Key 放哪儿更合适
OpenClaw 支持把 Key 写在 env 里：
{
"env": {
"OPENROUTER_API_KEY": "sk-or-...",
"ANTHROPIC_API_KEY": "sk-ant-...",
"vars": {
"GROQ_API_KEY": "gsk-..."
}
}
}环境变量来源优先级（从高到低）：
1. 系统环境变量
2. ~/.openclaw/.env（全局）
3. ./.env（工作区）
4. 配置文件 env 字段
如果你在多个环境部署，通常建议把 Key 放在系统环境变量或 .env，配置文件里少放敏感信息。
九、最常见的启动/调试命令
配置改完后，先做验证再重启，能省掉大量排查时间：
# 检查配置有效性
openclaw doctor
# 自动修复配置问题
openclaw doctor --fix
# 查看 Gateway 状态
openclaw gateway status
# 跟踪日志
openclaw logs --follow十、常见报错速查（先看这里）
- Gateway 拒绝启动：大概率是“出现未知字段 / 字段写错层级” → 先跑 openclaw doctor
- 渠道无法连接：token 过期或写错 → 检查 channels.*.botToken / token
- 消息没反应：被策略拦截了 → 检查 dmPolicy / groupPolicy / requireMention
- 模型调用失败：Key 无效或没加载 → 检查 models.providers.*.apiKey 或环境变量
参考
OpenClaw 官方文档：https://docs.openclaw.ai
转载作品，原作者：AI增效手册，文章来源：https://mp.weixin.qq.com/s/1FoFeUJC8VO769sddNgzjg
