OpenClaw 的所有行为，都由一个文件控制：~/.openclaw/openclaw.json。
很多新手在引导向导（openclaw onboard）完成后就停了，觉得能跑起来就够了。但如果你想真正发挥 OpenClaw 的能力——切换模型、限定谁能发消息、配置定时任务、调整 Heartbeat 频率——就必须读懂这个配置文件。
本文逐模块拆解 openclaw.json 的核心参数，每个参数都解释”是什么”和”为什么这么设”，并附上可直接使用的配置示例。
配置文件的位置和基本结构
配置文件路径：
~/.openclaw/openclaw.jsonDocker 容器内路径：
/app/data/openclaw.json整个 ~/.openclaw/ 目录的结构如下：
~/.openclaw/
├── openclaw.json # 主配置文件（本文重点）
├── credentials/ # API 密钥（权限应设为 600）
│ ├── anthropic
│ └── openai
└── workspace/ # 工作区（Agent 的"家"）
├── SOUL.md # Agent 人格定义
├── USER.md # 用户信息
├── HEARTBEAT.md # 心跳任务清单
├── TOOLS.md # 工具权限配置
└── memory/ # 长期记忆文件配置文件使用 JSON5 格式（兼容标准 JSON，但支持注释），有几条重要规则：
- OpenClaw 对 Schema 严格校验——未知字段、类型错误、缺少必填项都会导致 Gateway 拒绝启动
- 修改配置文件后，部分更改会热重载生效，但多数需要运行
openclaw gateway restart - 优先级顺序：环境变量 > 配置文件 > 默认值
三种修改配置的方式
在深入参数之前，先说清楚改配置的三种途径：
方式一：CLI 命令（推荐）
最安全的方式，自动校验语法，不会引入 JSON 格式错误：
# 读取配置
openclaw config get agents.defaults.model
# 设置配置
openclaw config set gateway.mode "local"
# 删除配置项
openclaw config unset channels.telegram.botToken方式二：直接编辑 JSON 文件
用任何文本编辑器打开 ~/.openclaw/openclaw.json 直接编辑。注意确保 JSON 语法正确，编辑完后用 openclaw doctor --fix 验证。
方式三：控制面板（Config 选项卡）
打开浏览器访问 http://127.0.0.1:18789，进入 Config 选项卡，界面化修改，适合不熟悉 JSON 的用户。
模块一：gateway — 网关核心设置
Gateway 模块控制 OpenClaw 的核心进程行为，是最关键的配置区块。
{
"gateway": {
"mode": "local", // 必填！local=仅本机访问，remote=允许外部访问
"host": "127.0.0.1", // 绑定地址，强烈建议保持 127.0.0.1
"port": 18789, // 监听端口，默认 18789
"auth": {
"mode": "token", // 认证方式：token 或 password
"token": "你的令牌" // 登录控制面板的凭证
}
}
}新手最常犯的错误：将 host 设为 0.0.0.0。这会把控制面板暴露在公网，是严重的安全漏洞。除非你明确知道自己在做什么，否则 host 永远保持 127.0.0.1。
关于 gateway.mode：这是一个必填项，缺少它 Gateway 会拒绝启动并报错 gateway start blocked。个人单机使用设为 "local"，服务器多用户部署设为 "remote"（同时必须配置严格的认证和防火墙）。
通过 CLI 快速设置：
openclaw config set gateway.mode "local"
openclaw config set gateway.host "127.0.0.1"模块二：agents — Agent 和模型配置
这个模块定义 AI Agent 的基本行为，包括使用哪个模型、工作区在哪里、心跳频率等。
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace", // 工作区路径
"model": {
"primary": "anthropic/claude-sonnet-4-6", // 主力模型
"fallbacks": [ // 备用模型（主力失败时自动切换）
"openai/gpt-5.2",
"deepseek/deepseek-chat"
]
},
"heartbeat": {
"every": "30m", // 心跳触发间隔（如 "30m"、"1h"、"900"秒）
"isolatedSession": true, // 每次心跳使用独立会话（大幅降低 Token 消耗）
"activeHours": "08:00-22:00" // 仅在此时间段内触发心跳
}
}
}
}关于模型命名格式：格式为 "提供商/模型名称"，例如：
anthropic/claude-sonnet-4-6（推荐日常使用，性价比最优）anthropic/claude-opus-4-6（性能最强，成本较高）openai/gpt-5.2deepseek/deepseek-chat（成本最低，中文支持好）
关于 fallbacks（备用模型）：强烈建议配置。当主力模型遇到限流（429错误）或服务不可用时，OpenClaw 会自动切换到备用模型继续工作，不会中断你的任务。
成本优化建议：不要把最贵的模型设为默认。推荐把 Sonnet 设为主力处理日常任务，只有在需要深度推理时才让 Opus 作为备用被调用。
模块三：channels — 通讯平台配置
这个模块控制 OpenClaw 连接哪些通讯平台，以及谁有权限给它发消息。
Telegram 配置示例
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456:ABC-你的BotToken",
"dmPolicy": "pairing", // pairing=配对验证 | allowlist=白名单 | open=开放
"allowFrom": ["tg:你的用户ID"] // 允许发消息的用户（allowlist 模式下）
}
}
}WhatsApp 配置示例
{
"channels": {
"whatsapp": {
"enabled": true,
"dmPolicy": "pairing",
"allowFrom": ["+8613800138000"], // 允许的手机号（E.164 格式）
"groupPolicy": "allowlist", // 群组消息策略
"ackReaction": {
"emoji": "👀", // 收到消息时的自动回应表情
"direct": true
}
}
}
}关于 dmPolicy（私信策略），这是最重要的安全参数之一：
"pairing"（推荐）：第一次发消息需要配对验证，防止陌生人控制你的 Agent"allowlist"：只有allowFrom列表中的用户才能发消息，最严格"open"：任何人都可以发消息，仅在完全受控的私有环境中使用
通过 CLI 快速配置 Telegram：
openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken "你的BotToken"
openclaw config set channels.telegram.dmPolicy "pairing"模块四：models — 模型提供商配置
这个模块配置各个 AI 模型提供商的连接信息，包括 API Key 和自定义端点。
{
"models": {
"providers": {
"anthropic": {
"apiKey": "sk-ant-你的密钥" // Anthropic API Key
},
"openai": {
"apiKey": "sk-你的密钥" // OpenAI API Key
},
"deepseek": {
"apiKey": "sk-你的密钥"
},
"local-ollama": { // 本地 Ollama 模型（API 费用为零）
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama",
"api": "openai-responses"
}
}
}
}安全建议：API Key 不要直接写在配置文件里，推荐用环境变量引用：
# 在 ~/.openclaw/openclaw.json 中使用环境变量
{
"models": {
"providers": {
"anthropic": {
"apiKey": "${ANTHROPIC_API_KEY}"
}
}
}
}然后在 shell 配置文件（~/.zshrc 或 ~/.bashrc）中设置：
export ANTHROPIC_API_KEY="sk-ant-你的密钥"这样 API Key 不会出现在配置文件中，即使配置文件意外泄露，密钥也是安全的。
模块五：cron — 定时任务配置
这个模块控制定时任务的全局行为（具体任务通过 openclaw cron add 添加）。
{
"cron": {
"enabled": true, // 是否启用定时任务
"maxConcurrentRuns": 2, // 同时执行的最大任务数
"sessionRetention": "24h", // 任务会话保留时间
"runLog": {
"maxBytes": "2mb", // 日志文件最大大小
"keepLines": 2000 // 保留的最大日志行数
}
}
}常用 Cron 任务配置（通过 CLI 添加，不写在 JSON 文件里）：
# 每天早上9点执行日报总结
openclaw cron add \
--name "morning-brief" \
--cron "0 9 * * *" \
--message "总结我的邮件和今日日程，用中文回复"
# 每小时检查一次优先事项
openclaw cron add \
--name "hourly-check" \
--every 3600000 \
--message "有什么需要我处理的优先事项吗？"
# 查看所有定时任务
openclaw cron list --all完整的最小可用配置示例
以下是一份覆盖核心功能的最小配置，适合新手参考：
{
"gateway": {
"mode": "local",
"host": "127.0.0.1",
"port": 18789
},
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace",
"model": {
"primary": "anthropic/claude-sonnet-4-6",
"fallbacks": ["deepseek/deepseek-chat"]
},
"heartbeat": {
"every": "30m",
"isolatedSession": true
}
}
},
"models": {
"providers": {
"anthropic": {
"apiKey": "${ANTHROPIC_API_KEY}"
},
"deepseek": {
"apiKey": "${DEEPSEEK_API_KEY}"
}
}
},
"channels": {
"telegram": {
"enabled": true,
"botToken": "${TELEGRAM_BOT_TOKEN}",
"dmPolicy": "pairing"
}
},
"cron": {
"enabled": true,
"maxConcurrentRuns": 2
}
}修改配置后的验证步骤
每次修改配置文件后，养成以下习惯：
# 第一步：验证配置语法和有效性
openclaw doctor --fix
# 第二步：重启 Gateway 使配置生效
openclaw gateway restart
# 第三步：确认运行状态正常
openclaw gateway status
# 第四步（定期执行）：安全审计
openclaw security audit --deep配置文件的权限安全
配置文件中包含 API Key、Bot Token 等敏感信息，务必设置正确的文件权限：
# 保护整个 .openclaw 目录（仅所有者可访问）
chmod 700 ~/.openclaw
# 保护主配置文件
chmod 600 ~/.openclaw/openclaw.json
# 保护 API 密钥目录
chmod 700 ~/.openclaw/credentials运行以下命令检查配置文件中是否有明文 API Key（这些应该通过环境变量引用，而不是直接写在文件里）：
grep -r "sk-" ~/.openclaw/openclaw.json如果有输出，建议将 Key 移到环境变量中管理。
总结：新手需要重点关注的参数
如果你是第一次接触 OpenClaw 配置文件，只需要重点掌握这几个参数就够用了：
gateway.mode：必填，设为"local"gateway.host：必须是"127.0.0.1"，不要改agents.defaults.model.primary：你的主力 AI 模型agents.defaults.model.fallbacks：备用模型列表，至少配置一个channels.*.dmPolicy：通讯平台的消息权限策略，建议用"pairing"agents.defaults.heartbeat.isolatedSession：设为true节省 Token
想查阅完整的配置参数参考，访问 OpenClaw官网中文版（通过浏览器翻译访问 openclaw.ai）或官方配置文档 docs.openclaw.ai/gateway/configuration。
本文内容基于 OpenClaw 官方文档、moltfounders.com、lumadock.com、clawtank.dev 等公开资料整理，信息截至2026年3月28日。