从“会用”到“会改”：第一次打开OpenClaw配置文件，这些参数都是什么意思？

如果你已经顺利跑起了 OpenClaw，看着终端里那个能跟你聊天、帮你查资料的 AI 机器人，心里肯定挺有成就感。但我知道，过不了几天你就会手痒——那个躺在 ~/.openclaw/openclaw.json 里的配置文件，就像新车的引擎盖，总想打开看看里面到底藏了什么。

我第一次打开这个文件的时候，也是一脸懵：这密密麻麻的字段都是干嘛的？改坏了会不会炸？今天，我就带你逐层拆解这个配置文件。我们的目标不仅是“会用”，更是“会改”，让它真正变成趁手的工具。

第一步：别怕，先找到它

不管你是在 Docker 里跑的，还是一键脚本装的，OpenClaw 的“大脑”通常都藏在这里（这是默认路径，绝大部分情况适用）：

• Linux/macOS：~/.openclaw/openclaw.json

直接用 VS Code 打开最好，因为它支持 JSON5 格式。看不懂？没关系，你只需要知道 JSON5 比普通 JSON 友好得多：你可以写注释（//），可以在最后一项后面加逗号，甚至可以用单引号 。这对于我们这种“试错型”选手太重要了，注释就是我们的操作手册。

整体框架：别被吓到，只有几大块

别被几十行甚至上百行的代码吓住。OpenClaw 的配置虽然细，但结构非常清晰，就像一个三居室的房子，每个房间管不同的事。

我把最外层的结构拆解给你看：

<pre data-tool="mdnice编辑器" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;">{ // 🤖 1\. Agent 配置区（这是灵魂，管机器人怎么思考） "agents": { ... }, // 🎨 2\. 模型配置区（管用哪个脑子，GPT还是Kimi） "models": { ... }, // 📱 3\. 渠道配置区（管在哪聊天，WhatsApp/Telegram） "channels": { ... }, // ⚙️ 4\. 系统与工具区（管端口、会话、浏览器等） "gateway": { ... }, "session": { ... }, "browser": { ... } } </pre>

看着有点多？放心，平时我们 90% 的时间，其实只盯着前两块折腾。

核心拆解：这些参数到底什么意思？

下面我们挑几个新手最容易接触、也是收益最高的参数，掰开揉碎了讲。

1. agents.defaults：机器人的“出厂设置”

这是整个配置文件的重中之重。你在聊天框里问的每一句话，都由这里面的规则控制。

<pre data-tool="mdnice编辑器" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;">"agents": { "defaults": { // 工作目录：机器人放东西的地方，一般保持默认就行 "workspace": "~/.openclaw/workspace", // 模型：这是它的脑子 "model": { "primary": "anthropic/claude-sonnet-4-5", // 主模型，OpenClaw 不内置模型，全靠对接 "fallbacks": ["openai/gpt-5.2"] // 备用：主模型跪了，自动切这个 }, // 温度（temperature）：这玩意儿非常玄学，数值越高越“发疯” // 我踩过的坑：设成1.0，让它写个总结，它硬是给我写了一首诗... // 现在老实了，日常用设 0.2，逻辑严谨，特别省钱（减少无意义 Token 消耗） "temperature": 0.2, // 心跳：让机器人定期在后台干活，比如每隔 30 分钟检查一次邮件 "heartbeat": { "every": "30m", "target": "last" // 把结果发回最后聊天的窗口 }, // 沙箱（Sandbox）：安全隔离的关键！ // 新手推荐 'non-main'，让非核心任务在隔离环境跑，防止它乱删你电脑文件 "sandbox": { "mode": "non-main" } } } </pre>

为什么这么改？我一个朋友没配 temperature，让它写周报，结果每次输出都带着强烈的“哲学思辨”，差点被老板约谈。调低这个值，能让它更“听话”。

2. models.providers：给机器人换脑子

OpenClaw 本身没脑子（模型），全靠对接外部的 API，比如 OpenAI、Claude，或者国内的 Kimi、DeepSeek。

这里有个常见的坑，尤其是用国内服务商的时候 ：

<pre data-tool="mdnice编辑器" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;">"models": { "providers": { // 以接入硅基流动（SiliconFlow）为例 "siliconflow": { "baseUrl": "https://api.siliconflow.cn/v1", // 注意结尾必须有 /v1 "apiKey": "sk-你的密钥", // 这玩意儿别分享出去 "api": "openai-completions", // 兼容模式 "models": [ { "id": "deepseek-ai/DeepSeek-V3", // 模型ID得一字不差 "name": "DeepSeek-V3" } ] } } } </pre>

实战经验：很多人复制网上的配置死活跑不通，90%是因为 baseUrl 结尾没加 /v1，或者模型 ID 复制多了空格。还有，apiKey 一定要填对，我第一次就把 sk- 前缀给漏了，排查了一下午。

3. channels：这是你的“钱袋子”！

这部分容易被忽略，但极其重要。如果不配好 allowFrom，任何知道你机器人号码的人都能调用它，产生的 API 费用可都记你账上！

<pre data-tool="mdnice编辑器" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;">"channels": { "whatsapp": { // 重点来了：白名单！只允许这几个号码私聊机器人 // 格式要带国家码，大陆是 +86，香港是 +852 "allowFrom": ["+8613912345678", "+85298765432"], // 群组策略：强烈建议设 true，不然群里@所有人，机器人都会响应 "groups": { "*": { "requireMention": true } // 必须提到机器人才回复 }, "dmPolicy": "pairing" // 新用户发消息，需要配对码确认，防止骚扰 }, "telegram": { "enabled": true, "botToken": "123456:ABC-DEF1234", // BotFather 给你的 // 国内用户必备：代理 "proxy": "socks5://127.0.0.1:7890" } } </pre>

血的教训：有次我测试完忘了关 allowFrom，把我另一个测试号加进去。结果第二天收到账单提醒，原来是测试号被某个爬虫扫到了，疯狂问问题。从那以后，我不仅配了 allowFrom，还把 dmPolicy 改成了 pairing，双重保险。

4. session：机器人的“记忆力”

这个节点控制机器人能记多久、记多少。

<pre data-tool="mdnice编辑器" style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;">"session": { // 会话作用域：如果是多用户，推荐 'per-channel-peer'，每个人有自己的聊天上下文 "dmScope": "per-channel-peer", // 重置策略：相当于让机器人“睡一觉就忘事” "reset": { "mode": "daily", // 每天重置一次 "atHour": 4 // 凌晨4点清空记忆（适合不想让它记太多私事的场景） }, // 线程绑定：Discord 等平台的线程管理 "threadBindings": { "enabled": true, "idleHours": 24 // 线程24小时没人说话就自动关闭 } } </pre>

实操中你必须知道的“潜规则”

改完配置，别急着高兴。有几个实操细节能让你少掉点头发：

1. 热重载 vs 重启：OpenClaw 有个很爽的功能叫“热重载”。改完配置一保存，大部分设置（如改模型、调温度）立刻生效，不用重启服务 。但如果你改了 gateway.port（端口）或者 gateway.reload 本身，不好意思，必须重启 。命令在此：

   <pre style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;"># 如果改了必须重启的配置 systemctl --user restart openclaw-gateway # 或者 openclaw gateway restart </pre>

2. 万能救命稻草： 如果你改完配置，机器人起不来了，或者报一些看不懂的错。别慌，OpenClaw 内置了“医生” ：

   <pre style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;">openclaw doctor --fix </pre>

   这行命令会自动检测语法错误、路径错误，甚至能帮你备份并修复配置文件。我在升级版本后必跑一次，稳得很。

3. 注释是你的好习惯： 在 JSON5 里，你可以尽情写注释。比如：

   <pre style="-webkit-tap-highlight-color: rgba(0, 0, 0, 0); margin: 10px 0px; padding: 0px; outline: 0px; max-width: 100%; box-sizing: border-box !important; overflow-wrap: break-word !important; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.55) 0px 2px 10px; text-align: left;">"allowFrom": [ "+8613912345678", // 我自己 (2026.03.13 新增) // "+8613900000000" // 小张（暂时禁用，省点钱） ] </pre>

   一个月后你再回来看，绝对感谢当时写注释的自己。

结语

打开配置文件，其实就像打开了一扇通往“自定义世界”的大门。别看它参数多，绝大多数都是“一次配置，终身受益”。从今天起，不要再满足于“能用”，试着去“改改”。

哪怕改错了也没关系，只要记得备份原文件（cp openclaw.json openclaw.json.bak），或者直接用 doctor --fix 拉你一把，OpenClaw 远比你想象的更耐造。

去试试把 temperature 调到 0.5，或者把默认模型换成最新的试试，你会发现一个更懂你的 AI 助手。

关于我们

霍格沃兹测试开发学社，隶属于 测吧（北京）科技有限公司，是一个面向软件测试爱好者的技术交流社区。

学社围绕现代软件测试工程体系展开，内容涵盖软件测试入门、自动化测试、性能测试、接口测试、测试开发、全栈测试，以及人工智能测试与 AI 在测试工程中的应用实践。

我们关注测试工程能力的系统化建设，包括 Python 自动化测试、Java 自动化测试、Web 与 App 自动化、持续集成与质量体系建设，同时探索 AI 驱动的测试设计、用例生成、自动化执行与质量分析方法，沉淀可复用、可落地的测试开发工程经验。

在技术社区与工程实践之外，学社还参与测试工程人才培养体系建设，面向高校提供测试实训平台与实践支持，组织开展 “火焰杯” 软件测试相关技术赛事，并探索以能力为导向的人才培养模式，包括高校学员先学习、就业后付款的实践路径。

同时，学社结合真实行业需求，为在职测试工程师与高潜学员提供名企大厂 1v1 私教服务，用于个性化能力提升与工程实践指导。