OpenClaw 配置实战：openclaw.json、workspace、tool policy 怎么配

AI 推荐

适合读者：已经能跑通 OpenClaw，但想把默认配置收紧成长期可维护形态的工程师。

预计阅读：6 分钟

你将看到：

•openclaw.json 决定的是运行边界，不只是参数表。

•agents.defaults、workspace 和 tools.profile 要先收口，再逐步放权。

•先有安全默认值，再加 channels、automation 和 plugin，系统才不会越跑越乱。

头图，适合正文开头和封面横图裁切。

核心示意图，帮助读者快速抓住本篇结构。

很多人把前几篇跑通之后，会立刻产生一种错觉：

系统既然已经能跑，配置可以以后再慢慢补。

这恰好是 OpenClaw 最容易被配乱的阶段。

如果你已经按前几篇做到了下面这些事情：

• 本地 dashboard 能用

• 至少已经接通了一个真实消息入口

• 也大概知道 Gateway、channel、Control UI 是怎么协同的

因为 ~/.openclaw/openclaw.json 不是一个附属文件，而是：

• Gateway 的入口边界

• Agent 的默认运行边界

• Tools 的权限边界

• Channels 的触发边界

这一篇不打算带你把配置项背下来，而是只解决一个更现实的问题：

在你已经跑通第 1 到第 3 篇之后，下一步到底该先改哪几项配置。

一、新手先只管 5 件事，不要试图一次配完

官方配置参考非常长，因为它覆盖了：

• channels

• agents.defaults

• agents.list

• tools

• sandbox

• hooks

• cron

• models

• plugins

• gateway

但对刚跑通前几篇的人来说，第一阶段其实只需要先盯住 5 件事：

1. 默认工作目录在哪

2. 默认模型是谁

3. 工具权限先开到什么程度

4. Gateway 只绑定本机还是暴露出去

5. 通道入口到底放多大

只要这 5 件事是清楚的，系统就已经有了第一层稳定边界。

二、先别想把 openclaw.json 一次配完

这意味着一件事：

OpenClaw 的配置不是“一张表”，而是一组边界合同。

更好的方法不是一次把所有块写满，而是先把三个核心面配对：

1. Agent 默认值

2. Channel 入口策略

3. Tool policy

只要这三个面是清楚的，系统就已经有了可运行的边界。

三、第一层：先配 Agent 默认值

官方配置参考里，agents.defaults 是最值得先看的块，因为它决定了每个 agent 没有单独覆盖时的默认行为。

这里最重要的几个字段是：

• workspace

• repoRoot

• skipBootstrap

• model

• heartbeat

• sandbox

其中第一阶段最值得先定住的是：

{

agents: {

defaults: {

workspace: "~/.openclaw/workspace",

userTimezone: "Asia/Shanghai",

model: {

primary: "openai/gpt-5.2-mini"

}

}

}

}

这段配置的意义不是“够高级”，而是让系统先回答三个问题：

1. 你的工作目录在哪

2. 你的时间语义按哪个时区理解

3. 你的默认模型是谁

只要这三件事没有定住，后面很多问题都会看起来像模型问题，实际上只是运行边界没定清楚。

四、workspace 不是装饰项，它决定 Agent 的世界从哪开始

官方文档把 agents.defaults.workspace 的默认值写得很明确：

~/.openclaw/workspace

同时，它还把 bootstrap 文件也讲得很明确：

• AGENTS.md

• SOUL.md

• TOOLS.md

• IDENTITY.md

• USER.md

• HEARTBEAT.md

• BOOTSTRAP.md

这意味着 OpenClaw 不是只靠聊天记录在运行，它还会把一部分稳定上下文从 workspace 注入进去。

所以这里最常见的错误不是“不会配”，而是：

1. 一开始就把 workspace 放到一个过大的目录

这样会让系统提示词和上下文边界变得模糊。

2. 还没理解 bootstrap，就先开 skipBootstrap: true

这个字段当然有用，但更适合你已经知道自己为什么不要默认 bootstrap 的时候再开。

3. 把 repoRoot 和 workspace 混成同一个概念

官方文档里已经区分得很清楚：

• workspace 是 Agent 的工作目录和上下文起点

• repoRoot 更多是用于运行时环境识别和提示

它们可以相同，但你最好知道自己为什么让它们相同。

五、第二层：先用 profile，再谈 allow / deny

OpenClaw 的 tool policy 不是“有没有权限”这么简单，而是分层收口的。

官方配置参考里有一个很实用的字段：

{

tools: {

profile: "coding"

}

}

文档给出的 profile 语义非常直白：

• minimal

• coding

• messaging

• full

这就意味着，第一阶段最稳的做法不是一开始手写几十个 allowlist，而是先选一个合理 profile，再补 deny。

例如：

{

tools: {

profile: "coding",

deny: ["browser", "canvas"]

}

}

这类配置比“全开再慢慢关”稳得多。

六、真正该记住的是：deny wins

官方配置参考把这一点写得很清楚：

tools.allow / tools.deny 是全局策略，而且 deny 优先。

这件事很重要，因为很多人会误以为：

• allow 写了就一定能用

• agent 级别 allow 会覆盖全局 deny

其实更稳的理解是：

1. 先用 profile 给一个基础能力面

2. 再用 allow 精确打开

3. 最后用 deny 收紧真正不想碰的面

尤其是下面这些能力，建议尽早想清楚：

• 浏览器类能力

• 画布类能力

• 直接执行类能力

• elevated mode

不要等系统接到真实群聊或 webhook 再来想。

七、per-agent 覆盖才是配置真正开始“长出结构”的地方

当你开始进入多 Agent 阶段时，agents.list[] 才会真正变得重要。

这时配置不再只是“全局默认值”，而是：

• 某个 agent 的独立 workspace

• 某个 agent 的独立 tool allowlist

• 某个 agent 的独立 model / heartbeat / sandbox

所以配置的学习顺序应该是：

1. 先学 agents.defaults

2. 再学 agents.list

3. 最后再学 bindings 怎么把消息路由到不同 agent

不要反过来。否则你会过早把多 Agent 变成配置迷宫。

八、Channel 配置不是“接账号”，而是定义消息触发边界

官方配置参考和示例都在强调一件事：

• DM policy

• group policy

• requireMention

• allowFrom

• secure DM mode

这些字段的本质都不是“体验优化”，而是边界配置。

例如在多人 DM 场景下，官方示例明确建议：

{

session: { dmScope: "per-channel-peer" }

}

它解决的问题不是 UI，而是不同 sender 不应该共享同一条上下文。

所以更实际的配置顺序是：

1. 先把通道接通

2. 先配 dmPolicy

3. 再配 group requireMention

4. 多人 DM 再考虑 dmScope

九、一个适合起步的“最小安全默认配置”长什么样

如果你现在只是想先把系统配稳，我会建议从这类骨架开始：

{

agents: {

defaults: {

workspace: "~/.openclaw/workspace",

userTimezone: "Asia/Shanghai",

model: {

primary: "openai/gpt-5.2-mini"

}

}

},

tools: {

profile: "coding",

deny: ["browser", "canvas"]

},

gateway: {

mode: "local",

bind: "loopback",

port: 18789

}

}

这套配置不华丽，但已经回答了最关键的三件事：

• Agent 在哪工作

• 默认模型是谁

• Gateway 对外暴露到什么程度

它比“抄一份超大配置模板”更适合第一阶段。

十、配置模式应该成套地学，不应该字段级地学

官方配置示例里，真正有价值的不是某一行，而是几个成套模式：

1. Secure DM mode

适合多人可 DM 的场景，防止上下文串线。

2. Work bot

适合工作场景，默认更强调 restricted access 和 requireMention。

3. OAuth + API key failover

适合你已经开始认真跑模型授权和回退链路时。

4. Local models only

适合你想先降低成本、控制实验环境时。

真正成熟的配置方式，不是字段堆叠，而是模式选择。

十一、给配置阶段的最小 checklist

1. workspace 已明确

2. 默认模型已明确

3. tools.profile 已明确

4. 真正不想开的工具已经写进 deny

5. Gateway 默认绑定 loopback

6. Channel 的 DM / group 边界已经写清

7. 多人 DM 场景下，已经评估 session.dmScope

十二、这一篇之后，你该建立什么认知

你应该开始把 openclaw.json 理解成：

它不是一份参数说明书，而是 OpenClaw 的运行边界声明。

真正把 OpenClaw 从“能跑的 demo”推进到“能长期维护的系统”的，往往不是多开几个功能，而是先把默认边界收紧。

边界先配清楚，后面学 multi-agent、automation、plugin 才不会一路补洞。

参考链接

• Configuration Reference： https://docs.openclaw.ai/gateway/configuration-reference

• Configuration Examples： https://docs.openclaw.ai/gateway/configuration-examples

• Security： https://docs.openclaw.ai/gateway/security

这一篇属于 OpenClaw 系列的「进阶」阶段。

上一篇：OpenClaw 架构入门：Gateway、Channel、Control UI 如何协同

下一篇：OpenClaw Skill 实战：写一个真正可用的 SKILL.md