OpenClaw.json配置文件操作小白指南
说到OpenClaw.json这个基本配置文件，是绝大多数养虾人都逃不过的定数，你不接触，也迟早会碰到。
尤其是当你的小龙虾装了个插件，或者改了一下模型、Agent等某个配置时，未经过你允许擅自修改保存并重启Gateway网关，大概率就会报错。
配置文件一报错，Gateway网关就启动不起来。而且大模型还特别习惯给openclaw.json的配置文件添加一些不存在的字段，或者把格式改错。
遇到报错无法启动网关的情况，你只能是运行openclaw doctor命令启动修复，有时候某些格式错误问题是修复不了的，还会导致异常不断重启。
因此，深入了解openclaw.json配置文件的每一个核心配置项，稳妥的修改方式，以及常见错误和常用命令，是很有必要的。
所以今天这篇文章，老马会把openclaw.json基础内容掰开揉碎了，介绍给大家，尽可能保证小白新手养虾户也能看懂，更能上手。
请务必仔细阅读，通过本文，你将了解和学会以下内容：
1、配置文件到底在哪，长什么样。
2、哪些配置分别代表什么意思。
3、修改后到底要不要重启。
4、常见错误和常用命令。
说到这里，有小伙伴就会问，老马你的配置文件是怎样的，发出来我们直接抄不就完了。
这是一个认知的误区，首先老马自己的配置文件，里面有些配置选项，比如多Agent设置，亦或是插件，渠道的设置，跟你的情况和需求是完全不同的。
正所谓千人千面，千虾千配置，直接抄过去是没用的，甚至还有可能引发一些报错显示在日志上。
openclaw.json配置文件，从你开始部署完OpenClaw小龙虾那一刻开始，它就是在不断更新修改，添加或者删除内容的。
可以说，每个人的openclaw.json配置文件，大体上的配置选项是差不多的，但是细节上会有区别，不一定代表大家可以互换配置文件。
甚至参考都是没有什么价值的，因为你只要了解了openclaw.json的底层的东西，你会发现配置文件的强大与弱小，对你龙虾的能力并不起决定性作用。
它顶多算是一份说明书罢了，啰嗦这么多，主要是看到很多小伙伴喜欢跟风。看啥都觉得人家的好，抄过来自己用肯定也好用。
小龙虾得自己养，自己喂饲料，自己装技能、装插件，自己跑通工作流程，自己调整记忆系统等等。这样养出来的小龙虾，才是对自己有用的。
废话不多说，下面直接进入今天的主题。
openclaw.json到底是啥？
假设现在你在开一家餐厅，openclaw.json就是你的餐厅运营手册，里面写着：
1、厨房在哪（工作区配置）
2、用什么食材（AI 模型配置）
3、接待哪些客人（渠道配置）
4、服务员怎么招呼人（智能体配置）
5、遇到投诉怎么处理（错误处理配置）
运营手册写清楚了，餐厅才能正常运转。
运营手册写错了，轻则上错菜，重则直接关门（Gateway 启动失败）。要不老马上面说，它就是一份说明书，一份小龙虾的运行工作说明书。
openclaw.json这个配置文件一般在电脑上，或者服务器上所处的位置，得区分不同的操作系统，系统不一样，文件路径不一样。
Windows系统：
C:\Users\你的用户名\.openclaw\openclaw.json
Mac/Linux 用户：
~/.openclaw/openclaw.json
如果你习惯自己去找文件夹路径的话，那手动查找就行了，或者使用系统的搜索功能去搜索。或者你也可以在命令行窗口输入命令，打开openclaw.json文件，命令如下：
# Mac终端
open ~/.openclaw/openclaw.json
# Windows PowerShell
code ~/.openclaw/openclaw.json
# Linux终端
nano ~/.openclaw/openclaw.json
openclaw.json核心配置选项
openclaw.json的核心配置选项可以分为工作区配置、渠道配置、模型配置、会话管理、工具配置、Webhooks配置、定时任务等。
下面将采用示例的配置文件，关键字段两个维度，对以上的核心配置选项进行详细说明。有些配置选项会带上老马的个人建议，但也仅供参考。
1、工作区配置
工作区配置是最重要的配置选项，没有之一。这里定义你的Agent的工作区域路径，使用什么模型，心跳间隔多少等，主Agent跟子Agent的设定都在于此，下面是仅供参考的配置文件内容，请勿直接复制使用：
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace", // 工作区路径
"model": {
"primary": "anthropic/claude-sonnet-4-5", // 主模型
"fallbacks": ["openai/gpt-5.2"] // 备用模型
},
"sandbox": {
"mode": "non-main", // 沙箱模式
"scope": "agent",
"workspaceAccess": "rw"
},
"heartbeat": {
"every": "30m", // 心跳间隔
"target": "last",
"directPolicy": "allow"
}
},
"list": [
{
"id": "main",
"default": true,
"workspace": "~/.openclaw/workspace"
},
{
"id": "coding",
"workspace": "~/.openclaw/workspace-coding"
}
]
}
}看到以上json内容，大多数小白用户是懵逼的，不知道是啥意思。所以你就得了解字段，知道每个字段代表含义，再一一对照看看，你就懂了。工作区配置的关键字段明细表如下：
简单说明一下，上面的配置内容中，我们可以看到defaults、sandbox、heartbeat、list这些是对象跟数组。
以list数组为例，里面还有id、default、workspace，这些就是字段，跟上面表格中的关键字段是一类的。
如果我们需要配置多智能体，就可以在list数组里定义多个智能体，每个智能体都有独立的工作区。因此仅供参考的配置文件内容如下：
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"workspace": "~/.openclaw/workspace"
},
{
"id": "coding",
"workspace": "~/.openclaw/workspace-coding",
"sandbox": {
"mode": "all",
"workspaceAccess": "rw"
}
}
],
"defaults": {
"model": {
"primary": "custom-coding-dashscope-aliyuncs-com/kimi-k2.5"
}
}
}
}从上面的配置文件内容中，你就可以看到，agents里面的list数组，包含了id是main，id是coding两个智能体，它们对应的工作区workspace文件夹路径是不一样。
2、渠道配置
渠道配置就很好理解了，允许你的小龙虾接入什么聊天渠道，是QQ机器人、飞书机器人、钉钉机器人，还是微信Clawbot，谁可以通过这些渠道跟你的小龙虾进行聊天，俗称私信策略，仅供参考的配置文件内容如下：
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123:abc",
"dmPolicy": "pairing", // 私信策略
"allowFrom": ["tg:123"], // 白名单
"groups": {
"*": {
"requireMention": true // 群组中需要@才回复
}
}
},
"whatsapp": {
"dmPolicy": "pairing",
"allowFrom": ["+15555550123"],
"groupPolicy": "allowlist",
"groupAllowFrom": ["+15555550123"]
}
}
}重点需要说明的是dmPolicy字段，它的不同值，代表不一样的设置，以及安全性，具体对照如下表：
一般来说，老马个人建议这个值的设置个人设置为pairing。公司企业团队设置为allowlist+白名单。如果是完全公开服务就设置为open。
3、模型配置
模型配置就是告诉你的小龙虾，使用什么大脑去思考，并完成任务。或者不同的任务，需要切换使用不同的大脑。
有关OpenClaw小龙虾对接多个模型，根据不同任务需求切换模型的说明教程，可以回看老马之前的文章：OpenClaw接入多个模型实现自动手动切换配置。
仅供参考的配置文件内容如下：
{
"models": {
"mode": "merge", // 配置合并模式
"providers": {
"anthropic": {
"baseUrl": "https://api.anthropic.com",
"apiKey": "${ANTHROPIC_API_KEY}",
"api": "anthropic-messages",
"models": [
{
"id": "claude-sonnet-4-5",
"name": "Claude Sonnet 4.5",
"contextWindow": 200000,
"maxTokens": 8192
}
]
},
"moonshot": {
"baseUrl": "https://api.moonshot.cn/v1",
"apiKey": "${MOONSHOT_API_KEY}",
"api": "openai-completions",
"models": [
{
"id": "kimi-k2.5",
"name": "Kimi K2.5"
}
]
}
}
}
}重点还是了解一些关键字段的含义，如下表：
像上面的参考配置文件内容中，就接入两个模型提供商，你看providers字段下面就有anthropic、moonshot这两家的名字。
其它的字段你一一对应自己的openclaw.json里面的内容，你就会发现这个所谓的json格式的配置文件，也不是那么难懂，它的结构有点类似于树状图，只要懂得字段含义，看起来就很简单。
4、会话管理
会话管理是控制会话怎么隔离和重置的问题，目前OpenClaw的会话是默认每天凌晨4点后重置，或者120分钟（2个小时）没有任何对话后重置。
重置之后，你再去跟小龙虾聊天，它就忘了上下文，等于新开了一个会话进行聊天。因此，当天的记忆必须得成功创建成每日记忆文件，或者记录到长期记忆文件中。
否则你就会发现，今天聊的，明天小龙虾就全忘了，你又得去重复说明上下文背景信息，等于白聊。有关这方面的记忆系统优化，老马后面有时间了会单独分享优化方法。
接着往下看仅供参考的配置文件内容：
{
"session": {
"dmScope": "per-channel-peer", // 私聊会话隔离策略
"threadBindings": {
"enabled": true,
"idleHours": 24,
"maxAgeHours": 0
},
"reset": {
"mode": "daily", // 重置模式
"atHour": 4, // 每天 4 点重置
"idleMinutes": 120 // 空闲 120 分钟也重置
}
}
}这里还是重点看dmScope字段对应配置的值，如下表：
一般我们把dmScope字段的值设置成per-channel-peer就可以了，这会对每个渠道接入的会话跟用户进行独立隔离，互不干扰，上下文不乱串。
大白话讲就是，假设你的小龙虾同时接入了QQ机器人、微信Clawbot，设置成per-channel-peer后。你就会发现在QQ上与小龙虾聊天，跟在微信Clawbot上与小龙虾聊天，它们两者的对话记录是分开的。
5、工具配置
工具配置同样是比较简单的，这里的配置是控制你的小龙虾能不能使用工具，以及能使用什么工具。仅供参考的配置文件内容如下：
{
"tools": {
"profile": "full", // 工具预设
"allow": ["browser"], // 额外允许的工具
"deny": [] // 明确禁止的工具
}
}我们重点还是看profile这个工具预设的字段，有一些小伙伴的小龙虾是3.8版本的，默认这个profile字段没有改成full，也就是没有改成允许使用全部工具。
这就会导致一个问题，让小龙虾去写一篇文章保存到word文档上。小龙虾却只会动嘴回答你问题，但不动手，甚至告诉你它使用不了工具。
因此profile字段对应各种值的预设说明如下表：
从上表中我们可以看出，针对不同的智能体，灵活配置profile字段的值，让每个智能体在工具使用上控制调配得当，不至于权限泛滥，乱用工具导致误删文件之类的事情发生。
6、Webhooks配置
Webhooks配置主要是用来接收外部消息的，比如小龙虾帮你自动处理 Issue后，GitHub推送过来的通知，又或者是邮件到达通知等等。仅供参考的配置文件内容如下：
{
"hooks": {
"enabled": true,
"token": "shared-secret",
"path": "/hooks",
"defaultSessionKey": "hook:ingress",
"allowRequestSessionKey": false,
"allowedSessionKeyPrefixes": ["hook:"],
"mappings": [
{
"match": { "path": "gmail" },
"action": "agent",
"agentId": "main",
"deliver": true
}
]
}
}7、定时任务
定时任务应该就比较好理解了，你如果有创建过定时任务，这里面也会出现一些对应的配置。比如每天早上定时给你发送财经新闻，每天晚上自动帮你整理撰写日报等等。
但openclaw.json中有定时任务的配置内容不是绝对的，定时任务也有可能单独保存在.openclaw\cron路径下，单独的jobs.json文件中。
仅供参考的配置文件内容如下：
{
"cron": {
"enabled": true,
"maxConcurrentRuns": 2,
"sessionRetention": "24h",
"runLog": {
"maxBytes": "2mb",
"keepLines": 2000
}
}
}以上是比较常见的openclaw.json核心配置选项，除此之外，Gateway的网关配置，以及当你安装了Skills技能，plugins插件后的配置，都会在openclaw.json的配置文件中体现。
甚至于你单独配置的browser浏览器，同样会出现在openclaw.json文件的配置内容中。但万变不离其宗，应该说你看懂了一个核心配置选项，后面的都能看懂的，所以这里老马就不一一赘述了。
openclaw.json的最佳修改方式
有些时候，我们难免会需要手动去修改openclaw.json配置文件。老手对json5比较熟悉的，可能一个文本编辑器打开文件就去修改了。
但对于新手小白来说，无论你是直接打开文件修改，还是通过小龙虾的Web UI界面修改，亦或是命令行窗口输入命令去修改。
老马始终觉得，你安装一个AI编程的IDE软件，是最佳的方式。国产就有很多可以免费使用，或者有一定免费额度的试用，比如字节的Trae、腾讯的CodeBuddy、阿里的Qoder这三家。
以Trae为例，你可以问问豆包和千问，或者百度搜索Trae下载安装，登录账号后，在软件界面上选择打开openclaw.json文件，右侧有个对话框，你就可以跟AI大模型对话，让它帮你去修改即可，如图：
AI编程IDE软件最大的优势是有图形界面，适合普通用户去使用，加上本身就是AI大模型加持下的编程工具，修改个json文件那是手到擒来。
你只需要用自然语言描述清楚，你要修改啥，比如改一下模型配置信息，把新的配置信息在对话框中输入，加上一句帮我修改默认配置的模型接入信息，稍等片刻，AI就帮你修改完成了。
当然，有条件的小伙伴可以选择下载安装Codex的桌面版，跟上面的国产AI编程IDE软件是一类工具，只不过大模型是GPT-5.4，效果会更好一些。
openclaw.json配置修改后，到底要不要重启？
这个问题的争议很大，结论是大部分配置修改后不需要重启，Gateway会自动热重载。
但是需要你在openclaw.json网关部分的mode模式字段里面，配置好热重载机制，仅供参考的配置文件内容如下：
{
"gateway": {
"reload": {
"mode": "hybrid", // hybrid | full | none
"debounceMs": 300 // 检测延迟（毫秒）
}
}
}从上面的配置文件内容中可以看出，mode模式字段目前的值是hybrid，也就是默认的热重载模式，或者叫智能重载模式，具体三种模式的值说明如下表：
配置了热重载机制之后，OpenClaw Gateway默认会监控配置文件变化。
比如文件修改后，Gateway会在 300ms内检测到，自动重新加载配置，大多数配置会立即生效。
但是也有例外，假如你在openclaw.json配置文件里面，修改了下表中的配置选项，那就得重启Gateway网关：
如果修改的是下表中的配置选项，则不需要重启Gateway网关：
至于如何判断你修改了openclaw.json配置文件后，配置是否生效，一般情况下你可以输入以下命令查看网关状态是否有问题：
openclaw gateway status
如果显示 “Running”，说明配置修改成功，没有问题，同时配置是加载成功的。
或者也可以输入以下命令查看日志：
openclaw logs –follow
日志中显示以下内容信息的话，就说明配置文件已经修改成功，并成功加载：
[INFO] Config file changed, reloading...
[INFO] Config reloaded successfully最最简单的判断方式就是，假设你上面修改了配置文件里面调用的大模型，由kimi-k2.5模型改成了GLM-5-Turbo模型。
你就直接跟小龙虾进行对话，问它是什么模型，如果回复是GLM-5-Turbo，那就说明配置修改并加载成功。
常见错误与常用命令
最后给大家贴一些修改openclaw.json配置文件时，经常会遇到的错误，以及常用的一些命令。
1、Gateway 启动失败
错误信息：Config validation failed
原因： 配置文件语法错误或有未知字段
解决方法：
# 运行诊断
openclaw doctor
# 自动修复
openclaw doctor --fix2、配置不生效
现象：修改了配置，但小龙虾行为、能力、工具等没有变化
可能原因：
（1）配置没保存（使用AI IDE编辑器修改后没保存）
（2）配置语法错误（Gateway网关拒绝加载）
（3）配置的路径错了
（4）需要重启的配置选项，却没有重启Gateway网关
排查步骤：
# 1. 检查 Gateway 状态
openclaw gateway status
# 2. 查看日志
openclaw logs --follow | grep "Config"
# 3. 验证配置值
openclaw config get <你的配置路径>
# 4. 重启 Gateway
openclaw gateway restart3、API Key的问题
错误信息：API key is missing or invalid
原因：
- API Key没配置
- API Key过期了，或者额度不足，套餐到期了
- 环境变量没加载
解决方法：
# 检查环境变量
echo $ANTHROPIC_API_KEY
# 重新配置
openclaw config set models.providers.anthropic.apiKey "sk-ant-..."
# 或者用环境变量
export ANTHROPIC_API_KEY="sk-ant-..."
openclaw gateway restart4、配置文件备份
改openclaw.json配置前，记得一定要先备份，你如果是让你的小龙虾去修改配置文件的话，记得加上一句，先备份再去修改，不然极大概率会掉坑。
老马的个人习惯是手动复制多一份openclaw.json文件，然后在openclaw名字后面加上日期。当然，你也可以通过输入命令的方式去备份：
# 备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# 恢复
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw gateway restart5、常用命令
# 配置管理
openclaw config get <路径> # 获取配置值
openclaw config set <路径> <值> # 设置配置值
openclaw config unset <路径> # 删除配置项
# Gateway 管理
openclaw gateway status # 查看状态
openclaw gateway start # 启动
openclaw gateway stop # 停止
openclaw gateway restart # 重启
# 诊断
openclaw doctor # 诊断配置
openclaw doctor --fix # 自动修复
openclaw logs --follow # 实时日志
openclaw health # 健康检查
# 备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak配置文件这东西，说难不难，说简单也不简单。难的是理解每个配置项的含义和适用场景。
简单的是，只要按照模板来，基本不会出大问题。老马的建议就一条，先跑起来，再慢慢调。
别一上来就搞最复杂的配置，结果最后连Gateway网关都启动不了。从最小配置开始，观察一段时间，再根据实际需求调整。
好了，以上就是今天的分享，欢迎关注、点赞、转发一键三连。有任何问题和需求，请在评论区留言，回见！
对了，老马最近刚创建了一个AI学习交流群，有兴趣进群的小伙伴可以添加老马微信号：immajiabin，添加好友时备注：进群（不备注不通过）。
