06 · Workspace——Agent 的灵魂容器
——翔宇
要点速览
- Workspace（工作区）是 Agent（智能体）的家目录——复制这个文件夹就能克隆一个 Agent
- 7 个核心文件各有分工：SOUL（决策框架）、AGENTS（操作手册）、USER（客户档案）、IDENTITY（工牌）、TOOLS（工具手册）、HEARTBEAT（巡检表）、MEMORY（笔记本）
- SOUL.md 不是写「你是谁」，而是写「遇到障碍时怎么选」
- 最好的 SOUL.md 不超过 500 token（词元，AI 文本计量单位）——简短但约束精准
1. 一个好问题
如果让你用 7 个文件定义一个完整的 AI 员工——它的性格、职责、记忆、工具、巡检清单——你会怎么分？
这不是假设题。OpenClaw 真的这么做了。而且这个设计带来了一个惊人的特性：复制一个文件夹就能克隆一个 Agent。
2. 直觉回答：一个大文件搞定？
错误直觉
「配置不就是一个大文件吗？把所有指令写在一起不就行了？」
很多 AI 框架确实这么做——一个巨大的 System Prompt（系统提示词），塞进所有指令。但这带来三个问题：
问题一：修改成本高
你想改 Agent 的语气风格，但规则和操作手册混在一起。改一行可能影响另一段的语义。
问题二：无法选择性加载
有些信息每次都需要（身份），有些只在特定场景需要（工具手册）。一个大文件 = 全量加载 = 浪费上下文空间。
问题三：无法复用
你想创建第二个 Agent，大部分配置一样但性格不同。一个大文件 = 全部复制再改 = 版本管理噩梦。
🧠 底层逻辑
拆分的本质是「关注点分离」——每个文件只回答一个问题。改性格？改 SOUL.md。改操作规则？改 AGENTS.md。不需要在一堆指令里大海捞针。
3. OpenClaw 的解法：7 个文件，7 个角色
workspace-{id}/
├─ SOUL.md 决策框架——遇到障碍时怎么选
├─ AGENTS.md 操作手册——日常工作流程和规则
├─ USER.md 客户档案——服务对象是谁
├─ IDENTITY.md 工牌——名字、角色、表情风格
├─ TOOLS.md 工具手册——环境信息、凭证备忘
├─ HEARTBEAT.md 巡检表——定期自动检查的清单
├─ MEMORY.md 笔记本——长期记忆精选
├─ memory/ 日记忆——每天的工作日志
└─ skills/ 技能包——Workspace 级 Skill
🎯 打个比方
想象一个新员工入职。公司给他准备了：性格指南（SOUL）、岗位说明书（AGENTS）、客户资料（USER）、工牌（IDENTITY）、工具手册（TOOLS）、巡检表（HEARTBEAT）、一本空白笔记本（MEMORY）。有了这些，他第一天就能开始工作。
3.1 SOUL.md——不是「你是谁」，而是「你怎么选」
这是最容易写错的文件。
错误直觉
「SOUL.md 就是写 Agent 的自我介绍吧——'你是一个有帮助的助手'之类的。」
不是。SOUL.md 的核心不是身份描述，而是决策框架——遇到模糊情况时，Agent 怎么做选择。
五大支柱：
🔑 关键点
最好的 SOUL.md 不超过 500 token。不是因为技术限制，而是因为——如果你需要 2000 token 才能描述一个 Agent 的行为规则，说明规则太复杂了，Agent 反而会混乱。简短、精准的约束比长篇大论更有效。
好的 SOUL.md vs 坏的 SOUL.md：
🧠 底层逻辑
好的 SOUL.md 有两个特征：具体和可测试。「简洁友好」无法测试——多简洁算简洁？什么程度的友好？「回复不超过 3 段，遇到错误先说解决方案再解释原因」——这就可以测试了。
社区资源：103 个已验证的 SOUL.md 模板可以在 awesome-openclaw-agents 仓库找到，覆盖技术顾问、客服、写手等角色。
3.2 AGENTS.md——操作手册
告诉 Agent 日常怎么工作：启动流程、记忆规则、协作方式。
三条黄金规则：
- 加反循环规则——「如果你发现自己在重复同一个操作，停下来汇报」
- 加「不要做什么」——每次 Agent 犯错，立刻加一条禁止规则。负面指令比正面指令更有效
- 保持回复简短——「回复尽量简短」这句话能显著节省上下文预算
3.3 USER.md——客户档案
记录服务对象的信息。这个文件的设计意图是让 Agent 「认识」用户：
💬 说人话
USER.md 就是 Agent 的「客户档案」。销售员见客户前会翻 CRM 看客户喜好——Agent 在回复前会看 USER.md 了解你是谁。
3.4 IDENTITY.md——工牌
名称、角色描述、表情风格。这是最简单的文件——大部分只有几行。
📌 记住这点
IDENTITY.md 和 SOUL.md 的区别：IDENTITY 是「名片」（外在形象），SOUL 是「性格」（内在决策框架）。改名字改 IDENTITY，改行为规则改 SOUL。
3.5 TOOLS.md——工具手册
环境信息备忘：可用 Skill（技能插件）的使用说明、凭证位置、工具特殊配置。
🎯 打个比方
SOUL.md 是「遇到问题怎么选」（决策层面），TOOLS.md 是「遇到任务怎么做」（执行层面）。前者是管理者思维，后者是工匠手册。
TOOLS.md 适合放什么：
- 特定 Skill 的使用注意事项
- 凭证文件的路径（不是凭证本身！）
- 工具的特殊配置说明
- 常用命令的速查
3.6 HEARTBEAT.md——巡检表
心跳巡检时 Agent 要检查的清单。这个文件定义了 Agent 在「没人找它」时主动做什么。
一个典型的 HEARTBEAT.md：
## 每次心跳必做
- 检查 work/inbox/ 是否有新任务文件
- 检查今天的 memory/ 日志是否存在，不存在则创建
- 扫描最近 2 天日志，提炼重复模式到 MEMORY.md
## 轮换检查（每次做一项）
- D. 检查 MEMORY.md 是否有 [待晋升] 标记
- E. 检查 work/drafts/ 是否有未完成的草稿
- F. 检查系统状态（Gateway 版本、磁盘空间）
/图片🧠 底层逻辑
HEARTBEAT.md 把「主动性」变成了可配置的——你可以精确控制 Agent 在空闲时做什么。不同 Agent 的巡检清单完全不同：内容 Agent 检查草稿，运维 Agent 检查系统状态。
详见深度教程-08《Session 与心跳——时间的维度》。
g. MEMORY.md——长期记忆笔记本
从日志提炼出来的跨会话复用信息。这是三层记忆架构中的 Layer 2。详见深度教程-04《记忆——AI 怎么记住你》。
一个健康的 MEMORY.md 应该：
- 控制在 20-50 条记录
- 每条 1-2 句话
- 定期删除过时的记录
- 有从日志晋升上来的记录（说明 Heartbeat 在正常工作）
h. 其他目录
📌 记住这点
BOOTSTRAP.md 只在全新 Workspace 首次启动时执行。仪式完成后建议删除它——否则每次重建 Session（会话）都会重新跑一遍入职流程。设置
agent.skipBootstrap: true也能跳过。
4. 容错设计：如果缺少某个文件
💡 划重点
缺失的文件不会导致 Agent 崩溃。OpenClaw 会注入一个「缺失文件」标记——Agent 知道这个文件不存在，但能正常工作。你可以从最小配置开始，逐步添加文件。
这意味着一个合法的 Workspace 可以只有一个 SOUL.md——其余文件都不是必须的。
🎯 打个比方
新员工没有客户资料也能工作——只是不了解客户偏好。没有巡检表也能工作——只是不会主动检查。每增加一个文件，Agent 就多一层能力。
4.1 大文件处理
workspace 文件不能无限大。两个截断参数：
📌 记住这点
如果你的 SOUL.md 超过 20,000 字符，后面的内容不会被 Agent 看到。但如果你遵守 500 token 原则，这个限制永远不会触发。
4.2 Workspace 不是沙箱
错误直觉
「Agent 只能在 Workspace 目录里操作文件，出不去。」
⚠️ 这是一个重要的安全认知。
官方文档明确指出：Workspace 是 Agent 的默认工作目录（cwd），但不是硬沙箱。 工具使用相对路径时，会解析到 Workspace 下。但如果使用绝对路径（如 /etc/passwd），Agent 可以访问主机上的任何位置。
要实现真正的文件系统隔离，必须启用沙箱模式（agents.defaults.sandbox），Agent 会在独立的 Docker 容器或沙箱 workspace 中运行。
🧠 底层逻辑
这是有意设计的。Workspace 是「默认值」不是「围栏」——对于个人使用，Agent 需要访问 Workspace 之外的文件（比如你的代码仓库）。只有面向不可信用户时才需要沙箱隔离。
5. 可移植性：复制文件夹 = 克隆 Agent
Workspace 的一个关键设计特性：它是自包含的。
🧠 底层逻辑
这就是「文件即真相」设计哲学在 Workspace 层面的体现——Agent 的全部定义都在文件里，不在数据库里，不在云端。你用文件管理器就能管理 Agent，用 Git 就能版本控制。
5.1 Workspace 之外的东西
这些文件在 ~/.openclaw/ 下，不放进 Workspace：
💬 说人话
Workspace 是 Agent 的「个人空间」——性格、规则、记忆。主配置和凭证是「公司基础设施」——不跟着个人走。
6. BOOTSTRAP.md vs BOOT.md
💡 划重点
预置好的 Workspace 不想每次都走入职流程？设置
agent.skipBootstrap: true。迁移 Workspace 时特别有用——省得 Agent 每次都自我介绍一遍。
7. 设计权衡
设计权衡
一句话检验
- Workspace 是什么？ → Agent 的家目录，复制它就能克隆 Agent
- SOUL.md 写什么？ → 不是「你是谁」，而是「遇到障碍时怎么选」——决策框架
- 为什么拆成 7 个文件？ → 关注点分离——改性格不需要动操作手册，改操作手册不需要动性格
- 缺文件会崩吗？ → 不会。注入「缺失」标记，Agent 正常工作，只是少了一层能力
CC 提示词
🚀 对 Claude Code 说 帮我审查 OpenClaw Agent 的 Workspace 文件质量： - 读取 /你的路径/.openclaw/workspace/ 下的所有 .md 文件
- 检查 SOUL.md：
- 估算 token 数，是否超过 500 token
- 是否包含「决策框架」（遇到模糊时怎么选）
- 是否有具体的禁止行为清单
- 是否有「你是一个有帮助的助手」这种无效描述
- 检查 AGENTS.md：是否有反循环规则、负面指令、回复长度约束
- 列出 7 个核心文件的存在状态和大小
- 给出改进建议——哪些文件需要补充，哪些需要精简
🚀 对 Claude Code 说 帮我创建一个新的 OpenClaw Workspace： - 在 /你的路径/.openclaw/ 下创建 workspace-新名称/ 目录
- 根据以下定位生成 7 个核心文件：
- 这个 Agent 的角色是：[你的描述，比如「技术文档写手」]
- SOUL.md 控制在 500 token 以内，重点写决策框架
- AGENTS.md 包含反循环规则和负面指令
- USER.md 填入你的基本信息
- IDENTITY.md 设定名称和风格
- TOOLS.md 列出可用工具
- HEARTBEAT.md 设定巡检清单
- MEMORY.md 留空
- 创建完成后用 tree 命令展示目录结构
延伸阅读
- 翔宇版 04《核心概念深度解析》— Workspace 全节：文件一览、写作技巧、默认位置
- 翔宇版 11《系统参数深度解读》— bootstrapMaxChars、skipBootstrap 等参数详解
- 深度教程-04《记忆——AI 怎么记住你》— MEMORY.md 和 memory/ 目录的详细机制
- 深度教程-08《Session 与心跳——时间的维度》— HEARTBEAT.md 的完整设计和配置