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

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

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

第一步：别怕，先找到它

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

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

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

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

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

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

{
  // 🤖 1. Agent 配置区（这是灵魂，管机器人怎么思考）
  "agents": { ... },

  // 🎨 2. 模型配置区（管用哪个脑子，GPT还是Kimi）
  "models": { ... },

  // 📱 3. 渠道配置区（管在哪聊天，WhatsApp/Telegram）
  "channels": { ... },

  // ⚙️ 4. 系统与工具区（管端口、会话、浏览器等）
  "gateway": { ... },
  "session": { ... },
  "browser": { ... }
}

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

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

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

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

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

"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"
    }
  }
}

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

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

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

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

"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"
        }
      ]
    }
  }
}

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

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

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

"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"
  }
}

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

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

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

"session": {
  // 会话作用域：如果是多用户，推荐 'per-channel-peer'，每个人有自己的聊天上下文 
  "dmScope": "per-channel-peer",

  // 重置策略：相当于让机器人“睡一觉就忘事” 
  "reset": {
    "mode": "daily",   // 每天重置一次
    "atHour": 4        // 凌晨4点清空记忆（适合不想让它记太多私事的场景）
  },

  // 线程绑定：Discord 等平台的线程管理 
  "threadBindings": {
    "enabled": true,
    "idleHours": 24    // 线程24小时没人说话就自动关闭
  }
}

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

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

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

   # 如果改了必须重启的配置
   systemctl --user restart openclaw-gateway
   # 或者
   openclaw gateway restart
   

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

   openclaw doctor --fix
   

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

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

   "allowFrom": [
       "+8613912345678", // 我自己 (2026.03.13 新增)
       // "+8613900000000" // 小张（暂时禁用，省点钱）
   ]
   

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

结语

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

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

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