OpenClaw 配置详解：掌控你的 AI 助手
本教程属于《OpenClaw 从入门到精通》系列
在前面的文章中，我们已经学习了本地部署、Docker 部署和云服务器部署。本文将深入讲解 OpenClaw 的配置文件，帮助你全面掌控你的 AI 助手。
📁 配置文件位置
OpenClaw 的配置文件位于：
~/.openclaw/openclaw.json
OpenClaw 使用 JSON5 格式，这意味着：
- ✅ 支持注释（
//或/* */） - ✅ 支持尾随逗号
- ✅ 更宽松的语法
如果配置文件不存在，OpenClaw 会使用安全的默认配置。
🛠️ 配置方法
方法一：交互式向导（推荐新手）
# 完整设置向导
openclaw onboard
# 配置向导
openclaw configure
方法二：CLI 命令
# 获取配置值
openclaw config get agents.defaults.workspace
# 设置配置值
openclaw config set agents.defaults.heartbeat.every "2h"
# 删除配置
openclaw config unset tools.web.search.apiKey
方法三：控制 UI
打开 http://127.0.0.1:18789，使用 Config 标签页。
方法四：直接编辑
直接编辑 ~/.openclaw/openclaw.json，OpenClaw 会自动监视文件变化并热加载配置。
📋 核心配置项
最小配置示例
// ~/.openclaw/openclaw.json
{
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
完整配置结构
{
// 网关设置
gateway: {
port: 18789,
reload: { mode: "hybrid", debounceMs: 300 }
},
// Agent 配置
agents: {
defaults: {
model: { primary: "anthropic/claude-sonnet-4-5" },
workspace: "~/.openclaw/workspace",
heartbeat: { every: "30m", target: "last" }
}
},
// 消息渠道
channels: {
telegram: { enabled: true, botToken: "xxx" },
whatsapp: { enabled: true }
},
// 定时任务
cron: { enabled: true, maxConcurrentRuns: 2 },
// Webhook
hooks: { enabled: true, token: "secret" }
}
💬 消息渠道配置
Telegram
{
channels: {
telegram: {
enabled: true,
botToken: "123:ABCDEF",
dmPolicy: "pairing",
allowFrom: ["tg:123456789"]
}
}
}
dmPolicy 选项：
pairing：未知发送者需配对码验证allowlist：仅允许列表中的用户open：允许所有私信disabled：禁用私信
{
channels: {
whatsapp: {
enabled: true,
dmPolicy: "pairing",
allowFrom: ["*"]
}
}
}
Discord
{
channels: {
discord: {
enabled: true,
botToken: "xxx",
dmPolicy: "pairing",
groupPolicy: "mention",
groupAllowFrom: ["*"]
}
}
}
🤖 模型配置
设置主模型和备用模型
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: ["openai/gpt-4o"]
},
models: {
"anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
"openai/gpt-4o": { alias: "GPT" }
}
}
}
}
本地模型配置
{
models: {
providers: {
llama: {
type: "llama",
apiKey: "not-needed",
baseURL: "http://localhost:11434/v1"
}
}
}
}
❤️ 心跳配置
心跳功能让 OpenClaw 定期主动联系你：
{
agents: {
defaults: {
heartbeat: {
every: "30m", // 检查间隔
target: "last" // 发送目标：last | whatsapp | telegram | discord | none
}
}
}
}
配置说明：
every：时间间隔（如30m、2h、1d）target：上次互动的渠道，或指定渠道- 设置
"0m"可禁用心跳
⏰ 定时任务配置
{
cron: {
enabled: true,
maxConcurrentRuns: 2,
sessionRetention: "24h",
runLog: {
maxBytes: "2mb",
keepLines: 2000
}
}
}
创建定时任务
openclaw cron add --name "daily-digest" --schedule "0 9 * * *" --agent main --prompt "总结昨天的重要事件"
🔗 Webhook 配置
{
hooks: {
enabled: true,
token: "your-shared-secret",
path: "/hooks",
defaultSessionKey: "hook:ingress",
allowRequestSessionKey: false,
allowedSessionKeyPrefixes: ["hook:"],
mappings: [
{
match: { path: "gmail" },
action: "agent",
agentId: "main",
deliver: true
}
]
}
}
🔐 安全配置
严格验证
OpenClaw 只接受完全符合 schema 的配置：
- ❌ 未知字段会导致启动失败
- ❌ 类型错误会拒绝配置
- ❌ 使用
openclaw doctor查看具体问题
秘密管理
{
env: {
vars: {
OPENROUTER_API_KEY: "sk-or-..."
}
}
}
或使用 SecretRef：
{
models: {
providers: {
openai: {
apiKey: {
source: "env",
provider: "default",
id: "OPENAI_API_KEY"
}
}
}
}
}
🔄 热加载
OpenClaw 支持配置文件热加载，无需重启即可应用大部分配置变更。
加载模式
| 模式 | 行为 |
|---|---|
hybrid（默认） |
安全变更即时生效，关键变更自动重启 |
hot |
仅热加载安全变更，需要手动处理重启 |
restart |
任何变更都重启网关 |
off |
禁用监视，下次手动重启生效 |
{
gateway: {
reload: { mode: "hybrid", debounceMs: 300 }
}
}
📊 会话配置
{
session: {
dmScope: "per-channel-peer",
threadBindings: {
enabled: true,
ttlHours: 24
},
reset: {
mode: "daily",
atHour: 4,
idleMinutes: 120
}
}
}
🖥️ 沙箱配置
为安全起见，可在隔离的 Docker 容器中运行 Agent：
{
agents: {
defaults: {
sandbox: {
mode: "non-main",
scope: "agent"
}
}
}
}
⚠️ 需要先运行
scripts/sandbox-setup.sh构建沙箱镜像
📂 配置文件分割
可以使用 $include 将大配置拆分：
// ~/.openclaw/openclaw.json
{
gateway: { port: 18789 },
agents: { $include: "./agents.json5" },
channels: { $include: ["./telegram.json5", "./whatsapp.json5"] }
}
🩺 配置诊断
检查配置问题
# 诊断配置错误
openclaw doctor
# 自动修复
openclaw doctor --fix
查看配置
# 获取当前配置
openclaw gateway call config.get --params '{}'
✅ 验证清单
配置完成后，请确认：
- 配置文件语法正确（JSON5 格式）
- 消息渠道可以正常连接
- 模型配置正确，可以正常调用
- 心跳功能正常工作（如已配置）
- 运行
openclaw doctor无报错
📞 下一步
配置详解完成后，你可以继续学习：
📚 参考资料
本教程由 AI 自动生成并发布