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 行为的核心，我把常用参数整理成表格，备注都是自己实测的推荐值：

参数路径	类型	默认值	我的说明 & 推荐值
workspace	string	~/.openclaw/workspace	Agent的工作目录，默认就行，不用改
model.primary	string/object	null	主模型，填"moonshot/kimi-k2.5"就行；进阶可配 fallback（比如Kimi挂了自动切GPT）
temperature	number	1.0	全局温度：推荐设0.2！亲测能减少模型瞎编，降低重试次数，直接省Token
compaction.reserveTokensFloor	number	24000	自动压缩阈值：超过这个Token数就压缩历史上下文，推荐20000（适配Kimi 2.5的上下文）
compaction.memoryFlush.enabled	boolean	true	记忆刷新：开启后会把关键信息存到文件，清空冗余上下文，必开！
compaction.memoryFlush.softThresholdTokens	number	6000	软阈值：快到压缩点时先存记忆，推荐4000（更早清理，更省Token）
heartbeat.every	string	“30m”	空闲重置：“30m”（30分钟没消息自动开新会话），省Token的核心配置；禁用填"0m"
timeoutSeconds	number	600	单次请求超时：默认10分钟，够用，不用改
contextTokens	number	200000	最大上下文窗口：Kimi 2.5支持256000，改不改都行
sandbox.mode	string	“non-main”	沙箱模式：推荐保持non-main，避免误操作本地文件

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. 其他常用顶级配置（偶尔会改）

配置键	说明 & 推荐值
gateway.port	Gateway监听端口，默认18789，不用改（改了要重启）
session.reset.dailyTime	每日固定重置时间，比如"04:00"（凌晨4点），和heartbeat配合用
cache.ttl	缓存有效期，默认"1h"（1小时），重复查询能省Token
tools.allow	工具白名单：比如只允许"file.read"，避免Agent乱删文件

---

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

这份是我优化后的最终版，省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产生高额费用。