OpenClaw 配置文件实战手册（最新版）：手把手教你搞定配置

OpenClaw 配置文件实战手册（最新版）：手把手教你搞定配置

这份是我结合官方更新和自己实操经验整理的配置手册，把 OpenClaw 2026.2.25 版本的核心配置参数拆得明明白白，新手照着配就能用，老用户也能查漏补缺。

文件路径：~/.openclaw/openclaw.json
文件格式：JSON5（比普通JSON友好太多——能加//注释、末尾能留逗号、甚至能用单引号，推荐用 VS Code 装个 JSON5 插件编辑，不报错）
生效方式：大部分参数改了不用重启 Gateway（热重载），但像gateway.port这种核心端口配置，必须重启才生效
备份提醒：改之前先复制一份原文件（比如cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak），避免改错回不去

1. 配置文件整体结构（先认框架，不迷路）

OpenClaw 的配置是分层的，核心就这几块，记好位置找参数更快：

{ // 🔥 最核心：控制Agent的行为（90%的优化都在这） "agents": { "defaults": { ... }, // 全局默认设置（日常用得最多） "list": [ ... ] // 进阶用：多Agent单独配置，覆盖全局默认 }, // 🤖 模型相关：对接Kimi/OpenAI/Claude这些模型 "models": { "providers": { ... } }, // 📱 聊天渠道：控制WhatsApp/Telegram谁能发消息 "channels": { ... }, // ⚙️ 其他辅助配置：端口、缓存、会话重置等 "gateway": { ... }, "session": { ... }, "cache": { ... }, "messages": { ... }, "tools": { ... } }

2. 核心参数详解（重点标红，新手先看这些）

1. agents.defaults（重中之重，全局默认配置）

这部分是控制 Token 消耗、Agent 行为的核心，我把常用参数整理成表格，备注都是自己实测的推荐值：

2. models.providers（对接Kimi 2.5的关键配置）

我只留了Kimi 2.5的配置（最常用），注释里加了自己踩过的坑：

"models": { "providers": { "moonshot": { "type": "moonshot", // 固定值，别改 "apiKey": "YOUR_MOONSHOT_KEY",// 替换成你的Kimi API密钥（在Moonshot控制台找） "baseUrl": "https://api.moonshot.ai/v1", // 香港/海外用.ai，大陆服务器换.cn "api": "openai-completions", // 固定值，适配OpenAI兼容接口 "models": [ { "id": "kimi-k2.5", // 模型ID，必须和Moonshot一致 "name": "Kimi K2.5", // 自定义名称，随便填 "contextWindow": 256000, // Kimi 2.5的最大上下文，别改 "maxTokens": 8192, // 单次输出最大Token，够用 "cost": { "input": 0.1, "output": 0.5 } // 计费标准，和Moonshot一致 } ] } } }

3. channels（聊天渠道安全配置，必配！）

别漏了这个，不然任何人都能通过WhatsApp调用你的Agent，花你的钱：

"channels": { "whatsapp": { // 只允许指定手机号发消息，填自己的号码（香港加+852，大陆加+86） "allowFrom": ["+85212345678"] } }

4. 其他常用顶级配置（偶尔会改）

我正在用的完整配置模板（直接复制改密钥就行）

这份是我优化后的最终版，省Token+安全+稳定，新手直接抄：

{ "agents": { "defaults": { "workspace": "~/.openclaw/workspace", "model": { "primary": "moonshot/kimi-k2.5" // 主力用Kimi 2.5 }, "models": { "moonshot/kimi-k2.5": { "alias": "Kimi K2.5 (官方)", "params": { "temperature": 0.2 // 低温度，省Token+少瞎编 } } }, "compaction": { "reserveTokensFloor": 20000, // 超过2万Token自动压缩 "memoryFlush": { "enabled": true, "softThresholdTokens": 4000, "systemPrompt": "Session nearing compaction. Store durable memories now.", "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store." } }, "heartbeat": { "every": "30m" // 空闲30分钟自动重置会话 } } }, "models": { "providers": { "moonshot": { "type": "moonshot", "apiKey": "替换成你的Kimi API密钥", // 👉 这里改自己的密钥 "baseUrl": "https://api.moonshot.ai/v1", // 香港用这个，大陆换.cn "api": "openai-completions", "models": [ { "id": "kimi-k2.5", "name": "Kimi K2.5", "contextWindow": 256000, "maxTokens": 8192, "cost": { "input": 0.1, "output": 0.5 } } ] } } }, "channels": { "whatsapp": { "allowFrom": ["替换成你的手机号"] // 👉 这里改自己的手机号 } }, // 可选：每日固定重置，和空闲重置双保险 "session": { "reset": { "dailyTime": "04:00" } }, // 可选：缓存1小时，重复查询省Token "cache": { "ttl": "1h" } }

配置完必做的3件事（验证+生效）

1. 校验配置是否正确：
   执行openclaw doctor --fix，会自动检查语法错误并修复，比自己查快多了。
2. 重启Gateway（改核心配置后必做）：
   • 本地运行：直接关了重新输openclaw gateway
   • 服务器运行（systemd）：systemctl restart openclaw-gateway.service
3. 验证配置是否生效：
   在聊天窗口发命令：
   • /status：看temperature是不是0.2、heartbeat是不是30m
   • /usage：看Token消耗统计，确认模型是Kimi 2.5

总结

1. OpenClaw 配置的核心是agents.defaults，重点调temperature（0.2）、heartbeat（30m）、compaction（20000）这三个参数，能省80%的Token；
2. models.providers里的API密钥和域名要对应（香港.ai/大陆.cn），避免调用失败；
3. 一定要配置channels.whatsapp.allowFrom，防止别人滥用你的Agent产生高额费用。