OpenClaw 的所有行为都通过一个核心配置文件控制：~/.openclaw/openclaw.json。
本文提供完整字段说明和可直接复制的配置模板。
配置文件基础
位置与格式
文件路径：~/.openclaw/openclaw.json
格式：JSON5（支持注释！普通 JSON 也兼容）
JSON5 的优势：可以写注释（// 和 /* */），方便记录配置目的。
json5
// ~/.openclaw/openclaw.json
{
// 这是一条注释，JSON5 支持！
channels: {
telegram: {
token: "你的Bot Token", // BotFather 给的
allowFrom: ["12345678"], // 允许的用户 ID 列表
}
}
}编辑方式
bash
# 方式 1：交互式向导（推荐新手）
openclaw configure
# 方式 2：命令行直接设置
openclaw config set channels.telegram.token "你的token"
openclaw config get agents.defaults.workspace
# 方式 3：直接编辑文件
nano ~/.openclaw/openclaw.json
# 方式 4：Dashboard UI（浏览器）
openclaw dashboard # 打开后找 Config 标签热重载（无需重启）
修改 openclaw.json 后，Gateway 会自动检测并应用大部分配置变更，
无需手动重启。例外：新频道连接、模型切换需重启。
bash
# 手动触发重载（或有些场景需要）
openclaw gateway reload
# 验证配置是否有效（变更前先检查）
openclaw config validate完整配置字段说明
频道配置（channels）
json5
{
channels: {
// ── Telegram ──
telegram: {
token: "1234567890:AAFxxx", // 必填，BotFather 生成
allowFrom: ["123456789"], // 允许的用户 ID（数字字符串）
allowFromUsernames: ["alice"], // 允许的用户名（不含@）
groups: {
"*": { requireMention: true } // 群组里必须 @Bot 才响应
}
},
// ── Discord ──
discord: {
token: "Bot Token",
allowedGuilds: ["服务器ID"],
allowedChannels: ["频道ID"],
mentionRequired: true,
},
// ── WhatsApp ──
whatsapp: {
allowFrom: ["+8613800000000"], // E.164 格式手机号
groups: {
"群组名称": { requireMention: true }
}
},
// ── Slack ──
slack: {
botToken: "xoxb-xxx",
appToken: "xapp-xxx",
allowedUsers: ["U01234"],
},
}
}AI 代理配置（agents）
json5
{
agents: {
defaults: {
// 工作区目录（SOUL.md、MEMORY.md 等存放位置）
workspace: "~/.openclaw/workspace-content",
// 默认 AI 模型
model: "claude-sonnet-4-5",
// 心跳任务（定期自动执行）
heartbeat: {
enabled: true,
every: "30m", // 每 30 分钟触发一次
prompt: "Read HEARTBEAT.md if it exists. If nothing needs attention, reply HEARTBEAT_OK."
},
// 会话压缩（长对话自动压缩节省 Token）
session: {
compression: {
enabled: true,
triggerTokens: 80000, // 超过 80K tokens 触发压缩
}
}
}
}
}工具开关（tools）
json5
{
tools: {
// 浏览器工具（Playwright 网页自动化）
browser: {
enabled: true,
sandbox: true,
},
// 命令执行工具
exec: {
enabled: true,
sandbox: "docker", // 在 Docker 中隔离执行
allowedCommands: ["git", "npm", "python3"],
},
// 网络搜索工具
web: {
enabled: true,
search: {
provider: "brave",
apiKey: "BSA_xxx", // Brave Search API Key
}
},
// TTS（文字转语音）
tts: {
enabled: true,
provider: "elevenlabs",
apiKey: "EL_xxx",
}
}
}Cron 定时任务（cron）
json5
{
cron: {
jobs: [
{
id: "morning-briefing",
schedule: "0 8 * * 1-5", // 周一到周五 8:00
task: "给我发早报：今日天气 + 日历事项 + 重要邮件摘要"
},
{
id: "weekly-summary",
schedule: "0 18 * * 5", // 周五 18:00
task: "总结本周工作进展，发送到 Telegram"
}
]
}
}完整生产配置模板
以下是一个完整的个人使用配置，可直接复制修改：
json5
// ~/.openclaw/openclaw.json（生产级个人配置）
{
// AI 代理设置
agents: {
defaults: {
workspace: "~/.openclaw/workspace-content",
model: "claude-sonnet-4-5",
heartbeat: {
enabled: true,
every: "30m",
},
session: {
compression: { enabled: true, triggerTokens: 80000 }
}
}
},
// 频道：只开启 Telegram
channels: {
telegram: {
token: "你的Bot Token",
allowFrom: ["你的Telegram用户ID"],
}
},
// 工具
tools: {
browser: { enabled: true },
exec: { enabled: true },
web: {
enabled: true,
search: { provider: "brave", apiKey: "你的Brave API Key" }
}
},
// 日志
logging: {
level: "info",
}
}配置验证与诊断
bash
# 检查配置文件语法和字段有效性
openclaw config validate
# 全面诊断（推荐每次重大变更后运行）
openclaw doctor
# 常见 doctor 输出说明：
# ✅ Config valid — 配置文件语法正确
# ✅ Telegram connected — Telegram Bot 正常连接
# ⚠️ No AI provider found — 未配置 API Key，需要设置
# ❌ Workspace not found — 工作区目录不存在，需要创建来源：OpenClaw 官方文档 - docs.openclaw.ai/gateway/configuration