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就是你的餐厅运营手册，里面写着：

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的核心配置选项可以分为工作区配置、渠道配置、模型配置、会话管理、工具配置、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配置文件。老手对json5比较熟悉的，可能一个文本编辑器打开文件就去修改了。

但对于新手小白来说，无论你是直接打开文件修改，还是通过小龙虾的Web UI界面修改，亦或是命令行窗口输入命令去修改。

老马始终觉得，你安装一个AI编程的IDE软件，是最佳的方式。国产就有很多可以免费使用，或者有一定免费额度的试用，比如字节的Trae、腾讯的CodeBuddy、阿里的Qoder这三家。

以Trae为例，你可以问问豆包和千问，或者百度搜索Trae下载安装，登录账号后，在软件界面上选择打开openclaw.json文件，右侧有个对话框，你就可以跟AI大模型对话，让它帮你去修改即可，如图：

AI编程IDE软件最大的优势是有图形界面，适合普通用户去使用，加上本身就是AI大模型加持下的编程工具，修改个json文件那是手到擒来。

你只需要用自然语言描述清楚，你要修改啥，比如改一下模型配置信息，把新的配置信息在对话框中输入，加上一句帮我修改默认配置的模型接入信息，稍等片刻，AI就帮你修改完成了。

当然，有条件的小伙伴可以选择下载安装Codex的桌面版，跟上面的国产AI编程IDE软件是一类工具，只不过大模型是GPT-5.4，效果会更好一些。

这个问题的争议很大，结论是大部分配置修改后不需要重启，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 --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

原因：

1. API Key没配置

2. API Key过期了，或者额度不足，套餐到期了

3. 环境变量没加载

解决方法：

# 检查环境变量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，添加好友时备注：进群（不备注不通过）。