Appearance
OpenClaw openclaw.json 终极配置指南：Gateway 稳稳启动的秘诀
很多人第一次用 OpenClaw，最容易卡在
~/.openclaw/openclaw.json：字段太多、改错一个就启动失败。这篇文章把官方文档里最常用的配置项按"能用、好理解、少踩坑"的方式重新整理一遍。
OpenClaw GitHub: https://github.com/OpenClawAI/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 主要决定两件事：
- 接入哪个平台（telegram/discord/slack/whatsapp…）
- 谁可以来找你（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 示例：
json
{
"channels": {
"whatsapp": {
"dmPolicy": "pairing",
"allowFrom": ["+15555550123"],
"textChunkLimit": 4000,
"mediaMaxMb": 50,
"groups": {
"*": { "requireMention": true }
}
}
}
}Telegram 示例：
json
{
"channels": {
"telegram": {
"botToken": "123456:ABC...",
"dmPolicy": "pairing",
"groups": {
"*": { "requireMention": true }
},
"streaming": true
}
}
}三、Agents：配置你的 AI 助手
agents 定义你有哪些 Agent、各自用什么模型和权限。
3.1 基本结构
json
{
"agents": {
"defaults": {
"model": "claude-sonnet-4-6",
"sandbox": { "mode": "off" }
},
"main": {
"model": "claude-opus-4-6"
},
"developer": {
"model": "gpt-4o",
"sandbox": { "mode": "docker" }
}
}
}3.2 关键字段
| 字段 | 说明 |
|---|---|
| defaults | 所有 Agent 的默认配置 |
| model | 使用的模型名称 |
| sandbox | 沙箱配置（off/docker/ssh） |
| memory | 记忆后端配置 |
3.3 沙箱模式
| 模式 | 说明 |
|---|---|
| off | 不使用沙箱 |
| docker | 在 Docker 容器中执行 |
| ssh | 在远程服务器上执行 |
四、Models：模型提供商配置
models 定义你可以使用的模型列表和提供商。
4.1 基本结构
json
{
"models": {
"openai": {
"api_key": "${OPENAI_API_KEY}",
"models": ["gpt-4o", "gpt-4o-mini", "o1", "o1-mini"]
},
"anthropic": {
"api_key": "${ANTHROPIC_API_KEY}",
"models": ["claude-opus-4-6", "claude-sonnet-4-6"]
}
}
}4.2 关键字段
| 字段 | 说明 |
|---|---|
| api_key | API 密钥（建议用环境变量） |
| models | 可用的模型列表 |
| baseURL | 自定义 API 地址（可选） |
⚠️ 建议：API Key 不要直接写在配置文件里，用环境变量 ${OPENAI_API_KEY} 更安全。
五、Gateway：网关配置
gateway 控制 Gateway 的端口、鉴权和热重载。
5.1 基本配置
json
{
"gateway": {
"port": 4242,
"auth": true,
"hotReload": true,
"maxRequestBodySize": "10mb"
}
}5.2 关键字段
| 字段 | 说明 |
|---|---|
| port | Gateway 监听端口 |
| auth | 是否启用鉴权 |
| hotReload | 是否启用热重载 |
| maxRequestBodySize | 请求体最大限制 |
六、Cron：定时任务
cron 定义定期执行的任务。
6.1 基本配置
json
{
"cron": [
{
"id": "morning-briefing",
"schedule": "0 9 * * 1-5",
"prompt": "执行晨间简报"
}
]
}6.2 关键字段
| 字段 | 说明 |
|---|---|
| id | 任务唯一标识 |
| schedule | cron 表达式 |
| prompt | 执行时发送的提示词 |
七、Bindings：路由绑定
bindings 把"某个渠道/账号"路由到"某个 Agent"。
7.1 基本配置
json
{
"session": {
"bindings": [
{
"channel": "telegram",
"account": "developer",
"agent": "developer"
}
],
"defaultAgent": "main"
}
}7.2 关键字段
| 字段 | 说明 |
|---|---|
| channel | 渠道名称 |
| account | 账号名称 |
| agent | 路由到的 Agent |
| defaultAgent | 默认 Agent |
八、完整配置示例
json
{
"channels": {
"telegram": {
"botToken": "${TELEGRAM_BOT_TOKEN}",
"dmPolicy": "pairing",
"groups": {
"*": { "requireMention": true }
}
}
},
"agents": {
"defaults": {
"model": "claude-sonnet-4-6",
"sandbox": { "mode": "off" }
}
},
"models": {
"anthropic": {
"api_key": "${ANTHROPIC_API_KEY}",
"models": ["claude-opus-4-6", "claude-sonnet-4-6"]
}
},
"gateway": {
"port": 4242,
"hotReload": true
},
"session": {
"defaultAgent": "main"
}
}九、踩坑提醒
| 问题 | 原因 | 解决方案 |
|---|---|---|
| Gateway 启动失败 | 配置文件有未知字段 | 检查拼写，删除多余字段 |
| API Key 无效 | 环境变量未设置 | 检查 ~/.openclaw/env 文件 |
| 消息无响应 | dmPolicy 配置错误 | 检查 allowFrom 列表 |
| Agent 不切换 | bindings 配置错误 | 检查路由规则 |
配置调试命令
bash
# 检查配置是否有效
openclaw config validate
# 查看当前配置
openclaw config get
# 重启 Gateway
openclaw restart总结
| 模块 | 一句话说明 |
|---|---|
| channels | 接入哪些平台、谁能找你 |
| agents | 有哪些 AI 助手、用什么模型 |
| models | 模型提供商和模型列表 |
| gateway | 网关端口、鉴权、热重载 |
| cron | 定时任务 |
| bindings | 消息路由规则 |
配置原则：最小可用 → 先跑起来 → 逐步补充。不要一开始就写满，出错难排查。
