OpenClaw核心配置文件openclaw.json详解解

一、基础认知（新手必看）

1. 配置文件位置

默认在~/.openclaw/openclaw.json（Linux/Mac/ Windows WSL2）。

2. 修改规则

标准JSON格式，不能漏逗号、引号，修改前建议先备份：cp openclaw.json openclaw.json.bak.日期
改完必须重启Gateway生效：openclaw gateway restart
配置错了直接用备份文件覆盖回滚即可

3. 整体结构

你的配置文件包含12个顶级配置段，按重要性分三类：

分类	配置段	是否需要手动改
🔥 核心必改	`models` /`agents`/`channels`/`tools`	是
⚙️ 按需修改	`gateway` /`auth`/`plugins`	按需调整
🧊 不用改	`meta` /`wizard`/`messages`/`commands`/`session`/`hooks`	系统自动维护，不用动

二、核心配置段详解

1. 🔥 `models` 大模型配置（你想接什么模型都在这里改）

控制所有接入的大模型提供商和可用模型，支持所有兼容OpenAI协议的模型：

"models": {  "mode": "merge", // merge=合并系统默认模型+自定义模型；override=仅用自定义模型  "providers": {    "ark": { // 提供商ID，自定义即可      "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3", // 模型API端点      "api": "openai-completions", // API协议，几乎所有厂商都兼容OpenAI      "models": [ // 该提供商下的可用模型列表        {          "id": "doubao-seed-2.0-pro", // 模型ID，从提供商控制台获取          "name": "豆包Seed 2.0 Pro", // 显示名称          "reasoning": false, // 是否支持思维链输出          "input": ["text"], // 支持的输入类型：文本/图片/视频          "contextWindow": 128000, // 上下文窗口大小（token数）          "maxTokens": 8192, // 最大输出token数          "cost": { // 计费参数，个人使用全部填0即可            "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0          }        }      ]    },    "moonshot": { /* 其他模型提供商配置，和上面结构一样 */ }  }}

✅ 支持接入的模型：

公有云模型：豆包、Kimi、DeepSeek、GPT系列、Claude系列等
本地私有化模型：Llama3、Qwen2、GLM4等，只要部署的时候开启OpenAI兼容API即可
企业专属模型：火山方舟、阿里云百炼、腾讯混元等企业级模型

2. 🔥 `agents` Agent实例配置（多独立AI的核心）

每个Agent就是一个独立的AI助理，完全隔离，有自己的记忆、工作区、模型、工具权限：

"agents": {  "defaults": { // 全局默认配置，所有Agent都会继承    "model": {      "primary": "ark/doubao-seed-2.0-pro" // 全局默认模型，格式：提供商ID/模型ID    },    "workspace": "/root/.openclaw/workspace", // 默认工作区路径    "maxConcurrent": 4, // 最大并发会话数    "subagents": { "maxConcurrent": 8 } // 子Agent最大并发数  },  "list": [ // 所有独立Agent实例列表    {       "id": "main", // 主Agent，默认继承全局配置      "name": "通用助理"    },    {      "id": "coder", // 代码专属Agent，完全独立      "name": "代码助手",      "workspace": "/root/.openclaw/workspace-coder", // 专属独立工作区      "model": { "primary": "deepseek/deepseek-coder" }, // 专属模型，不用全局默认      "tools": { "profile": "coding" } // 专属工具权限，只开代码相关工具    }  ]}

💡 玩法参考：

客服Agent：绑定知识库模型，仅开文档工具，专门回答用户问题
运维Agent：绑定代码模型，仅开服务器操作工具，处理运维需求
新闻Agent：绑定搜索工具，定时爬取新闻推送
每个Agent完全独立，记忆不会互通，不会互相干扰

3. 🔥 `channels` 消息渠道配置（绑定飞书/微信/企业微信机器人）

每个渠道实例对应一个消息机器人，可绑定到不同Agent：

"channels": {  "feishu": [ // 飞书渠道，数组格式支持多个飞书机器人    {      "id": "default", // 渠道唯一ID      "enabled": true, // 开启这个机器人      "appId": "cli_xxxxxx", // 飞书应用ID，从飞书开放平台获取      "appSecret": "xxxxxx", // 飞书应用密钥      "connectionMode": "websocket", // 连接模式，推荐websocket      "domain": "feishu", // 国内用feishu，海外用lark      "groupPolicy": "allowlist", // 群策略：allowlist=仅白名单群可用；all=所有群可用      "allowFrom": ["*"], // 私聊白名单：*=允许所有用户私聊；[]=禁止所有私聊      "groupAllowFrom": ["oc_xxxxxx"], // 群白名单，填写群open_id      "agentId": "main" // 绑定的AgentID，这个机器人的消息都发给对应Agent处理    },    {      "id": "coder-bot", // 第二个飞书机器人      "enabled": true,      "appId": "cli_yyyyyy",      "appSecret": "yyyyyy",      "allowFrom": ["*"],      "groupAllowFrom": ["*"], // 允许所有群使用      "agentId": "coder" // 绑定到代码Agent    }  ],  "openclaw-weixin": { /* 微信渠道配置，和飞书逻辑一致 */ }}

✅ 效果：你可以有N个完全独立的机器人，比如：

机器人A（通用助理）→ 主Agent → 处理日常问题
机器人B（代码助手）→ 代码Agent → 专门写代码
机器人C（新闻推送）→ 新闻Agent → 每天自动发早报

4. 🔥 `tools` 全局工具权限配置（控制AI能做什么不能做什么）

全局控制所有工具的开关，单个Agent可以单独覆盖：

"tools": {  "profile": "coding", // 工具权限模板：coding=开放所有代码工具；restricted=限制高危命令  "web": {    "search": {      "enabled": true, // 开启网页搜索能力      "provider": "kimi", // 搜索提供商      "kimi": { "apiKey": "sk_xxxxxx" } // 搜索API密钥    },    "fetch": { "enabled": true } // 开启网页抓取能力  }}

💡 常见工具开关：

可以单独关闭exec命令执行权限，避免AI执行高危命令
可以单独开启飞书文档/知识库/Bitable工具，实现文档问答
可以开启邮件/日历/提醒工具，实现个人助理功能

5. ⚙️ `gateway` 网关服务配置（控制访问权限）

控制OpenClaw服务的网络、端口、安全：

"gateway": {  "port": 18789, // 网关服务端口，控制UI访问端口  "mode": "local", // 运行模式：local=仅本地访问；public=公网可访问  "bind": "loopback", // 绑定地址：loopback=仅127.0.0.1；0.0.0.0=绑定所有网卡  "auth": {    "mode": "token", // 认证模式：token=API密钥认证；none=无认证（公网下禁止用none）    "token": "xxxxxx" // 访问控制UI的API密钥  },  "nodes": {    "denyCommands": [ // 高危命令黑名单，永远不允许执行      "camera.snap", "screen.record", "sms.send"    ]  }}

⚠️ 公网部署注意：如果要公网访问控制UI，一定要：

把mode改成public，bind改成0.0.0.0
确保auth.mode是token，不要用无认证模式
配置防火墙只开放18789端口，或者用反向代理加HTTPS

6. ⚙️ 其他配置段（按需修改即可）

auth
全局授权配置，声明不同API提供商的授权类型，实际密钥存在credentials目录下，不会明文存储
plugins
插件管理配置，控制飞书/微信/企业微信等扩展插件的开关
剩下的meta/wizard/messages等配置段都是系统自动维护，不用手动修改

三、实用配置模板（直接抄作业）

模板1：接入本地私有化模型

"models": {  "providers": {    "local": {      "baseUrl": "http://127.0.0.1:8000/v1", // 本地模型的OpenAI兼容API地址      "api": "openai-completions",      "models": [        {          "id": "qwen2-7b",          "name": "通义千问2 7B本地版",          "reasoning": false,          "input": ["text"],          "contextWindow": 32000,          "maxTokens": 4096,          "cost": {"input":0, "output":0}        }      ]    }  }}

模板2：完全限制私聊，仅允许指定群使用

"feishu": {  "enabled": true,  "appId": "cli_xxxxxx",  "appSecret": "xxxxxx",  "groupPolicy": "allowlist",  "allowFrom": [], // 空数组=禁止所有私聊  "groupAllowFrom": ["oc_群1ID", "oc_群2ID"], // 仅允许这两个群使用  "agentId": "main"}

四、避坑指南（新手必看）

JSON格式错误
修改后可以用在线JSON校验工具验证格式，不要漏逗号、引号
改完没重启
所有配置修改必须重启Gateway才会生效，openclaw gateway restart
密钥放错位置
API密钥不要直接写在openclaw.json里，要存在credentials目录下的对应JSON文件
公网暴露无认证
公网部署一定要开token认证，不要用auth.mode: none，会被黑
多Agent绑定错误
多机器人配置的时候，agentId要和agents.list里的ID一一对应

五、常见FAQ

Q：修改配置会不会丢失历史记忆？

A：不会，记忆存在memory目录和每个Agent的独立目录下，修改配置不会影响记忆数据。

Q：多Agent的配置会互相影响吗？

A：完全不会，每个Agent有自己的工作区、记忆、模型、工具权限，完全隔离。

Q：最多可以接入多少个机器人？

A：没有限制，只要服务器性能够，你可以接N个飞书/微信/企业微信机器人，绑定不同的Agent。

Q：能不能给不同的群绑定不同的Agent？

A：可以，在channels.feishu配置里给每个群单独做渠道配置，绑定不同的agentId即可。

如果你对 AI 编程、智能体开发和 AI 应用落地感兴趣，欢迎关注我的公众号。

我是一名 20 年经验的软件工程师，会持续分享 AI Agent 实战、AI 编程工具和真实项目案例。

如果这篇文章对你有帮助。关注我，一起把 AI 从 Demo 变成生产力。