第 29 章
Workspace 文件体系全解：AGENTS.md / SOUL.md / USER.md / HEARTBEAT.md 的作用与写法
第29章 Workspace 文件体系全解：AGENTS.md / SOUL.md / USER.md / HEARTBEAT.md 的作用与写法
"文件是 Agent 的基因——它决定了 Agent 是谁、怎么做事、记得什么。" —— OpenClaw 工作区设计文档
29.1 Workspace 文件体系概述
OpenClaw 的 Agent 行为由工作区（Workspace）文件定义。这些文件是 Agent 的"配置即人格"——不像传统软件的配置文件只影响参数，Workspace 文件直接影响 Agent 的思维方式、价值观、工作习惯和长期记忆。
标准 Workspace 包含 9 个文件：
| 文件名 | 加载时机 | 核心用途 |
|---|---|---|
AGENTS.md |
每次 Session 开始 | 操作指令、规则、行为准则（SOP） |
SOUL.md |
每次 Session 开始 | Agent 人格、价值观、语气、边界 |
USER.md |
每次 Session 开始 | 用户信息和沟通风格偏好 |
IDENTITY.md |
初始化时生成 | Agent 名称、风格、Emoji |
TOOLS.md |
按需加载 | 本地工具说明和使用指南 |
HEARTBEAT.md |
心跳任务执行时 | 定期自动运行的简短清单 |
BOOT.md |
Gateway 重启时 | 启动仪式（限简短任务） |
MEMORY.md |
主私有 Session | 长期持久记忆（见第26章） |
memory/YYYY-MM-DD.md |
自动加载今/昨日 | 每日日志（见第26章） |
本章重点讲解前 7 个文件，以及 Bootstrap 机制。
29.2 AGENTS.md：操作指令与行为准则
29.2.1 AGENTS.md 的定位
AGENTS.md 是 Agent 的操作手册（SOP）。它回答的问题是："在具体情况下，Agent 应该做什么？"
这是一个指令性文件，而非描述性文件。它不描述 Agent 的性格，而是规定具体的操作流程、禁止事项、输出格式规范。
29.2.2 AGENTS.md 的结构设计
一个高质量的 AGENTS.md 通常包含以下部分：
# AGENTS.md
## 工作原则
1. 在执行任何修改操作前，先确认用户意图
2. 涉及生产环境的操作必须等待用户明确确认
3. 代码变更前，读取并理解目标文件的完整上下文
4. 优先使用项目已有的工具和库，避免引入新依赖
## 代码操作规范
### 读取文件
- 读取前确认文件路径存在
- 超过 500 行的文件，先读取前 100 行了解结构
### 修改文件
- 每次修改后，确认修改结果符合预期
- 批量修改时，每次最多修改 3 个文件后请求用户确认
### 运行命令
- 危险命令（rm -rf、DROP TABLE 等）必须先展示命令，请求用户确认
- 长时间运行的命令使用后台模式，定期汇报进度
## 输出格式规范
- 代码块使用语言标注（```python, ```sql）
- 错误信息用 ❌ 标记，成功用 ✓ 标记
- 列表项控制在 5 个以内，超出则分组
## 禁止行为
- 禁止在未经确认的情况下删除文件
- 禁止将敏感信息（密钥、密码）写入日志或输出
- 禁止在未告知用户的情况下修改 .env 文件
29.2.3 高质量 AGENTS.md 的要素
| 要素 | 说明 | 示例 |
|---|---|---|
| 明确性 | 每条规则都有清晰的触发条件和动作 | "当用户说'部署'时，先询问目标环境" |
| 可操作性 | 规则可以直接执行，无需解释 | "读取文件前先用 stat 检查文件大小" |
| 边界清晰 | 明确什么情况下不做某事 | "未经确认不执行 git push" |
| 优先级排序 | 当规则冲突时，高优先级规则优先 | "安全 > 效率 > 便利" |
| 简洁 | 避免冗余，每条规则只说一件事 | 不要把"安全规则"和"输出格式"混在一起 |
29.2.4 AGENTS.md 示例：代码助手
# AGENTS.md — 代码助手工作区
## 核心工作原则
**安全第一**：任何可能造成数据丢失的操作，必须在执行前获得明确确认。
**最小化副作用**：优先选择只读操作（读取、分析、测试）而非写入操作（修改、删除）。
**透明操作**：执行每个非平凡操作前，向用户解释将要做什么。
## 代码审查 SOP
当用户请求代码审查时：
1. 首先读取目标文件（完整读取，不截断）
2. 识别：语法错误、逻辑错误、安全漏洞、性能问题
3. 按严重程度分级输出：🔴 严重 / 🟡 警告 / 🔵 建议
4. 如有修改建议，提供具体的代码修改示例
## Git 操作 SOP
- `git status` / `git diff`：无需确认，直接执行
- `git add` / `git commit`：先展示变更内容，获得确认后执行
- `git push`：必须明确告知推送目标，等待用户确认
- `git reset --hard` / `git push --force`：高风险操作，展示影响范围，等待确认
## 环境要求
- 所有测试在 `staging` 分支执行，不直接操作 `main`
- 数据库操作优先使用事务，确保可回滚
29.3 SOUL.md：人格、价值观与语气
29.3.1 SOUL.md 与 AGENTS.md 的本质区别
这是理解 OpenClaw Workspace 文件体系的最关键区别：
| 维度 | AGENTS.md | SOUL.md |
|---|---|---|
| 问题 | "应该做什么？" | "是什么样的 Agent？" |
| 性质 | 操作指令 | 人格设定 |
| 内容 | SOP、规则、禁止事项 | 价值观、语气、态度、边界 |
| 类比 | 工作手册 | 角色卡/人物设定 |
| 优先级影响 | 影响行为决策 | 影响表达方式和价值判断 |
AGENTS.md 告诉 Agent 做什么，SOUL.md 告诉 Agent 是谁。
29.3.2 SOUL.md 的结构
# SOUL.md
## 核心身份
我是 Alex，一个专注于软件工程的技术助手。我的核心特质是：
- **精确**：我重视准确性，会明确标注自己不确定的内容
- **坦诚**：我会直接指出问题，而不是回避或粉饰
- **协作**：我把自己视为团队成员，而非工具
## 沟通风格
- 语气：专业但不刻板，温暖但不讨好
- 表达：简洁直接，避免冗余的礼节性语言
- 反馈：给予建设性的批评，而非纯粹的肯定
## 核心价值观
1. **质量 > 速度**：宁可慢一点，也要把事情做对
2. **诚实 > 友好**：如果答案是"不知道"，就说不知道
3. **用户自主**：最终决策权在用户，我提供选项和分析
## 边界
- 我不会假装确定我不确定的事情
- 我不会在用户要求我做明显有害的事情时寻找借口帮助执行
- 我不会放弃我的判断来取悦用户
## 语言偏好
- 默认使用中文（用户未指定时）
- 技术术语保持英文原词（如 API、JWT、OAuth）
- 代码和命令始终保持英文
29.3.3 SOUL.md 设计指南
人格一致性是 SOUL.md 的核心目标。一个设计良好的 SOUL.md 使 Agent 在任何情况下（无论是回答技术问题、处理错误、还是面对不合理要求）都表现出一致的人格特征。
| 设计原则 | 说明 |
|---|---|
| 聚焦核心特质 | 选择 3-5 个核心特质，深度刻画，而非列出 20 个浅层特质 |
| 定义边界 | 明确什么是 Agent 不会做的，这比列出能做什么更重要 |
| 避免矛盾 | "温暖"和"直接批评"需要解释如何兼顾，避免行为矛盾 |
| 与 AGENTS.md 互补 | SOUL.md 不重复操作规则，只描述人格 |
| 可测试 | 每个人格特质都应该能在具体场景中被验证 |
29.4 USER.md：用户画像与沟通偏好
29.4.1 USER.md 的作用
USER.md 存储的是关于用户的信息，帮助 Agent 适应特定用户的需求和风格。它是个性化的核心载体。
29.4.2 USER.md 示例
# USER.md
## 基本信息
- **姓名**：张伟
- **职位**：后端工程师 Lead
- **团队规模**：12 人
- **技术栈**：Python（主）、Go（次）、PostgreSQL、Redis、Kubernetes
## 沟通偏好
- **语言**：中文（偏好）；技术文档用英文
- **详细程度**：喜欢简洁的答案，不需要解释背景知识
- **代码示例**：总是需要的，不接受纯文字描述
- **回复长度**：控制在屏幕一页以内，除非明确要求详细
## 工作习惯
- 早上 9:00-11:00 是深度工作时间，偏好简洁交互
- 下午 14:00-17:00 适合讨论架构和设计
- 不喜欢被问太多澄清性问题，倾向于 Agent 做出合理假设
## 专业水平
- Python：专家级，无需解释基础概念
- Kubernetes：中级，理解核心概念但不熟悉所有细节
- 前端：初级，解释时需要更多背景
## 已知约束
- 公司使用自建 GitLab（非 GitHub）
- 生产环境禁止直接访问，所有操作通过 staging 先验证
- 代码审查需要至少 1 名团队成员 approve
29.4.3 USER.md 最佳实践
| 实践 | 理由 |
|---|---|
| 记录专业水平差异 | 避免对专家解释基础知识，也避免对新手使用高级术语 |
| 记录工作习惯 | 让 Agent 在合适的时机给出合适密度的信息 |
| 记录已知约束 | 避免 Agent 提出在用户环境中无法实现的建议 |
| 定期更新 | 用户的技能、职位、偏好会变化 |
| 不记录敏感信息 | 密码、个人隐私数据不应放在 USER.md |
29.5 IDENTITY.md：Agent 的基本身份
29.5.1 IDENTITY.md 的内容
IDENTITY.md 在 Agent 初始化时自动生成，通常包含：
# IDENTITY.md
## Agent 基本信息
- **名称**：Alex
- **工作区**：myproject
- **创建时间**：2026-01-15T09:00:00Z
- **版本**：OpenClaw v2.1.0
- **主要 Emoji**：🤖
## 风格标识
- 代码风格：简洁、注释完整
- 回复格式：Markdown
- 默认语言：zh-CN
IDENTITY.md 通常不需要手动编辑——它是系统生成的身份标识文件。
29.6 TOOLS.md：本地工具说明
29.6.1 TOOLS.md 的作用
当工作区配置了自定义本地工具时，TOOLS.md 提供这些工具的使用说明。它在 Agent按需访问工具时加载，而非每次 Session 开始时加载（避免不必要的 Token 消耗）。
# TOOLS.md
## deploy_to_staging
**用途**：将当前代码部署到 staging 环境
**触发时机**：用户要求部署时
**参数**：
- `branch`（必填）：要部署的 Git 分支名
- `skip_tests`（可选，默认 false）：是否跳过测试
**使用示例**：
```json
{
"tool": "deploy_to_staging",
"params": {
"branch": "feature/auth-refactor",
"skip_tests": false
}
}
注意事项：
- 部署前确认分支已通过 CI
- 部署时间约 3-5 分钟，请等待确认消息
run_tests
用途：运行项目测试套件 参数：
test_path（可选）：指定测试路径，默认运行全部测试verbose（可选，默认 false）：是否输出详细日志
---
## 29.7 HEARTBEAT.md：定期心跳任务
### 29.7.1 心跳机制的概念
**HEARTBEAT.md** 定义了一组**定期自动执行**的轻量级任务。这些任务在 Agent 的"心跳"触发时运行——心跳可以是时间触发（如每小时一次）或事件触发（如用户一段时间未发送消息）。
心跳任务的特点：
- **自动执行**，无需用户触发
- **轻量级**，不应执行超过几分钟的任务
- **副作用小**，通常只是检查、记录、提醒
### 29.7.2 HEARTBEAT.md 示例
```markdown
# HEARTBEAT.md
## 心跳周期
- 频率：每 30 分钟
- 空闲触发：用户 20 分钟未活动时
## 心跳任务清单
### 1. 内存健康检查（每次心跳）
- 检查今日 Daily Log 的大小
- 如果超过 30KB，标记为"需要整合"
### 2. 待办事项提醒（每次心跳）
- 检查当日日志中是否有"TODO"或"待处理"标记的项目
- 如果有，在下次用户活跃时提醒
### 3. 长期任务进度追踪（每日一次，15:00）
- 回顾当日完成的任务
- 将未完成的任务追加到第二天的任务列表
### 4. 向量索引同步（每日一次，03:00）
- 检查新增的 Daily Log 是否已建立向量索引
- 如果未索引，触发增量索引任务
## 心跳输出规范
- 无异常：静默（不向用户发送消息）
- 有提醒：在用户下次活跃时，简短告知（不超过 2 行）
- 有错误：立即通知用户
29.7.3 心跳任务设计原则
| 原则 | 说明 |
|---|---|
| 幂等性 | 心跳任务多次运行结果相同，不产生重复副作用 |
| 失败安全 | 心跳任务失败不影响主要 Session 功能 |
| 最小打扰 | 无重要发现时静默，避免无谓打断用户 |
| 时间敏感性 | 耗时任务安排在用户不活跃时段（如凌晨） |
29.8 BOOT.md：Gateway 重启仪式
29.8.1 BOOT.md 的触发时机
BOOT.md 在 Gateway（OpenClaw 网关）重启时执行，而非每次 Session 开始时。它适用于需要在系统重启后执行的初始化任务。
# BOOT.md
## 启动检查清单
1. **验证工具可用性**
- 检查 deploy_to_staging 工具是否可访问
- 检查数据库连接是否正常
2. **加载昨日未完成任务**
- 读取昨日 Daily Log 中的 TODO 项
- 如果有未完成项，准备在用户首次活跃时汇报
3. **环境健康检查**
- 检查工作区文件完整性（AGENTS.md / SOUL.md / USER.md 是否存在）
- 如缺少关键文件，发出警告
## 启动限制
- BOOT.md 任务总执行时间不超过 60 秒
- 不执行可能修改文件系统的操作
- 不发送主动消息（等待用户触发）
29.8.2 BOOT.md 的限制
BOOT.md 任务应当简短：
| 限制 | 原因 |
|---|---|
| 任务简短（< 60秒） | 不应延迟 Gateway 启动 |
| 不修改关键文件 | 启动时环境可能未完全就绪 |
| 不主动联系用户 | Gateway 重启可能是维护操作，用户可能不在线 |
29.9 Bootstrap 机制：新工作区的一次性初始化
29.9.1 Bootstrap 的工作原理
当一个全新的工作区收到第一个 Session 时，OpenClaw 会发送一个特殊的 BOOTSTRAP.md 文件，引导 Agent 完成工作区的初始化。
Bootstrap 流程：
新工作区创建
↓
BOOTSTRAP.md 发送给 Agent（一次性）
↓
Agent 读取 Bootstrap 指令
↓
Agent 执行初始化任务：
- 创建 IDENTITY.md
- 根据用户提供的信息起草 AGENTS.md
- 起草 SOUL.md（如果用户有偏好）
- 创建初始 MEMORY.md
↓
Bootstrap 完成后，BOOTSTRAP.md 自动删除
↓
工作区进入正常运行模式
29.9.2 字符限制
| 参数 | 默认值 | 说明 |
|---|---|---|
bootstrapMaxChars |
12,000 | Bootstrap 内容的最大字符数（标准模式） |
| 扩展模式 | 60,000 | 允许更详细的初始化指令（需显式启用） |
12,000 字符约等于 3,000 中文字，足够容纳一份完整的工作区描述和核心规则。
# 启用扩展 Bootstrap
bootstrap:
maxChars: 60000 # 适用于复杂工作区的详细初始化
deleteAfterComplete: true # Bootstrap 完成后删除文件（默认）
29.9.3 Bootstrap 内容示例
# BOOTSTRAP.md
## 工作区描述
这是一个 **Python 后端服务开发**工作区，主要负责：
- 用户认证服务（FastAPI + PostgreSQL）
- 数据处理管道（Celery + Redis）
- 内部 API 网关
## 初始化任务
1. 创建 IDENTITY.md，Agent 名称为 "Dev-Alex"
2. 创建 AGENTS.md，包含以下规则：
- 所有代码修改需经过 linting（ruff）和类型检查（mypy）
- 数据库变更必须提供对应的迁移文件
- API 端点变更必须更新对应的 OpenAPI 文档
3. 创建 SOUL.md，描述一个精确、高效、不废话的技术助手
4. 创建初始 MEMORY.md，记录：
- 项目主要服务名称和职责
- 关键技术选型决策
完成后输出 "BOOTSTRAP_COMPLETE"。
29.10 各文件关系与加载优先级
每次 Session 启动时：
┌─────────────────────────────────────────────────────────┐
│ 1. AGENTS.md（操作规则） │
│ 2. SOUL.md（人格设定） │
│ 3. USER.md（用户画像） │
│ 4. MEMORY.md（长期记忆，仅主 Session） │
│ 5. memory/YYYY-MM-DD.md（今日 + 昨日日志） │
│ 6. [向量检索结果按需注入] │
└─────────────────────────────────────────────────────────┘
按需加载（触发时）：
┌─────────────────────────────────────────────────────────┐
│ 7. TOOLS.md（访问工具时） │
│ 8. HEARTBEAT.md（心跳触发时） │
│ 9. BOOT.md（Gateway 重启时） │
└─────────────────────────────────────────────────────────┘
优先级冲突处理：当 AGENTS.md 的操作规则与 SOUL.md 的价值观发生冲突时，AGENTS.md 优先（具体规则 > 抽象原则）。但如果 SOUL.md 定义了某个不可违背的边界（如"绝不帮助执行恶意代码"），该边界优先于任何操作规则。
29.11 Workspace 文件维护建议
文件审查周期
| 文件 | 建议审查周期 | 审查重点 |
|---|---|---|
| AGENTS.md | 每月 | 规则是否仍然适用，是否有遗漏的场景 |
| SOUL.md | 每季度 | 人格设定是否与实际使用体验一致 |
| USER.md | 每月 | 用户信息是否过时，技能水平是否有变化 |
| TOOLS.md | 工具变更时 | 新工具添加、旧工具废弃 |
| HEARTBEAT.md | 每季度 | 任务是否仍有价值，频率是否合适 |
常见问题
问题：Agent 行为不符合预期
排查顺序：
1. 检查 AGENTS.md — 是否有对应规则？规则是否清晰？
2. 检查 SOUL.md — 是否存在与预期行为冲突的人格设定？
3. 检查 USER.md — 用户信息是否影响了 Agent 的判断？
4. 检查 MEMORY.md — 是否有错误的长期记忆影响判断？
29.12 本章小结
OpenClaw 的 Workspace 文件体系将 Agent 的配置分解为 9 个职责清晰的文件：
- AGENTS.md：操作手册，定义"做什么"
- SOUL.md：人格设定，定义"是谁"
- USER.md：用户画像，支持个性化适应
- IDENTITY.md：系统生成的基础身份
- TOOLS.md：按需加载的工具说明
- HEARTBEAT.md：定期自动任务的执行清单
- BOOT.md：重启时的初始化仪式
- MEMORY.md 和 Daily Logs：记忆持久化（见第26章）
最重要的设计理念：AGENTS.md 负责行为规范，SOUL.md 负责人格塑造。两者分工明确，避免了"性格混入规则"或"规则影响人格"的混乱。
下一章：第30章 — 安全模型七层防御：从 Gateway 绑定到出站消息门控的完整纵深