夜雨聆风
马佳彬
微信改版啦，一定别忘记点击上方蓝色的公众号名称，进入公众号资料页面，在右上角点击“...”设为星标★，更多干货，不再错过！
说到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内容，大多数小白用户是懵逼的，不知道是啥意思。所以你就得了解字段，知道每个字段代表含义，再一一对照看看，你就懂了。工作区配置的关键字段明细表如下：
字段 | 说明 | 推荐值 |
workspace | 智能体工作区路径 | ~/.openclaw/workspace |
model.primary | 主模型 | 根据你用的模型填 |
model.fallbacks | 备用模型列表 | 至少配一个 |
sandbox.mode | 沙箱模式 | non-main（主智能体不用沙箱） |
heartbeat.every | 心跳间隔 | 30m（30 分钟） |
简单说明一下，上面的配置内容中，我们可以看到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 | 任何人都可以 | ⚠️ 低 |
disabled | 禁用私信 | 🔒 最高 |
一般来说，老马个人建议这个值的设置个人设置为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"}]}}}}
重点还是了解一些关键字段的含义，如下表：
字段 | 说明 |
mode | merge表示合并配置，override表示覆盖 |
providers | 模型提供商列表 |
baseUrl | API 地址 |
apiKey | API 密钥（推荐用环境变量） |
api | API 类型（openai-completions、anthropic-messages等） |
像上面的参考配置文件内容中，就接入两个模型提供商，你看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字段对应配置的值，如下表：
值 | 说明 | 适用场景 |
main | 所有用户共享一个会话 | 个人用 |
per-peer | 每个用户独立会话 | 推荐 |
per-channel-peer | 每个渠道 + 用户独立 | 多渠道用 |
per-account-channel-peer | 最细粒度隔离 | 多账号用 |
一般我们把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字段对应各种值的预设说明如下表：
预设 | 包含工具 | 适用场景 |
minimal | 仅状态查询 | 监控型智能体 |
coding | 文件 + 命令 + 会话 + 记忆 | 编程智能体 |
messaging | 消息 + 会话管理 | 客服智能体 |
full | 全部工具 | 主智能体 |
从上表中我们可以看出，针对不同的智能体，灵活配置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，也就是默认的热重载模式，或者叫智能重载模式，具体三种模式的值说明如下表：
模式 | 说明 | 适用场景 |
hybrid | 智能重载（默认） | 推荐，平衡性能和实时性 |
full | 每次修改都完全重载 | 调试时用 |
none | 禁用热重载 | 生产环境，追求稳定 |
配置了热重载机制之后，OpenClaw Gateway默认会监控配置文件变化。
比如文件修改后，Gateway会在 300ms内检测到，自动重新加载配置，大多数配置会立即生效。
但是也有例外，假如你在openclaw.json配置文件里面，修改了下表中的配置选项，那就得重启Gateway网关：
配置项 | 原因 |
gateway.bind | 绑定地址改变，需要重新监听 |
gateway.port | 端口改变，需要重新绑定 |
gateway.remote | 远程访问模式改变 |
gateway.reload | 重载策略本身改变 |
env.* | 环境变量需要重新加载 |
如果修改的是下表中的配置选项，则不需要重启Gateway网关：
配置项 | 生效方式 |
agents.* | 自动热重载 |
channels.* | 自动热重载 |
models.* | 自动热重载 |
tools.* | 自动热重载 |
session.* | 自动热重载 |
hooks.* | 自动热重载 |
至于如何判断你修改了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 --fix
2、配置不生效
现象：修改了配置，但小龙虾行为、能力、工具等没有变化
可能原因：
（1）配置没保存（使用AI IDE编辑器修改后没保存）
（2）配置语法错误（Gateway网关拒绝加载）
（3）配置的路径错了
（4）需要重启的配置选项，却没有重启Gateway网关
排查步骤：
# 1. 检查 Gateway 状态openclaw gateway status# 2. 查看日志openclaw logs --follow | grep "Config"# 3. 验证配置值openclaw config get <你的配置路径># 4. 重启 Gatewayopenclaw gateway restart
3、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 restart
4、配置文件备份
改openclaw.json配置前，记得一定要先备份，你如果是让你的小龙虾去修改配置文件的话，记得加上一句，先备份再去修改，不然极大概率会掉坑。
老马的个人习惯是手动复制多一份openclaw.json文件，然后在openclaw名字后面加上日期。当然，你也可以通过输入命令的方式去备份：
# 备份cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak# 恢复cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.jsonopenclaw gateway restart
5、常用命令
# 配置管理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，添加好友时备注：进群（不备注不通过）。
