OpenClaw 通过 ~/.openclaw/openclaw.json（JSON5 格式）管理所有配置。配置文件缺失时使用安全默认值，按需添加即可。
极简配置
json
{
"agents": { "defaults": { "workspace": "~/.openclaw/workspace" } },
"channels": { "whatsapp": { "allowFrom": ["+8613800138000"] } }
}编辑配置的 4 种方式
方式 1：交互向导
bash
openclaw onboard # 完整设置向导
openclaw configure # 配置向导方式 2：CLI 一行命令
bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey方式 3：控制面板 Web UI
访问 http://127.0.0.1:18789/，使用 Config 选项卡，支持表单编辑和原始 JSON 编辑器。
方式 4：直接编辑文件
Gateway 自动监听文件变化并热加载（大多数配置不需要重启）。
配置验证
OpenClaw 严格验证配置，不合法的配置会拒绝启动。
bash
openclaw doctor # 显示具体问题
openclaw doctor --fix # 尝试自动修复常用配置片段
配置模型
json
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-5",
"fallbacks": ["openai/gpt-5.2"]
},
"models": {
"anthropic/claude-sonnet-4-5": { "alias": "Sonnet" },
"openai/gpt-5.2": { "alias": "GPT" }
}
}
}
}agents.defaults.models 同时定义模型目录和 /model 命令的可选列表。
接入频道（通用模式）
json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123:abc",
"dmPolicy": "pairing",
"allowFrom": ["tg:123456789"]
}
}
}dmPolicy 可选值：pairing（默认）| allowlist | open | disabled
控制群聊 @提及
json
{
"agents": {
"list": [{
"id": "main",
"groupChat": {
"mentionPatterns": ["@openclaw", "openclaw"]
}
}]
},
"channels": {
"whatsapp": {
"groups": { "*": { "requireMention": true } }
}
}
}会话隔离
json
{
"session": {
"dmScope": "per-channel-peer",
"threadBindings": {
"enabled": true,
"idleHours": 24,
"maxAgeHours": 0
},
"reset": {
"mode": "daily",
"atHour": 4,
"idleMinutes": 120
}
}
}dmScope 选项：
main：所有 DM 共享一个会话（默认）per-peer：每个联系人独立会话per-channel-peer：多平台用户隔离（推荐多用户场景）per-account-channel-peer：最细粒度隔离
心跳（定时主动联系）
json
{
"agents": {
"defaults": {
"heartbeat": {
"every": "30m",
"target": "last"
}
}
}
}target 选项：last | whatsapp | telegram | discord | none
定时任务（Cron）
json
{
"cron": {
"enabled": true,
"maxConcurrentRuns": 2,
"sessionRetention": "24h",
"runLog": {
"maxBytes": "2mb",
"keepLines": 2000
}
}
}Webhooks
json
{
"hooks": {
"enabled": true,
"token": "shared-secret",
"path": "/hooks",
"defaultSessionKey": "hook:ingress",
"mappings": [{
"match": { "path": "gmail" },
"action": "agent",
"agentId": "main",
"deliver": true
}]
}
}Docker Agent 沙箱
json
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "agent"
}
}
}
}先运行 scripts/sandbox-setup.sh 构建沙箱镜像。
多 Agent 路由
json
{
"agents": {
"list": [
{ "id": "main", "workspace": "~/.openclaw/workspace-main" },
{ "id": "coding", "workspace": "~/.openclaw/workspace-coding", "model": "anthropic/claude-opus-4-6" }
]
},
"bindings": [
{ "agentId": "main", "match": { "channel": "whatsapp" } },
{ "agentId": "coding", "match": { "channel": "telegram" } }
]
}热加载 vs 需要重启
热加载（修改后自动生效）：
- 频道策略（allowlist、groupPolicy）
- 心跳间隔
- 消息设置
- 大多数 Agent 设置
需要重启：
- 频道连接（WhatsApp、Telegram Bot Token）
- 沙箱模式变更
- 底层网络配置
bash
openclaw gateway restart配置 RPC（程序化更新）
Gateway 支持通过 WebSocket API 程序化更新配置，无需重启：
json
// 发送更新请求
{ "type": "req", "id": "123", "method": "config.set", "params": { "path": "agents.defaults.heartbeat.every", "value": "1h" } }完整配置参考
所有可用配置项：Configuration Reference
完整配置示例：Configuration Examples
原文：Configuration - OpenClaw | 来源：OpenClaw 官方文档