OpenClaw配置文件详解：openclaw.json逐行解读

逐行解释每个配置项的含义，让你彻底理解 OpenClaw 的配置逻辑。

一、meta 元数据

json

"meta": {
  "lastTouchedVersion": "2026.3.13",
  "lastTouchedAt": "2026-03-19T08:28:54.283Z"
}

字段	含义
lastTouchedVersion	最后一次操作 OpenClaw 的版本号
lastTouchedAt	最后一次操作的时间戳（ISO 8601 格式）

说明：这是 OpenClaw 自动维护的元数据，记录你最后一次使用 OpenClaw 的版本和时间。一般不需要手动修改。

二、wizard 向导

json

"wizard": {
  "lastRunAt": "2026-03-19T08:28:54.230Z",
  "lastRunVersion": "2026.3.13",
  "lastRunCommand": "onboard",
  "lastRunMode": "local"
}

字段	含义
lastRunAt	最后一次运行向导的时间
lastRunVersion	运行向导时的 OpenClaw 版本
lastRunCommand	最后运行的命令（onboard = 初始安装向导）
lastRunMode	运行模式（local = 本地模式）

说明：记录 OpenClaw 初始化向导的运行状态。onboard 表示你已完成初始配置。

三、browser 浏览器控制

json

"browser": {
  "enabled": true,
  "remoteCdpTimeoutMs": 10000,
  "remoteCdpHandshakeTimeoutMs": 15000,
  "defaultProfile": "windows",
  "profiles": {
    "windows": {
      "cdpUrl": "http://127.0.0.1:9222",
      "color": "#00AA00"
    }
  }
}

字段	含义
enabled	是否启用浏览器控制功能
remoteCdpTimeoutMs	CDP 连接超时时间（毫秒），10秒
remoteCdpHandshakeTimeoutMs	CDP 握手超时时间（毫秒），15秒
defaultProfile	默认使用的浏览器配置名
profiles	浏览器配置列表

profiles 子配置：

字段	含义
cdpUrl	Chrome DevTools Protocol 地址，9222 是 Chrome 远程调试端口
color	在 UI 中显示的颜色标识

说明：这是 OpenClaw 控制浏览器的核心配置。CDP（Chrome DevTools Protocol）让 OpenClaw 能像人一样操作浏览器。要在 Windows 上启用此功能：

bash

chrome.exe --remote-debugging-port=9222

四、models 模型配置

4.1 models.mode: "merge" 的含义

json

"models": {
  "mode": "merge",
  "providers": { ... }
}

merge 的含义：你写的配置 + OpenClaw 默认配置 = 最终生效的配置

默认配置（内置）     +     你的配置     =     最终生效
├─ anthropic              ├─ moonshot        ├─ anthropic（保留）
├─ openai                 └─ aliyun          ├─ openai（保留）
└─ ...                                      ├─ moonshot（新增）
                                             └─ aliyun（新增）

mode	效果
merge	你的配置 + 默认配置（推荐）
replace	只用你的配置，默认配置全部丢弃

什么时候用 replace：完全不想让 OpenClaw 用默认模型，要完全控制所有可用模型。

4.2 providers：AI 模型提供商列表

moonshot 提供商（月之暗面/Kimi）

json

"moonshot": {
  "baseUrl": "https://api.moonshot.cn/v1",
  "apiKey": "sk-WJj*******UoDU8cZsI",
  "api": "openai-completions",
  "models": [
    { "id": "moonshot-v1-8k", "name": "Kimi Chat (8k)" },
    { "id": "moonshot-v1-32k", "name": "Kimi Chat (32k)" },
    { "id": "moonshot-v1-128k", "name": "Kimi Chat (128k)" }
  ]
}

字段	含义
baseUrl	API 地址
apiKey	API 密钥（敏感信息，不要泄露）
api	API 协议类型（openai-completions = OpenAI 兼容格式）
models	可用模型列表
id	模型 ID（调用时使用）
name	模型显示名称

模型说明：8k/32k/128k = 上下文窗口大小，数字越大能处理的文本越长。

aliyun 提供商（阿里云百炼）

json

"aliyun": {
  "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
  "apiKey": "sk-sp-...",
  "api": "openai-completions",
  "models": [
    {
      "id": "glm-5",
      "name": "GLM-5 (阿里云百炼Coding Plan)",
      "reasoning": false,
      "input": ["text"],
      "cost": { "input": 0, "output": 0 },
      "contextWindow": 200000,
      "maxTokens": 8192
    }
  ]
}

字段	含义
reasoning	是否支持推理模式（思维链）
input	支持的输入类型（text = 文本）
cost	成本配置（这里是 0，说明是免费套餐）
contextWindow	上下文窗口大小（20万 token）
maxTokens	最大输出 token 数（8192）

五、agents 智能体配置

json

"agents": {
  "defaults": {
    "model": {
      "primary": "aliyun/glm-5",
      "fallbacks": ["aliyun/kimi-k2.5", "aliyun/MiniMax-M2.5"]
    },
    "workspace": "/home/.openclaw/workspace",
    "compaction": {
      "mode": "safeguard",
      "reserveTokensFloor": 20000
    },
    "heartbeat": {
      "every": "1h",
      "activeHours": { "start": "08:30", "end": "23:00" },
      "target": "last"
    },
    "maxConcurrent": 4,
    "subagents": { "maxConcurrent": 8 }
  }
}

5.1 model 模型选择

字段	含义
primary	首选模型（aliyun/glm-5）
fallbacks	备用模型列表（主模型失败时依次尝试）

说明：当前首选 GLM-5，如果挂了会自动切换到 Kimi K2.5 或 MiniMax M2.5。

5.2 workspace 工作目录

所有文件操作默认在这个目录下进行。

5.3 compaction 压缩配置

json

"compaction": {
  "mode": "safeguard",
  "reserveTokensFloor": 20000
}

背景知识：当对话太长，超出模型的上下文窗口时，OpenClaw 需要「压缩」历史消息——把旧对话总结成摘要，保留最近的对话，腾出空间继续聊天。

mode	含义	使用场景
default	标准压缩，一次性总结	对话历史不太长
safeguard	分块压缩，超长历史也能处理	长对话、复杂任务（推荐）

reserveTokensFloor 推荐值：

值	场景
10000	简单聊天，对话短
20000	默认值，适合大多数场景
30000+	复杂任务，需要大空间

5.4 heartbeat 心跳

字段	含义
every	心跳间隔（1小时）
activeHours.start	活跃时间开始（08:30）
activeHours.end	活跃时间结束（23:00）
target	心跳目标（last = 最后一个活跃会话）

说明：心跳功能让 OpenClaw 每隔 1 小时主动检查是否有任务，只在 08:30-23:00 期间活跃。

5.5 maxConcurrent 并发限制

json

"maxConcurrent": 4,
"subagents": { "maxConcurrent": 8 }

字段	含义
maxConcurrent	主会话最大并发数（4）
subagents.maxConcurrent	子代理最大并发数（8）

通俗解释：同时处理多少个任务。第 5 个请求会排队等待，避免电脑卡死、API 限流。

六、tools.profile 配置

json

"tools": {
  "profile": "coding"
}

profile 决定了 OpenClaw 能用哪些工具。

profile	可用工具	适用场景
minimal	只有 session_status	只能看状态，不能做任何事
coding	文件操作、终端、会话、记忆、图片	开发工作、日常工作（推荐）
messaging	消息发送、会话列表	只聊天，不能操作文件
full	所有工具	不限制（有安全风险）

工具组对照表：

工具组	包含工具	coding	full
group:fs	read, write, edit, apply_patch	✅	✅
group:runtime	exec, bash, process	✅	✅
group:sessions	sessions_list, sessions_history...	✅	✅
group:memory	memory_search, memory_get	✅	✅
image	图片分析	✅	✅
group:web	web_search, web_fetch	✅	✅
group:ui	browser, canvas	❌	✅
group:automation	cron, gateway	❌	✅
group:messaging	message	❌	✅
group:nodes	nodes	❌	✅

七、messages 消息配置

json

"messages": {
  "ackReactionScope": "group-mentions"
}

字段	含义
ackReactionScope	消息确认反应范围（group-mentions = 群聊中只有 @ 时才反应）

说明：避免在群聊中刷屏，只有被 @ 时才会触发反应。

八、commands 命令配置

json

"commands": {
  "native": "auto",
  "nativeSkills": "auto",
  "restart": true,
  "ownerDisplay": "raw"
}

字段	值	含义
native	"auto"	自动检测是否支持原生命令（如 /status）
nativeSkills	"auto"	自动检测是否支持原生技能命令
restart	true	允许远程重启 Gateway
ownerDisplay	"raw"	显示原始用户名

说明：

/status → 查看状态
/new → 新会话
/cron → 定时任务
/gateway restart → 重启网关

九、session 会话配置

json

"session": {
  "dmScope": "per-channel-peer"
}

dmScope 决定了不同地方的私聊是否共享同一个会话记忆。

值	含义
per-channel-peer	每个渠道+用户独立会话，不同渠道互不干扰
main	所有 DM 共享一个 session，记忆互通

十、cron 定时任务

json

"cron": {}

目前没有配置定时任务。可以通过 /cron add 命令添加。

十一、channels 渠道配置

json

"telegram": {
  "enabled": true,
  "dmPolicy": "allowlist",
  "botToken": "825*******tPg...",
  "allowFrom": ["74*****34"],
  "groupPolicy": "allowlist",
  "streaming": true,
  "proxy": "http://127.0.0.1:7897"
}

字段	含义
enabled	是否启用
dmPolicy	私聊策略（allowlist = 白名单）
botToken	Telegram 机器人 Token（敏感信息）
allowFrom	允许的用户 ID 列表
groupPolicy	群聊策略
streaming	是否流式输出
proxy	代理地址（国内访问 Telegram 需要代理）

飞书

json

"feishu": {
  "enabled": true,
  "appId": "cli_a9********8dcb3",
  "appSecret": "UqN****************siXsF",
  "domain": "feishu",
  "groupPolicy": "allowlist",
  "connectionMode": "websocket"
}

字段	含义
enabled	是否启用
appId	飞书应用 ID
appSecret	飞书应用密钥（敏感信息）
domain	域名（feishu = 国内版）
groupPolicy	群聊策略
connectionMode	连接模式（websocket = 实时连接）

十二、gateway 网关配置

json

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "loopback",
  "controlUi": {
    "allowedOrigins": [
      "http://127.0.0.1:18789",
      "http://192.168.0.2:18789"
    ]
  },
  "auth": {
    "mode": "token",
    "token": "0b4d19e6f46********c338b4c"
  },
  "tailscale": {
    "mode": "off",
    "resetOnExit": false
  },
  "nodes": {
    "browser": { "mode": "auto" }
  }
}

字段	含义
port	网关端口（18789）
mode	运行模式（local = 本地模式）
bind	绑定地址（loopback = 只监听本地）
controlUi.allowedOrigins	允许访问的来源地址（CORS 白名单）
auth.mode	认证模式（token = Token 认证）
auth.token	认证 Token（敏感信息）
tailscale	内网穿透配置
nodes.browser.mode	浏览器节点模式（auto = 自动）

十三、skills 技能配置

json

"skills": {
  "entries": {
    "tavily": {
      "enabled": true,
      "env": {
        "TAVILY_API_KEY": "tvly-dev-ojSXF********g6tLf"
      }
    }
  }
}

字段	含义
tavily.enabled	是否启用 Tavily 搜索技能
tavily.env.TAVILY_API_KEY	Tavily API 密钥（敏感信息）

说明：Tavily 是一个 AI 搜索引擎，让 OpenClaw 能联网搜索信息。

十四、plugins 插件配置

json

"plugins": {
  "entries": {
    "telegram": { "enabled": true },
    "feishu": { "enabled": true }
  }
}

启用了 Telegram 和飞书插件，让 OpenClaw 能在这两个平台上收发消息。

十五、agents.defaults.models.alias 别名配置

json

"agents": {
  "defaults": {
    "models": {
      "moonshot/kimi-k2.5": {
        "alias": "Kimi"
      }
    }
  }
}

作用：给模型起「快捷名」，方便切换。

bash

# 没有别名时
/model moonshot/kimi-k2.5  ← 要打完整的模型ID

# 有别名后
/model Kimi  ← 只需要打别名

十六、auth 认证配置

json

"auth": {
  "profiles": {
    "moonshot:default": {
      "provider": "moonshot",
      "mode": "api_key"
    }
  }
}

作用：记录「认证配置文件的元数据」，方便管理多个 API 密钥。

实际 API 密钥存储位置：~/.openclaw/agents/<agentId>/agent/auth-profiles.json

十七、Canvas 画布与 Nodes 节点控制

Canvas 画布

Canvas = 在设备屏幕上显示内容的工具，需要配对的节点设备（Mac、iPhone、Android 手机）。

功能	说明
present	在设备屏幕上显示内容
snapshot	截取当前显示内容
a2ui_push	推送 AI 生成的 UI 界面

Nodes 节点控制

Nodes = 控制配对的远程设备。

功能	说明
camera_snap	拍照
camera_clip	录制视频
screen_record	录制屏幕
location_get	获取 GPS 位置
notify	发送系统通知
run	在设备上执行命令

十八、Message 消息发送

Message = 主动发送消息到其他渠道（不是在当前聊天中回复）。

与 sessions_send 的区别：

工具	用途
message	主动发送到任意渠道/群/人
sessions_send	发送到另一个 OpenClaw 会话

十九、Gateway 工具说明

Gateway 工具 ≠ 编辑 openclaw.json

工具	能做什么	结果
edit	修改 openclaw.json 文件	文件改了，但 Gateway 不会自动重启
gateway.config.patch	修改配置 + 重启 Gateway	配置立即生效

Gateway 工具的实际功能：

功能	说明
restart	重启 Gateway 进程
config.get	获取当前配置
config.apply	写入完整配置 + 重启
config.patch	合并部分配置 + 重启
update.run	运行更新 + 重启

关键词：OpenClaw配置, openclaw.json, CDP浏览器控制, models模式配置, agents智能体配置, gateway网关, skills技能配置

OpenClaw配置文件详解：openclaw.json逐行解读

OpenClaw配置文件详解：openclaw.json逐行解读 ​

一、meta 元数据 ​

二、wizard 向导 ​

三、browser 浏览器控制 ​

四、models 模型配置 ​

4.1 models.mode: "merge" 的含义 ​

4.2 providers：AI 模型提供商列表 ​

moonshot 提供商（月之暗面/Kimi） ​

aliyun 提供商（阿里云百炼） ​

五、agents 智能体配置 ​

5.1 model 模型选择 ​

5.2 workspace 工作目录 ​

5.3 compaction 压缩配置 ​

5.4 heartbeat 心跳 ​

5.5 maxConcurrent 并发限制 ​

六、tools.profile 配置 ​

七、messages 消息配置 ​

八、commands 命令配置 ​

九、session 会话配置 ​

十、cron 定时任务 ​

十一、channels 渠道配置 ​

Telegram ​

飞书 ​

十二、gateway 网关配置 ​

十三、skills 技能配置 ​

十四、plugins 插件配置 ​

十五、agents.defaults.models.alias 别名配置 ​

十六、auth 认证配置 ​

十七、Canvas 画布与 Nodes 节点控制 ​

Canvas 画布 ​

Nodes 节点控制 ​

十八、Message 消息发送 ​

十九、Gateway 工具说明 ​

OpenClaw配置文件详解：openclaw.json逐行解读

OpenClaw Skills添加详细步骤：让小龙虾具备更多技能

OpenClaw+TG配置教程：5步完成Telegram Bot接入

OpenClaw 53个官方内置Skills完全指南：从笔记到语音全覆盖

OpenClaw AI视频脚本生成技能：一句话生成完整分镜提示词

OpenClaw进阶技巧50个：斜杠命令/记忆系统/Skills安装/成本优化

OpenClaw专属数据分析师：5步配置，自动出图发报告

OpenClaw × web-access实战：AI自己打开浏览器，帮你刷10个平台

CC Switch：51K星标的Agent模型切换神器，一键热切换所有Agent

不要孤军奋战啦！

OpenClaw配置文件详解：openclaw.json逐行解读

一、meta 元数据

二、wizard 向导

三、browser 浏览器控制

四、models 模型配置

4.1 models.mode: "merge" 的含义

4.2 providers：AI 模型提供商列表

moonshot 提供商（月之暗面/Kimi）

aliyun 提供商（阿里云百炼）

五、agents 智能体配置

5.1 model 模型选择

5.2 workspace 工作目录

5.3 compaction 压缩配置

5.4 heartbeat 心跳

5.5 maxConcurrent 并发限制

六、tools.profile 配置

七、messages 消息配置

八、commands 命令配置

九、session 会话配置

十、cron 定时任务

十一、channels 渠道配置

Telegram

飞书

十二、gateway 网关配置

十三、skills 技能配置

十四、plugins 插件配置

十五、agents.defaults.models.alias 别名配置

十六、auth 认证配置

十七、Canvas 画布与 Nodes 节点控制

Canvas 画布

Nodes 节点控制

十八、Message 消息发送

十九、Gateway 工具说明