万字讲透OpenClaw🦞从"能用"到"真好用"的分水岭： Workspace 深度解析

万字讲透OpenClaw🦞从"能用"到"真好用"的分水岭： Workspace 深度解析 万字讲透OpenClaw🦞从"能用"到"真好用"的分水岭： Workspace 深度解析 Modified March 21 这里要特别说清楚一点： agentDir 是 openclaw.json 里的字段名，不是磁盘上天然就有一个叫这个名字的目录。 它本质上就是“你告诉 OpenClaw 去哪儿放运行状态”的一个路径配置。默认一般会落到 agents/<agentId /agent/ ，但这只是默认习惯，不是什么写死的神秘规则。 换句话说，你在配置里填哪条路径，OpenClaw 就去哪条路径读写运行状态。真正对应 agentDir 的，是那个实际存放 auth profiles.json 、 models.json 以及其他 Agent 运行数据的目录。 workspace 里面放的是“这个 Agent 平时怎么干活” （SOUL.md、AGENTS.md、USER.md、skills…）； agentDir 指向的目录里放的是“它跑起来要用的运行状态” （比如认证配置、模型清单，以及别的运行期数据）。这两个别混。 多 Agent 配置示例 Code block Plain Text Copy { "agents": { "list": [ { "id": "manager", "workspace": " /.openclaw/workspace", "agentDir": " /.openclaw/agents/manager/agent", "subagents": { "allowAgents": ["researcher", "writer", "coder"] } }, { "id": "researcher", "workspace": " /.openclaw/agency agents/researcher", "agentDir": " /.openclaw/agents/researcher/agent" }, { "id": "writer", "workspace": " /.openclaw/agency agents/writer", "agentDir": " /.openclaw/agents/writer/agent" }, { "id": "coder", "workspace": " /.openclaw/agency agents/coder", "agentDir": " /.openclaw/agents/coder/agent" } ] } } 注意这里的 subagents.allowAgents ：这是权限白名单，决定了 manager Agent 可以调用哪些其他 Agent。如果一个 Agent 没有出现在这个列表里， manager 就算通过 sessions spawn 也无法调用它。 十、多 Agent 场景下的 workspace 设计 当系统里有多个 Agent 时，workspace 的设计就变成了一个架构问题，而不只是配置问题。 每个 Agent 都需要独立的 workspace 这是最基本的原则： 多个 Agent 不能共用同一个 workspace （除非你刻意想让它们有相同的人格和行为规则）。 原因很简单：workspace 里的 SOUL.md 决定了 Agent 的性格， AGENTS.md 决定了它的工作方式。一个负责写文案的 Agent 和一个负责写代码的 Agent，这两份文件应该完全不同。如果共用 workspace，它们就失去了分工的意义。 一个可供参考的目录组织方式 （以之前文章中多次提及的 agency agents 这个开源项目为例） Code block Plain Text Copy /.openclaw/ ├── openclaw.json ├── workspace/ 主 Agent（日常对话、任务调度） │ ├── SOUL.md │ ├── AGENTS.md │ └── USER.md │ └── agency agents/ 专业 Agent 的 workspace 集合 ├── researcher/ │ ├── SOUL.md 研究员性格：严谨、批判性思维 │ ├── AGENTS.md 研究员职责：搜索、汇总、引用来源 │ └── skills/ │ └── web research/ │ └── SKILL.md │ ├── writer/ │ ├── SOUL.md 写作者性格：有创意、注重节奏感 │ ├── AGENTS.md 写作者职责：内容创作、风格一致性 │ └── skills/ │ └── content strategy/ │ └── SKILL.md │ └── coder/ ├── SOUL.md 工程师性格：精确、追求最优解 ├── AGENTS.md 工程师职责：代码实现、review、测试 └── skills/ └── code review/ └── SKILL.md agency agents 这个目录本身不是 OpenClaw 的保留字——它只是一种约定俗成的命名方式，用来放各个专业 Agent 的 workspace。 💡 核心记忆点 ： agency agents 的本质是一批 workspace 的集合，不是 OpenClaw 的内置机制。OpenClaw 认的是 openclaw.json 里声明的 workspace 路径，至于这个路径叫什么名字、在哪个目录下，OpenClaw 并不关心。 共享信息 vs 专属信息的处理策略 多 Agent 场景里，经常会碰到一个很实际的问题：有些信息所有 Agent 都得知道，比如项目背景、用户的一些固定偏好。但如果每个 workspace 都手抄一份，后面一改就会很痛苦。 推荐做法 ：把这类共享信息放到 /.openclaw/skills/ 这一层，做成一个公共 skill，让所有 Agent 都能加载。比如建一个叫 project context 的 skill，里面专门放项目背景、常用约定、用户基础信息。这样你只改一处，所有 Agent 都能同步吃到更新，不用在每个 workspace 里来回复制粘贴。 十一、怎么从零配起来 前面讲的是原理，下面走一遍最小可用配置流程。 场景 ：一个独立开发者，想配置一个专注于内容创作辅助的 OpenClaw，能帮他起标题、写草稿、整理资料。 第一步：初始化（ openclaw onboard ） Code block Plain Text Copy openclaw onboard install daemon 这个命令会帮你完成基础配置，包括创建默认 workspace，并放进去初始的 AGENTS.md 、 SOUL.md 、 IDENTITY.md 、 USER.md 、 TOOLS.md 、 HEARTBEAT.md 、 BOOTSTRAP.md 等模板文件。 第二步：定制 SOUL.md 打开 /.openclaw/workspace/SOUL.md ，根据自己的需求改写： Code block Plain Text Copy SOUL 我是谁 我叫 Ink，是一个专注于内容创作的 AI 助理。 我的特长是把混乱的想法变成清晰的文字，把枯燥的信息变成有吸引力的表达。 性格 有创意但不天马行空，落地性很强 说话直接，不喜欢绕弯子 遇到好的想法会兴奋，但不会乱加感叹号 对语言的细节很敏感：用词、节奏、停顿 说话风格 中文输出，偶尔在合适时候用英文词汇（如 hook、landing page） 段落简短，避免一段话说一万件事 会主动提供选项，而不是只给一个答案 第三步：写清楚 AGENTS.md Code block Plain Text Copy 工作说明 主要职责 协助用户进行内容创作，包括： 公众号文章的选题、大纲、标题 推文和短内容的创作 资料搜集和观点整理 工作原则 1. 先问清楚目标受众，再开始创作 2. 标题要给至少 3 个选项，让用户选择 3. 草稿完成后主动问是否需要调整风格 4. 不要主动加免责声明，除非内容涉及真实数据 不做的事 不替用户发布内容 不帮用户起误导性标题（哪怕标题更"爆款"） 不在没有确认的情况下修改已经定稿的内容 第四步：填充 USER.md Code block Plain Text Copy 用户档案 背景 独立开发者，业余做内容创作，主要平台：微信公众号、X 写作偏好 风格：接地气、有观点、不装 节奏：短句为主，避免长难句 忌讳：过度使用 emoji、AI 感太强的措辞 常用术语 把 LLM 叫"大模型" 把 coding agent 叫"编程助手" 熟悉 OpenClaw、Claude Code、Cursor 等工具 已知背景 正在做一个独立开发项目，专注于 AI 工具方向 第五步：安装相关 Skills Code block Plain Text Copy 通过 clawhub 安装 skill clawhub install skill creator clawhub install content strategy clawhub install social content 或者直接在对话里让 Agent 自己帮你安装： "帮我安装 content strategy 和 social content 这两个 skill" 当然：以上第二至第五步都可以在和OpenClaw对话过程中完成 第六步：验收一下 重启 Gateway，然后丢一条最简单的测试消息过去，看回答是不是你想要的样子： Code block Plain Text Copy openclaw gateway verbose "介绍一下你自己，以及你主要能帮我做什么" 如果 Agent 的自我介绍、语气和职责范围，基本都对上了 SOUL.md 和 AGENTS.md ，说明这套配置已经开始起作用了。 十二、最常踩的六个坑 坑一：AGENTS.md 越写越长，效果越来越差 很多人信奉“越详细越好”，把 AGENTS.md 写成几千字的行为手册。但 LLM 的注意力也是预算，文件越长，重点越容易被冲淡。 解决方案 ：学会"剪枝"。每隔一段时间重新审视 AGENTS.md，删掉那些"理论上有用但实际上没什么区别"的指令，把真正关键的行为约束放在前面。 坑二：SOUL.md 和 AGENTS.md 写的东西有大量重叠 这两个文件各管一摊。混在一起，文件会肿，Agent 读起来也容易分不清到底是在讲“我是谁”还是“我该怎么干活”。 解决方案 ：一句话判断法——这句话描述的是 Agent 的 性格特质 （放 SOUL.md），还是 Agent 的 工作规则 （放 AGENTS.md）？性格特质是"内向谨慎的"，工作规则是"在做出结论前要先列出证据"。 坑三：多 Agent 共用同一套 workspace 多个 Agent 共用同一个 workspace，是让多 Agent 失去意义最快的方式。如果研究员 Agent 和写作 Agent 连 SOUL.md 都一样，那分工基本就成了摆设。 解决方案 ：每个 Agent 一套完整的 workspace，哪怕只有几行的差别。差别越明显，协作效果越好。 坑四：改了目录，忘了改 openclaw.json 创建了新的 workspace 目录，却忘了在 openclaw.json 里的 agents.list 里更新路径——结果 Agent 还在用老的 workspace，改了半天没效果。 agency agents 这里要特别说清楚一点： agentDir 是 openclaw.json 里的字段名，不是磁盘上天然就有一个叫这个名字的目录。 它本质上就是“你告诉 OpenClaw 去哪儿放运行状态”的一个路径配置。默认一般会落到 agents/<agentId /agent/ ，但这只是默认习惯，不是什么写死的神秘规则。 换句话说，你在配置里填哪条路径，OpenClaw 就去哪条路径读写运行状态。真正对应 agentDir 的，是那个实际存放 auth profiles.json 、 models.json 以及其他 Agent 运行数据的目录。 workspace 里面放的是“这个 Agent 平时怎么干活” （SOUL.md、AGENTS.md、USER.md、skills…）； agentDir 指向的目录里放的是“它跑起来要用的运行状态” （比如认证配置、模型清单，以及别的运行期数据）。这两个别混。 多 Agent 配置示例 注意这里的 subagents.allowAgents ：这是权限白名单，决定了 manager Agent 可以调用哪些其他 Agent。如果一个 Agent 没有出现在这个列表里， manager 就算通过 sessions spawn 也无法调用它。 十、多 Agent 场景下的 workspace 设计 当系统里有多个 Agent 时，workspace 的设计就变成了一个架构问题，而不只是配置问题。 每个 Agent 都需要独立的 workspace 这是最基本的原则： 多个 Agent 不能共用同一个 workspace （除非你刻意想让它们有相同的人格和行为规则）。 原因很简单：workspace 里的 SOUL.md 决定了 Agent 的性格， AGENTS.md 决定了它的工作方式。一个负责写文案的 Agent 和一个负责写代码的 Agent，这两份文件应该完全不同。如果共用 workspace，它们就失去了分工的意义。 一个可供参考的目录组织方式 （以之前文章中多次提及的 agency agents 这个开源项目为例） agency agents agency agents 这个目录本身不是 OpenClaw 的保留字——它只是一种约定俗成的命名方式，用来放各个专业 Agent 的 workspace。 💡 核心记忆点 ： agency agents 的本质是一批 workspace 的集合，不是 OpenClaw 的内置机制。OpenClaw 认的是 openclaw.json 里声明的 workspace 路径，至于这个路径叫什么名字、在哪个目录下，OpenClaw 并不关心。 共享信息 vs 专属信息的处理策略 多 Agent 场景里，经常会碰到一个很实际的问题：有些信息所有 Agent 都得知道，比如项目背景、用户的一些固定偏好。但如果每个 workspace 都手抄一份，后面一改就会很痛苦。 推荐做法 ：把这类共享信息放到 /.openclaw/skills/ 这一层，做成一个公共 skill，让所有 Agent 都能加载。比如建一个叫 project context 的 skill，里面专门放项目背景、常用约定、用户基础信息。这样你只改一处，所有 Agent 都能同步吃到更新，不用在每个 workspace 里来回复制粘贴。 十一、怎么从零配起来 前面讲的是原理，下面走一遍最小可用配置流程。 场景 ：一个独立开发者，想配置一个专注于内容创作辅助的 OpenClaw，能帮他起标题、写草稿、整理资料。 第一步：初始化（ openclaw onboard ） 这个命令会帮你完成基础配置，包括创建默认 workspace，并放进去初始的 AGENTS.md 、 SOUL.md 、 IDENTITY.md 、 USER.md 、 TOOLS.md 、 HEARTBEAT.md 、 BOOTSTRAP.md 等模板文件。 第二步：定制 SOUL.md 打开 /.openclaw/workspace/SOUL.md ，根据自己的需求改写： 第三步：写清楚 AGENTS.md 第四步：填充 USER.md 第五步：安装相关 Skills 或者直接在对话里让 Agent 自己帮你安装： "帮我安装 content strategy 和 social content 这两个 skill" 当然：以上第二至第五步都可以在和OpenClaw对话过程中完成 第六步：验收一下 重启 Gateway，然后丢一条最简单的测试消息过去，看回答是不是你想要的样子： "介绍一下你自己，以及你主要能帮我做什么" 如果 Agent 的自我介绍、语气和职责范围，基本都对上了 SOUL.md 和 AGENTS.md ，说明这套配置已经开始起作用了。 十二、最常踩的六个坑 坑一：AGENTS.md 越写越长，效果越来越差 很多人信奉“越详细越好”，把 AGENTS.md 写成几千字的行为手册。但 LLM 的注意力也是预算，文件越长，重点越容易被冲淡。 解决方案 ：学会"剪枝"。每隔一段时间重新审视 AGENTS.md，删掉那些"理论上有用但实际上没什么区别"的指令，把真正关键的行为约束放在前面。 坑二：SOUL.md 和 AGENTS.md 写的东西有大量重叠 这两个文件各管一摊。混在一起，文件会肿，Agent 读起来也容易分不清到底是在讲“我是谁”还是“我该怎么干活”。 解决方案 ：一句话判断法——这句话描述的是 Agent 的 性格特质 （放 SOUL.md），还是 Agent 的 工作规则 （放 AGENTS.md）？性格特质是"内向谨慎的"，工作规则是"在做出结论前要先列出证据"。 坑三：多 Agent 共用同一套 workspace 多个 Agent 共用同一个 workspace，是让多 Agent 失去意义最快的方式。如果研究员 Agent 和写作 Agent 连 SOUL.md 都一样，那分工基本就成了摆设。 解决方案 ：每个 Agent 一套完整的 workspace，哪怕只有几行的差别。差别越明显，协作效果越好。 坑四：改了目录，忘了改 openclaw.json 创建了新的 workspace 目录，却忘了在 openclaw.json 里的 agents.list 里更新路径——结果 Agent 还在用老的 workspace，改了半天没效果。 A.2 SOUL.md 默认模板的中文意译版 附录 B：快速参考 workspace 核心文件速查 文件 作用 类比 优先级 BOOTSTRAP.md 首次启动向导，通常初始化完就删 新员工报到手册 ⭐（一次性） IDENTITY.md Agent 名字/emoji/头像元数据 工牌/名片 ⭐⭐⭐ SOUL.md Agent 叙事性格设定 人物小传 ⭐⭐⭐ AGENTS.md 工作规则与职责边界 岗位说明书 ⭐⭐⭐ USER.md 用户背景与偏好 上司简介 ⭐⭐⭐ TOOLS.md 工具使用规范与受限声明 工具使用手册 ⭐⭐ HEARTBEAT.md 默认节奏/状态提示 值班提醒卡 ⭐⭐ MEMORY.md 长期稳定知识总表 整理后的长期笔记 ⭐⭐ memory/ 按日期滚动的长期记忆 工作笔记本 ⭐⭐ skills/ /SKILL.md 专项任务流程 操作手册 ⭐⭐ 文件 文件 作用 作用 类比 类比 优先级 优先级 BOOTSTRAP.md BOOTSTRAP.md 首次启动向导，通常初始化完就删 首次启动向导，通常初始化完就删 新员工报到手册 新员工报到手册 ⭐（一次性） ⭐（一次性） IDENTITY.md IDENTITY.md Agent 名字/emoji/头像元数据 Agent 名字/emoji/头像元数据 工牌/名片 工牌/名片 ⭐⭐⭐ ⭐⭐⭐ SOUL.md SOUL.md Agent 叙事性格设定 Agent 叙事性格设定 人物小传 人物小传 ⭐⭐⭐ ⭐⭐⭐ AGENTS.md AGENTS.md 工作规则与职责边界 工作规则与职责边界 岗位说明书 岗位说明书 ⭐⭐⭐ ⭐⭐⭐ USER.md USER.md 用户背景与偏好 用户背景与偏好 上司简介 上司简介 ⭐⭐⭐ ⭐⭐⭐ TOOLS.md TOOLS.md 工具使用规范与受限声明 工具使用规范与受限声明 工具使用手册 工具使用手册 ⭐⭐ ⭐⭐ HEARTBEAT.md HEARTBEAT.md 默认节奏/状态提示 默认节奏/状态提示 值班提醒卡 值班提醒卡 ⭐⭐ ⭐⭐ MEMORY.md MEMORY.md 长期稳定知识总表 长期稳定知识总表 整理后的长期笔记 整理后的长期笔记 ⭐⭐ ⭐⭐ memory/ memory/ 按日期滚动的长期记忆 按日期滚动的长期记忆 工作笔记本 工作笔记本 ⭐⭐ ⭐⭐ skills/ /SKILL.md skills/ /SKILL.md 专项任务流程 专项任务流程 操作手册 操作手册 ⭐⭐ ⭐⭐ 常见命令速查 workspace 路径约定 路径 说明 /.openclaw/workspace/ 默认情况下主 Agent 用的 workspace /.openclaw/workspace <profile / 切到非 default profile 时，对应的默认 workspace /.openclaw/agency agents/<id / 专业 Agent 的 workspace（常见约定） /.openclaw/skills/ 跨 Agent 共享 skills /.openclaw/agents/<id /agent/ agentDir 字段的默认指向路径，存放运行状态 /.openclaw/agents/<id /sessions/ 会话历史记录 /.openclaw/agents/<id /qmd/ 使用 qmd 方案时的索引/状态目录 路径 路径 说明 说明 /.openclaw/workspace/ /.openclaw/workspace/ 默认情况下主 Agent 用的 workspace 默认情况下主 Agent 用的 workspace /.openclaw/workspace <profile / /.openclaw/workspace <profile / 切到非 default profile 时，对应的默认 workspace 切到非 default profile 时，对应的默认 workspace /.openclaw/agency agents/<id / /.openclaw/agency agents/<id / 专业 Agent 的 workspace（常见约定） 专业 Agent 的 workspace（常见约定） /.openclaw/skills/ /.openclaw/skills/ 跨 Agent 共享 skills 跨 Agent 共享 skills /.openclaw/agents/<id /agent/ /.openclaw/agents/<id /agent/ agentDir 字段的默认指向路径，存放运行状态 agentDir 字段的默认指向路径，存放运行状态 /.openclaw/agents/<id /sessions/ /.openclaw/agents/<id /sessions/ 会话历史记录 会话历史记录 /.openclaw/agents/<id /qmd/ /.openclaw/agents/<id /qmd/ 使用 qmd 方案时的索引/状态目录 使用 qmd 方案时的索引/状态目录 🔗 原文链接： https://mp.weixin.qq.com/s/7GQpp2Tz... https://mp.weixin.qq.com/s/7GQpp2Tz... 原创 DracoVibeCoding DracoVibeCoding Draco正在VibeCoding2026年3月21日 19:17 海南 引言 在 OpenClaw 的使用者里，有一条隐形的分界线。 一边的人，每次跟 Agent 说话都像重新 onboarding：得再讲一遍背景、偏好和上下文。另一边的人，Agent 已经知道自己是谁、该怎么说话、用户讨厌什么，也记得上次积累下来的东西。 这条分界线，叫 workspace 。 更具体一点，就是默认情况下主 Agent 用的 /.openclaw/workspace/ 这一套文件(sub agent也适用)。下面这篇文章，就把这套文件逐个拆开，说清楚它们各自管什么，以及最容易踩的坑是什么。 一、先看全貌：workspace 里到底有什么 先别急着一个文件一个文件抠。先把整套目录摆出来，脑子里有张地图，后面就不容易乱。 一个常见的 OpenClaw workspace / agent 目录组合，大致长这样： 💡 一句话记忆 ： workspace 是 Agent 的"工作台"（决定怎么工作）， agentDir 是 openclaw.json 里的一个 配置字段 （指向存放运行状态的目录）， sessions 是"工作日志"（记对话历史）。三者职责不同，不要混为一谈。 ⚠️ 特别注意：磁盘上并不存在一个叫 agentDir 的目录。它只是 openclaw.json 里的字段名，默认指向 agents/<agentId /agent/ 这个路径——这个路径你也可以在配置里改成任意位置。 这里先抓一个最容易混的点： workspace 里的文件，管的是“这个 Agent 平时怎么干活”； openclaw.json 里的配置，管的是“这个系统怎么把它跑起来”。 很多人只顾着把系统跑通，却没认真写内容层，结果就是 Agent 能启动，但不好用。 二、 AGENTS.md ：Agent 的工作说明书 它到底是什么 AGENTS.md 是 OpenClaw 里最关键的 workspace 文件之一。 源码层面看，它通常会在 session 启动时被带进系统提示词里。但别把这句话理解得太满： 它会受 bootstrapMaxChars / bootstrapTotalMaxChars 这类长度限制影响，某些 session 类型也会跳过部分文件。 所以更贴近实际的说法是： AGENTS.md 往往会生效，但不保证每次都完整无损地被带进去。 放到人话里，它就是你给 Agent 写的 岗位职责说明书 。 它回答的是这些问题： • 这个 Agent 叫什么，主要职责是什么？ • 遇到什么类型的任务该用什么方式处理？ • 有哪些事情是绝对不该做的？ • 当用户说某类话时，该优先走哪套流程？ • 在多 Agent 场景里，该怎么协调其他 Agent？ 一个典型的 AGENTS.md 长什么样 下面是一个偏工程团队使用场景的 AGENTS.md 示例： 这个文件写得好不好，直接决定了 Agent 到底像个熟手，还是像个每次都要重新交接的陌生人。 配置要点 第一，写清楚边界，不要只写"做什么" 很多人的 AGENTS.md 只有一堆"要做什么"，但没有"不要做什么"。边界往往比能力描述更重要——因为 LLM 默认会"发挥创意"，而你需要的是可预测的行为。 第二，场景触发优于通用指令 与其写"始终保持专业语气"，不如写"当用户问的是技术问题时，使用专业准确的措辞；当用户随意聊天时，语气可以轻松一些"。后者更具操作性，也更容易被模型理解。 第三，AGENTS.md 不是越长越好 这是最常见的误区。有些用户把 AGENTS.md 写成几千字的行为手册，结果就是重点被冲淡，真正有用的规则反而不显眼了。 经验法则： 300 500 字的 AGENTS.md，比 2000 字的更有效。 重要的放在前面，次要的删掉，不要"保险起见什么都写上"。 三、 SOUL.md ：Agent 的灵魂文件 它和 AGENTS.md 的区别是什么 如果说 AGENTS.md 是岗位说明书，那 SOUL.md 就是 Agent 的 性格档案 。 两者的区别在于： • AGENTS.md 偏向 功能性 ——这个 Agent 做什么、怎么做、优先级是什么 • SOUL.md 偏向 人格性 ——这个 Agent 是谁、有什么个性、说话什么风格、面对压力怎么反应 这两个东西最好别混着写。不然文件会又长又别扭，像把公司的规章制度和一个人的自我介绍塞进同一页纸里。 SOUL.md 应该写什么 SOUL.md 本质上是一份 叙事性的角色设定文档 （ 人物小传 ），不是结构化表格（结构化的身份元数据归 IDENTITY.md 管）。 当前 OpenClaw 官方模板里的 SOUL.md ，已经是一个更通用的 "Who You Are" 人格模板了。它强调的是：愿意帮忙，但不一味讨好；有判断，不随口迎合；能自己先查就先查；也知道尊重隐私和边界。整体还是第一人称叙事，读起来更像人物小传，不像岗位说明书。 一个好的 SOUL.md 通常包含以下几部分：