先聊聊 OpenClaw 的配置文件

各位好，我们继续来聊 OpenClaw。 之前和大家聊了 OpenClaw 为什么要用 WebSocket，那次又是不小心文章写长了：）

这次开始和大家分享一些我对 OpenClaw 使用层面的理解。 也是自己最近空闲的时候，各种折腾研究了一个月左右，遇到和解决的各种问题。

如果要一次都聊的话， 又会很长，还是拆成一些小话题，我争取一点点都写完。

我们先说说配置文件和基础结构。

如果你是把它装在 macOS 系统上， 那么一定会在你当前用户目录上创建一个 .openclaw 的隐藏目录：

~/.openclaw

这个目录里有很多有用的文件， 比如 workspace, 是你当前默认的工作空间， 这里面你还会看到很多 Markdown 文件， 比如 SOUL.md, AGENTS.md 等等。 这个是可以让你做个性化的地方， 我们这次主要聊配置文件，这些地方就先一笔带过了。

配置文件在哪

同样在这个目录里， 你会看到这样一个 json 文件 ~/.openclaw/openclaw.json。 我们如果看官方的教程，运行 openclaw onboard, 进行初始化的时候， 有一系列提示， 比如怎么选模型， 怎么选channel 等等， 实际上就是往这个文件里写内容。

另外， 我们在 Web 界面打开点这个 Config 的时候， 实际上也是在操作这个配置文件：

这里不得不说， Web 端这个配置管理界面，做的还是很烂：）

至少给我的感觉，实在是看着费劲， 所以我更习惯直接去看这个 json 配置文件。

配置文件的结构

这个配置文件，大概是这个样子：

{  "env": { ... },  "agents": { ... },  "gateway": { ... },  "channels": { ... },  "plugins": { ... },  "tools": { ... },  "messages": { ... }}

每个顶层 key 都是一个子模块的配置项。

取决于你的 OpenClaw 版本， 以及 onboard 初始化时候的配置，这里面并不一定所有的 key 你都有。

但是 agents 这个 key 是一定会有的。 我们就来聊这个。

agents 定义模型和工具行为

agents 的配置内容大概长这样：

"agents": {  "defaults": {    "models": {      "minimax/minimax-m2.7": { "alias": "minimax" }    },    "model": {      "primary": "minimax/minimax-m2.7"    },    "workspace": "/Users/xxx/.openclaw/workspace",  }}

OpenClaw 的 json 配置文件， 嵌套的层级经常很深。 大家看它文档的时候， 经常这样说配置，比如 agents.defaults.model.primary , 实际上指的就是上面这个 json 层级的一个节点。

包括它自己的 CLI 命令行很多工具，在引用设置的时候，也会用这种点号的表示法。

这里边的几个配置条目，简单跟大家聊聊。 我也用这种点号表示法来说了。

先说 agents.defaults.models： 注意啊， 我说的这个配置条目，是带 s 的， 复数形式的，大家仔细对比上面我贴的 json 内容。

这个 models 是一个列表，它的作用是放我们当前 agents 可用的模型。 可用模型只是备选模型，不是当前 agent 正在使用的。 这里边也不是什么模型都能放， 一定要写 OpenClaw 当前版本，能够支持的。

什么叫能支持呢， 比如上面我们例子中写的 minimax， 当前版本是有专门的子程序可以处理和 minimax API 交互的。 至于都支持哪些模型的完整列表， 大家去看 OpenClaw 的官方文档就可以。

再接着说下面这个配置 agents.defaults.model.primary ， 注意， 这次不带 s， 这个配置就是当前这个 agent 主模型，我们发消息，他就会调用这个模型。这个模型名称，要在 models 列表里面。

另外， 要吐槽一点的，就是这个 defaults， 很迷惑人。 实际上 agents.defaults 里面定义的是全局默认的 agent 配置。

这里跟大家再分享一下，我们在 OpenClaw 一个 gateway 服务中，可不是只能运行唯一一个 agent 的。 如果你用的比较久之后，你会发现对不同职责的角色，你很可能会创建多个 agent。 每个 agent 都有自己的 workspace ，以及各自的 skill 以及 SOUL.md, AGENTS.md 这些文件。

是的，每个 agent 是会有自己独立的 workspace 目录的， 大家看我上面贴的默认生成的 json 配置， 是不是在 defaults 里面也有一个 workspace 目录，但它是全局默认配置的意思，这个实际上就会有点容易让人产生误会。简单理解就是，我们刚安装的 OpenClaw 实际上是没有一个明确定义的 agent 的， 它是用默认配置帮我们构建了一个 agent，叫做 main。

就比如这张图， 实际上我的 OpenClaw 是有一个我自己定义的 agent 叫做 swiftcafe， 但是大家首次安装的时候， 实际上就只有这个 main(default).

这就又是另外一个话题了， 篇幅原因这里我们不过多展开了， 不过大家知道有这么一个事就行。

这里主要说的是， agents.defaults 这个层级，描述的是全局 agent 默认配置， 就是如果你自定义的 agent 没有在进行特殊配置， 就会默认使用这里的配置。当然， 如果你初次使用 OpenClaw 大概率你只会接触这个默认 agent， 那就可以暂时忽略这个 defaults 的含义。

配置文件的备份机制

还有一个可以和大家提一下的，就是你运行一段时间后，你可能会看到好几个这样的文件：

除了我们的 openclaw.json 主配置之外，还有好几个 bak 文件。 这实际上是 OpenClaw 的一个循环备份机制，它会在我们每次修改配置文件后，轮转式的把最近的几个历史版本放到这些文件中。

之所以提一下，就是大家知道这些文件不是没用的垃圾就好。 如果你当前的配置文件出错了，可以直接从这几个文件中恢复。

这次就和大家聊这么多，找时间还会继续分享自己的一些使用体验，希望对你有帮助。