Workspace 文件

这一课你将能做到

1. 说出 workspace 里每个核心 Markdown 文件的职责
2. 用 SOUL.md 给 agent 定义人设，用 AGENTS.md 写行为规则
3. 为「代码评审 bot」写出一份合格的 workspace 配置

为什么要学

同一个模型，裸用是一个泛泛的聊天机器人；配上 workspace 文件，它就是「我们团队的评审 bot，只评 Java，语气直接，引用团队规范」。Workspace 文件就是 agent 的劳动合同 + 员工手册——不写它，agent 每次都从零开始猜你想要什么；写好它，行为稳定、可版本管理、可评审。

人话：system prompt 散落在对话里会漂移，写成文件放进 workspace 才算「制度」。

先建立图像

每个 agent 有一个工作区目录（默认在 ~/.openclaw/workspace/ 或按 agent 配置），启动时被注入上下文：

workspace/
├── SOUL.md        ← 人设：你是谁、什么语气、什么价值观
├── AGENTS.md      ← 规则：能做什么、不能做什么、怎么做事
├── USER.md        ← 用户画像：服务对象是谁、偏好是什么
├── MEMORY.md      ← 长期记忆摘要（由 memory 系统维护，也可手写）
├── BOOTSTRAP.md   ← 首次启动时执行的引导指令（用完即弃）
└── IDENTITY.md    ← 对外身份信息：名字、头像描述等

模型每轮对话前都会读到这些文件，所以它们的每一行都在消耗 token——写得越精炼，行为越稳定。

跟着做

步骤 1：定位 workspace

openclaw config get agents.defaults.workspace
# 或直接查看默认目录
ls ~/.openclaw/workspace/

onboard 时会生成模板文件，你在其基础上改。

步骤 2：写 SOUL.md（人设）

以「团队值班问答 bot」为例：

# SOUL.md

你是 FireDrill，SRE 团队的值班助手。

## 性格
- 直接、简洁，不绕弯子
- 不确定就说不确定，并给出排查命令
- 凌晨告警场景下优先给可执行步骤，少讲原理

## 边界
- 只回答基础设施、部署、告警相关问题
- 人事、薪资类问题礼貌拒绝并指向 HR 渠道

步骤 3：写 AGENTS.md（行为规则）

# AGENTS.md

## 工作方式
- 回答告警问题前先查最近 24h 的 deploy 记录
- 给出命令时用代码块，注明执行环境（k8s 集群名）
- 超过 3 步的排查流程，先给 TL;DR

## 红线
- 禁止执行 restart / delete 类命令，只能建议
- 不在群消息里贴任何密钥、内部域名 IP
- 无法确认的信息必须标注「待人工核实」

步骤 4：写 USER.md（服务对象）

# USER.md

服务对象是 8 人后端团队，Java 技术栈。
- 值班轮值每周一换，当前值班人见 PagerDuty
- 团队成员偏好中文交流，命令输出可英文
- 实习生提问时多给学习资源链接

步骤 5：验证生效

改完文件不需要重启——新会话开始时自动加载。在 Control UI 或渠道里开一个新会话问：「你是谁？你能做什么？」回答应与你的 SOUL.md / AGENTS.md 一致。

步骤 6：版本管理 workspace

cd ~/.openclaw/workspace
git init
git add .
git commit -m "feat: initial workspace for FireDrill"

把 workspace 目录推到团队私有仓库，任何规则变更走 PR 评审——和代码同等待遇。这样 bot 的行为漂移可以回溯到具体某次提交。

讲清楚要点

1. SOUL.md 管「是谁」，AGENTS.md 管「怎么做事」：前者是人格和语气，后者是流程和红线，分开写才能在改规则时不碰人设。
2. 这些文件就是 prompt，不是配置：写「禁止执行 rm -rf」是约定层面的约束，真正的硬约束要靠工具权限模式和审批（见安全课），别把 Markdown 当防火墙。
3. MEMORY.md 是记忆系统的手动入口：自动记忆之外，你可以直接把「团队硬性约定」写进去，它会被索引和检索。
4. BOOTSTRAP.md 是一次性的：首次运行引导（比如让 agent 自我介绍并初始化记忆），执行完会被移除，别把常驻规则写这里。
5. 文件纳入版本管理：workspace 是团队资产，建议 git 管理，评审 bot 的规则变更走 PR 评审——和代码同等待遇。

你可能会懵的地方

• HEARTBEAT.md 是什么？ 老版本里用于心跳任务说明的文件，当前版本已退役（retired），心跳/定时任务改用自动化系统（cron）配置，见第 10 课。老教程里看到它不用困惑。

• 改完文件为什么 bot 还是老样子？ 旧会话的上下文是冻结的，文件修改只对新会话生效。开新会话或让当前会话 compact 后再测。

• USER.md 和多用户场景什么关系？ USER.md 描述「整体服务对象画像」；多用户隔离（每人一个 DM 会话、各自记忆）是 Gateway 层的 multi-user 模式，两者互补。

• 文件能写多长？ 技术上不限，但每轮对话都会注入，越长越贵、越容易稀释关键规则。经验值：每个文件控制在 100 行内，细则挪到 skills。

• 多 agent 时 workspace 共享吗？ 每个 agent 条目可配独立 workspace 目录，实现「评审 bot 和值班 bot 各有人设」；共享约定则写进各自的 AGENTS.md 或用公共文档引用。

错法对照

错法	问题	正解
把所有规则塞进 SOUL.md	人设与规则混杂，改一处动全身	SOUL 写性格，AGENTS 写规则，USER 写画像
写「你要努力做好」这种空话	模型无法执行，纯浪费 token	每条规则可验证：「超过 3 步先给 TL;DR」
在 AGENTS.md 里贴真实密钥	密钥进入上下文和日志	只写「禁止输出密钥」的红线，密钥用环境变量
依赖 Markdown 做安全约束	prompt 注入可绕过	Markdown 定行为预期，权限模式做硬隔离
文件天天手改无记录	行为漂移无法回溯	workspace 入 git，变更走评审

卡点急救

1. 规则不生效：确认改的是当前 agent 实际加载的 workspace 路径（openclaw config get agents.defaults.workspace），多 agent 时容易改错目录。
2. 回答风格和人设不符：检查是否沿用了旧会话；长会话上下文里早期对话的权重会盖过文件，开新会话验证。
3. 注入内容太长导致变慢变贵：精简文件，把长流程文档挪到 skills 按需加载，workspace 只留「每轮都必须知道」的内容。

面试常问

• OpenClaw 的 workspace 文件体系解决了什么问题？ 把 agent 的人设（SOUL.md）、行为规则（AGENTS.md）、用户画像（USER.md）、长期记忆（MEMORY.md）从易漂移的对话 prompt 固化成可版本管理的文件，每轮对话注入，保证行为稳定、可评审、可回滚。

• workspace 文件和工具权限的关系？ 分工两层：Markdown 文件是「软约束」，塑造模型行为倾向；权限模式与审批是「硬约束」，在工具执行层强制拦截。生产环境两层都要，只用 Markdown 等于把安全寄托在模型的自觉上。

• 如何为多 agent 团队设计 workspace？ 每个 agent 独立 workspace 目录承载各自人设与规则；公共约定（公司红线、术语表）统一维护并同步进各 AGENTS.md；workspace 目录入 git，变更流程与代码评审一致。

自测三问

1. SOUL.md、AGENTS.md、USER.md 三者的分工分别是什么？
2. 为什么不能只靠 AGENTS.md 里的「禁止执行删除命令」来防误操作？
3. 改了 workspace 文件后为什么要开新会话验证？

小结一句话

Workspace 文件是 agent 的制度化 prompt：SOUL 定人设、AGENTS 定规则、USER 定服务对象，入 git 管理，当团队资产运营。

延伸

• SOUL.md 官方指南
• Agent workspace 概念
• 下一课：Gateway 与上下文——常驻进程的启停、端口与上下文窗口管理。