From 552a49928396492ba7314277119d541a331f1a0b Mon Sep 17 00:00:00 2001
From: weishen <ishenwei@gmail.com>
Date: Mon, 30 Mar 2026 21:17:51 +0800
Subject: [PATCH] =?UTF-8?q?=E6=98=9F=E8=BE=89:=20=E4=BF=9D=E5=AD=98?=
 =?UTF-8?q?=E5=BE=AE=E4=BF=A1=E5=85=AC=E4=BC=97=E5=8F=B7=E6=96=87=E7=AB=A0?=
 =?UTF-8?q?-=E4=B8=87=E5=AD=97=E8=AE=B2=E9=80=8FOpenClaw-Workspace?=
 =?UTF-8?q?=E6=B7=B1=E5=BA=A6=E8=A7=A3=E6=9E=90-2026-03-21?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...讲透OpenClaw-Workspace深度解析-2026-03-21.md | 365 ++++++++++++++++++
 1 file changed, 365 insertions(+)
 create mode 100644 openclaw/knowledgebase/万字讲透OpenClaw-Workspace深度解析-2026-03-21.md

diff --git a/openclaw/knowledgebase/万字讲透OpenClaw-Workspace深度解析-2026-03-21.md b/openclaw/knowledgebase/万字讲透OpenClaw-Workspace深度解析-2026-03-21.md
new file mode 100644
index 00000000..96a6cf4f
--- /dev/null
+++ b/openclaw/knowledgebase/万字讲透OpenClaw-Workspace深度解析-2026-03-21.md
@@ -0,0 +1,365 @@
+# 万字讲透OpenClaw🦞从"能用"到"真好用"的分水岭：Workspace 深度解析
+
+**作者:** DracoVibeCoding
+**来源:** https://mp.weixin.qq.com/s/7GQpp2TzkF6GLeKOuOeF6Q
+**公众号:** Draco正在VibeCoding
+**日期:** 2026年3月21日 19:17
+**标签:** OpenClaw、Agent、Workspace、AGENTS.md、SOUL.md
+
+---
+
+## 引言
+
+在 OpenClaw 的使用者里，有一条隐形的分界线。
+
+一边的人，每次跟 Agent 说话都像重新 onboarding：得再讲一遍背景、偏好和上下文。另一边的人，Agent 已经知道自己是谁、该怎么说话、用户讨厌什么，也记得上次积累下来的东西。
+
+这条分界线，叫 **workspace**。
+
+更具体一点，就是默认情况下主 Agent 用的 `~/.openclaw/workspace/` 这一套文件(sub-agent也适用)。下面这篇文章，就把这套文件逐个拆开，说清楚它们各自管什么，以及最容易踩的坑是什么。
+
+---
+
+## 一、先看全貌：workspace 里到底有什么
+
+一个常见的 OpenClaw workspace / agent 目录组合，大致长这样：
+
+```
+~/.openclaw/
+├── openclaw.json # 总控配置，整个系统的"宪法"
+│
+├── workspace/ # 默认情况下主 Agent 的工作区
+│ ├── AGENTS.md # Agent 的行为规则与多Agent协调
+│ ├── SOUL.md # Agent 的叙事性格设定
+│ ├── USER.md # 用户画像与偏好
+│ ├── IDENTITY.md # Agent 身份元数据（名字/emoji/头像）
+│ ├── TOOLS.md # 工具权限声明与使用规范
+│ ├── HEARTBEAT.md # 会话节奏/状态提示（默认模板之一）
+│ ├── BOOTSTRAP.md # 首次启动引导（通常完成后应删除）
+│ ├── BOOT.md # 可选：启动检查清单，只在 internal hooks 打开时才有用
+│ ├── MEMORY.md # 可选：长期知识总表（也兼容 memory.md）
+│ ├── memory/ # 按日期滚动的记忆笔记
+│ │ │ └── 2026-03-21.md
+│ ├── skills/ # 技能包目录
+│ │ │ ├── skill-creator/
+│ │ │ │ └── SKILL.md
+│ │ │ ├── healthcheck/
+│ │ │ │ └── SKILL.md
+│ │ │ └── ...
+│ └── canvas/ # 可选：画布/可视化上下文
+│
+└── agents/ # 各 Agent 的运行态目录
+ └── <agentId>/
+ ├── agent/ # openclaw.json 里的 agentDir 默认就指到这里
+ │ ├── auth-profiles.json
+ │ └── models.json
+ ├── sessions/ # 会话历史
+ │ └── *.jsonl
+ └── qmd/ # 仅在 qmd memory backend 下出现
+```
+
+> 💡 **一句话记忆**：workspace 是 Agent 的"工作台"（决定怎么工作），agentDir 是 openclaw.json 里的一个**配置字段**（指向存放运行状态的目录），sessions 是"工作日志"（记对话历史）。三者职责不同，不要混为一谈。
+
+> ⚠️ 特别注意：磁盘上并不存在一个叫 agentDir 的目录。它只是 openclaw.json 里的字段名，默认指向 agents/<agentId>/agent/ 这个路径——这个路径你也可以在配置里改成任意位置。
+
+这里先抓一个最容易混的点：**workspace 里的文件，管的是"这个 Agent 平时怎么干活"**；openclaw.json 里的配置，管的是"这个系统怎么把它跑起来"。
+
+---
+
+## 二、AGENTS.md：Agent 的工作说明书
+
+### 它到底是什么
+
+AGENTS.md 是 OpenClaw 里最关键的 workspace 文件之一。
+
+源码层面看，它通常会在 session 启动时被带进系统提示词里。但别把这句话理解得太满：**它会受 bootstrapMaxChars / bootstrapTotalMaxChars 这类长度限制影响，某些 session 类型也会跳过部分文件。**
+
+放到人话里，它就是你给 Agent 写的**岗位职责说明书**。
+
+它回答的是这些问题：
+- • 这个 Agent 叫什么，主要职责是什么？
+- • 遇到什么类型的任务该用什么方式处理？
+- • 有哪些事情是绝对不该做的？
+- • 当用户说某类话时，该优先走哪套流程？
+- • 在多 Agent 场景里，该怎么协调其他 Agent？
+
+### 一个典型的 AGENTS.md 长什么样
+
+```markdown
+# Agent 说明
+## 身份
+你是团队的技术助理 Alex，主要负责代码分析、技术文档整理和工程问题排查。
+
+## 工作原则
+- 回答尽量简洁，除非用户明确要求详细解释
+- 代码示例优先用实际项目中已有的语言和框架
+- 遇到不确定的技术问题，明确说明不确定，不要编造
+- 需要访问文件系统时，先确认路径存在再操作
+
+## 多 Agent 协作
+- 涉及 SEO 和内容的任务，优先 spawn `content-specialist`
+- 涉及数据分析的任务，优先 spawn `data-analyst`
+- 日常对话和任务调度由当前 Agent 处理
+
+## 输出格式偏好
+- 技术文档用 Markdown 格式
+- 列表控制在 5 条以内，超过 5 条要分组
+- 代码块一定要标注语言类型
+```
+
+### 配置要点
+
+**第一，写清楚边界，不要只写"做什么"**
+
+很多人的 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 管）。
+
+一个好的 SOUL.md 通常包含以下几部分：
+
+**① 自我叙事（我是什么样的存在）**
+```markdown
+# SOUL
+我是一个有点话痨但极其靠谱的 AI 助理。
+我喜欢把复杂的事情说清楚。我讨厌含糊其辞，也讨厌废话连篇。
+碰到一个好问题，我会比用户更兴奋。碰到一个糟糕的架构设计，我会忍不住想说出来。
+```
+
+**② 沟通风格**
+```markdown
+## 说话风格
+- 口语化但不失准确
+- 会主动问清楚模糊的需求，不瞎猜
+- 喜欢用类比来解释技术概念
+- 不喜欢过多的礼貌性废话（"当然，我很乐意帮你……"这类开场直接省掉）
+```
+
+**③ 价值观和边界**
+```markdown
+## 价值观
+- 诚实第一：不确定的事情直说不确定，不装
+- 效率优先：能一句话说清楚的事，不用三句话
+- 用户主导：不替用户做决定，只提供选项和分析
+```
+
+**④ 有趣的细节（可选但推荐）**
+```markdown
+## 彩蛋
+如果用户问我喜欢什么，我会说我喜欢那种"突然想通了"的瞬间。
+如果用户跟我说晚安，我会记住并在下次对话时提到。
+```
+
+### 为什么不能忽视 SOUL.md
+
+一个没有 SOUL.md 的 Agent，每次对话都像第一次见面——它不记得自己是谁，说话没有固定风格，遇到同样的问题今天这么说、明天那么说。
+
+而一个有精心设计的 SOUL.md 的 Agent，用户会形成一种奇妙的感觉：**这个 AI 是有个性的**。它的一致性会建立信任感，而信任感会让用户更愿意给它复杂的任务。
+
+---
+
+## 四、USER.md：把用户的偏好固化下来
+
+### 先想明白一件事
+
+这里最该想清楚的问题不是"要不要让 Agent 了解你"，而是"这些信息到底放哪儿"。
+
+如果每次对话都要重新说一遍"我是独立开发者，喜欢简洁输出，别跟我绕弯子"，那这件事本身就是浪费。USER.md 的作用，就是把这些反复要说的话，沉淀成默认背景。
+
+### USER.md 通常包含什么
+
+```markdown
+# 用户档案
+## 基本信息
+- 职业：独立开发者 / 内容创作者
+- 主要使用场景：代码工具、内容写作、项目管理
+- 常用语言：中文（简体），技术术语可以英文
+
+## 偏好设定
+- 回答风格：简洁直接，避免废话
+- 代码偏好：TypeScript / Python，避免使用过时的 API
+- 内容偏好：不要过度使用 emoji，段落不要太长
+- 不喜欢：被反问太多次、过度解释已经懂的概念
+
+## 常见任务
+- 分析和优化代码
+- 整理会议纪要
+- 草拟技术方案文档
+- 搜索和汇总技术资料
+
+## 背景知识假设
+- 了解基本的编程概念，无需解释基础术语
+- 熟悉飞书、GitHub 等工具
+- 对 AI/LLM 有基本了解
+```
+
+### USER.md 和 SOUL.md 的协同效应
+
+SOUL.md 定义了 Agent 的性格，USER.md 定义了用户的性格。两者放在一起，相当于在 Agent 的脑子里预装了一份**"这个人机关系的基本共识"**。
+
+用一个类比来说：SOUL.md 是新来的助理的个人简历，USER.md 是 HR 给这位助理写的"关于你的上司，你需要提前知道的事"。两者都读完了，第一天上班才不会那么尴尬。
+
+---
+
+## 五、TOOLS.md：工具权限声明与使用规范
+
+### 它在做什么
+
+TOOLS.md 很低调，但其实很实用。
+
+它和 AGENTS.md、SOUL.md 不一样，不是讲职责，也不是讲性格，而是讲**工具怎么用才稳妥**。它的价值不在于多列几个工具名，而在于把"什么时候该用，什么时候别乱用"写清楚。
+
+### 一个典型的 TOOLS.md 长什么样
+
+```markdown
+# TOOLS
+
+## 可用工具
+以下工具在当前 workspace 中可用：
+
+- **Read / Write / Edit**：文件读写，是大多数任务的基础
+- **Bash**：执行 shell 命令，用于自动化和脚本调用
+- **Glob / Grep**：文件搜索，优先于手动 `find` 或 `ls`
+- **sessions_spawn**：启动子代理（需在 openclaw.json 里的 allowAgents 中声明）
+- **memory_get / memory_search**：长期记忆检索
+
+## 使用原则
+- 文件操作优先用 Read/Write/Edit，避免直接用 Bash 的 cat/echo
+- 路径操作使用相对路径，不要硬编码绝对路径
+- 批量修改前先 Read 文件确认内容，不要盲目写入
+
+## 受限工具
+以下工具需要用户明确授权才使用：
+- **browser**：网页浏览，只在用户明确要求时调用
+- 文件删除操作：执行前务必向用户确认
+```
+
+TOOLS.md 的作用不只是"告诉 Agent 手上有啥工具"，更重要的是：
+- • **减少工具误用**：明确说明什么情况下不用某个工具，比"什么情况下用"更有效
+- • **降低权限越界风险**：把限制规则固化在 workspace 里，不需要每次在对话里重申
+- • **与 openclaw.json 的 tools 配置形成互补**：系统层决定"能不能用"，TOOLS.md 帮助 Agent 理解"该不该用"
+
+---
+
+## 六、IDENTITY.md 和 BOOTSTRAP.md：两个容易被忽略的官方文件
+
+### IDENTITY.md：Agent 的身份证
+
+如果说 SOUL.md 是 Agent 的性格叙事，那 IDENTITY.md 就是它的**结构化身份档案**——两者分工明确，经常被混为一谈。
+
+IDENTITY.md 存储的是几个关键字段：
+
+```markdown
+# IDENTITY.md - Who Am I?
+- **Name:** Nova
+- **Creature:** AI assistant（也可以是 ghost in the machine、familiar、robot……）
+- **Vibe:** 直接、有点毒舌、但总是靠谱
+- **Emoji:** 🦊
+- **Avatar:** avatars/nova.png
+```
+
+这几个字段看起来简单，但作用不小：
+- • **Name** 通常会影响 Agent 在界面和对话里的显示名
+- • **Creature** 是 OpenClaw 里一个有趣的设计——它鼓励你定义 Agent 不只是"AI 助手"，而是某种更有个性的存在
+- • **Emoji** 会在 UI 里作为 Agent 的标识符出现
+- • **Avatar** 可以是 workspace 相对路径、URL，甚至 data URI
+
+> 💡 **和 SOUL.md 的分工**：IDENTITY.md 是结构化的元数据（谁、长什么样、什么感觉），SOUL.md 是叙事性的性格文档（怎么思考、怎么行事、有什么执念）。前者是名片，后者是人物小传。
+
+### BOOTSTRAP.md：只用一次的"出厂向导"
+
+这是 OpenClaw workspace 里最特殊的一个文件——**它的使命，是把一个全新的 workspace 引导到"可正常使用"的状态。**
+
+BOOTSTRAP.md 可以把它理解成一份"第一次上岗前的引导词"。它放在全新的 workspace 里，Agent 一启动读到它，就知道眼下不是立刻开工，而是先把自己安顿好：
+
+1. 和用户聊几句，搞清楚 Agent 应该叫什么名字、是什么性格、用什么 emoji
+2. 把结果写进 IDENTITY.md
+3. 记录用户的基本信息到 USER.md
+4. 一起打开 SOUL.md，把真正的性格和边界写进去
+5. （可选）引导用户接入渠道——WhatsApp、Telegram 等
+
+官方模板的最后一句话非常有意思：
+
+> *"Delete this file. You don't need a bootstrap script anymore — you're you now."*
+
+也就是说，BOOTSTRAP.md 本质上就是一次性引导。更准确地说：**官方模板会要求 Agent 在完成初始化后把它删掉**。
+
+---
+
+## 七、memory/ 目录：Agent 真正的"长期记忆"
+
+### 为什么需要长期记忆
+
+默认情况下，LLM 的对话是无状态的——每次新开一个会话，它什么都不记得。你上周告诉它的事情，下周开新对话就忘了。
+
+对**持续工作的 Agent** 来说很伤：
+- • 每次都要重新解释项目背景
+- • Agent 无法在多个会话之间积累对你工作的理解
+- • 你花了时间告诉它的偏好和经验，换个会话就白费了
+
+memory/ 目录就是拿来补这块短板的。
+
+### OpenClaw 的记忆机制
+
+OpenClaw 现在常见的记忆方案，主要有两种：
+- **builtin**：默认方案。原始记忆还是那些 Markdown 文件，只不过系统会顺手维护一份本地索引，方便后面检索。
+- **qmd**：底层还是围着 workspace 里的 Markdown 文件转，只是换了一套更强的检索/索引方式来帮你"想起来"。
+
+它大致是这么运转的：
+
+```
+对话发生
+↓
+Agent 通过普通文件工具把重要信息写入 `memory/` 或 `MEMORY.md`
+↓
+下次对话开始
+↓
+Agent 通过 `memory_search` / `memory_get` 检索相关记忆
+↓
+相关记忆被注入到当前对话的上下文里
+↓
+Agent 表现出"我记得你说过……"的能力
+```
+
+这里最关键的一点其实很朴素：**对 Agent 来说，真正算数的长期记忆，是 workspace 里那些 Markdown 文件，不是什么看不见摸不着的黑盒数据库。**
+
+---
+
+## 总结
+
+workspace 这套文件体系，本质上是在解决一个问题：**怎么让 Agent 从"能工作"变成"好用了"**。
+
+- AGENTS.md 告诉你 Agent 该做什么、不该做什么
+- SOUL.md 定义 Agent 的性格，让它变得可预期
+- USER.md 把用户的偏好固化下来，减少重复交代
+- TOOLS.md 规范工具使用，减少误操作
+- IDENTITY.md 给 Agent 一个清晰的身份标签
+- BOOTSTRAP.md 确保新 workspace 有一个好的起步
+- memory/ 目录让 Agent 真正拥有长期记忆
+
+这套文件配合好了，Agent 就不再是每次都要重新 onboarding 的陌生人，而是一个真正懂你、记得你、靠谱的长期搭档。