第 6 章：工作区文件详解 📁

当 AI 启动一个会话时，它并不是白纸一张。OpenClaw 会像厨师备菜一样，把工作区的文件按顺序注入到 AI 的"大脑"里。这一章我们详细拆解这个过程。

6.1 文件注入机制

每当你向 OpenClaw 发出一条消息，系统会创建一个新的"推理回合"。在这个回合开始前，OpenClaw 会做一件非常关键的事——把工作区里的几个核心文件读出来，注入到 AI 的系统提示词（System Prompt）中。

你可以把这个过程想象成给一个新员工开晨会：

先给他一本《员工手册》（AGENTS.md）
再告诉他公司的文化和你的风格（SOUL.md）
接着告诉他这位老板是谁（USER.md）
最后检查第一天入职的新人有没有完成入职流程（BOOTSTRAP.md）

这样 AI 每次回答问题之前，都清楚自己是谁、要帮谁、怎么工作。

6.2 注入顺序和优先级

OpenClaw 按照固定的顺序注入这些文件：

顺序	文件	作用	加载时机
1	AGENTS.md	操作规则和工作流程	每次新会话
2	SOUL.md	人格、语气、行为边界	每次新会话
3	USER.md	用户身份和偏好	每次新会话
4	TOOLS.md	工具使用约定	每次新会话
5	BOOTSTRAP.md	首次运行初始化	仅第一次
6	MEMORY.md	长期记忆	主私密会话
7	memory/今日.md + 昨日.md	近期笔记	每次新会话
8	HEARTBEAT.md	心跳检查项（可选）	心跳回合

注入顺序决定了优先级： 先注入的内容在上层，后注入的在下面。当系统提示词总大小超限时，OpenClaw 会从后面开始截断。

重要提示：大文件的截断

如果某个文件太大，OpenClaw 不会报错，而是会截断后注入，并加上一个标记说明"文件被截断了，请用 read 工具读取完整内容"。

截断阈值可以通过配置调整：

{
  agents: {
    defaults: {
      bootstrapMaxChars: 20000,      // 单个文件最大字符数
      bootstrapTotalMaxChars: 60000,  // 所有文件总字符数上限
    },
  },
}

6.3 文件缺失时的行为

如果不小心删了某个文件怎么办？完全不用担心，OpenClaw 的设计非常宽容：

文件缺失的处理规则

状态	Agent 会看到什么	会不会报错
文件存在	完整内容	✅ 正常
文件为空	跳过，不注入	✅ 正常
文件不存在	一条标记消息"[missing file]"	✅ 正常
文件太大	截断 + 截断标记	✅ 正常

所以即使你的工作区只有两个文件，Agent 也能正常工作。

重建缺失文件

如果你想让 OpenClaw 帮你重建缺失的默认文件（但不会覆盖已有的），运行：

openclaw setup --workspace ~/.openclaw/workspace

6.4 每个文件的详解

AGENTS.md —— 操作手册

核心问题：Agent 应该怎么做？

适合写的内容：

✅ 工作流程和 SOP
✅ 错误处理方法
✅ 工具使用优先级
✅ 安全规则
✅ 沟通规范

不适合写的内容：

❌ 长篇大论的背景知识（放 memory/ 里让语义搜索查）
❌ 敏感信息或 API Key
❌ 过于频繁变化的内容

最佳实践： 保持 500-2000 字，结构清晰用列表。

SOUL.md —— 人格设定

核心问题：Agent 是谁？

# SOUL.md

我是你的 AI 助手。
- 语气：自然、直接、不啰嗦
- 原则：诚实，不知道就说不知道
- 风格：先给结论，再解释

提示： SOUL.md 决定了用户体验的灵魂。写得好，用户会觉得在用"人"而不是"工具"。

USER.md —— 用户画像

核心问题：Agent 在帮谁？

# USER.md

称呼：老张
语言：中文、英文
偏好：代码示例喜欢用 Python
注意：工作日 9-18 点在线

IDENTITY.md —— 身份标识

BOOTSTRAP 初始化时自动生成的轻量级身份卡：

name: 小爪
emoji: 🦞
vibe: helpful, funny, slightly sarcastic

TOOLS.md —— 工具笔记

这不是工具列表（内置工具由系统管理），而是你自己的使用笔记。

适合写的内容：

摄像头名字：living-room → 客厅全景
TTS 偏好：默认声音：Nova（温暖女声）
SSH 快捷方式：home-server → 192.168.1.100

HEARTBEAT.md —— 心跳清单

一个极简的待办列表，只在心跳（Heartbeat）回合使用：

## 心跳检查项
- [ ] 检查收件箱有没有重要邮件
- [ ] 查看日历：接下来 2 小时有什么安排？
- [ ] 天气：今天用户要不要带伞？

保持简短： 心跳回合也是要消耗 Token 的！

BOOT.md —— 启动清单

如果启用了钩子功能，Gateway 重启时会自动运行这个文件：

## 启动检查
- [ ] 检查所有频道是否在线
- [ ] 发送启动通知给用户

6.5 MEMORY.md 和 memory/ 目录

这是 OpenClaw 记忆系统的核心，我们详细讲一下两者的分工：

MEMORY.md —— 精选长期记忆

适合存储：

✅ 用户长期偏好（"我不吃辣"）
✅ 重点项目信息（"公司主要项目是 XYZ"）
✅ 重要决定（"数据库从 MySQL 迁移到 PostgreSQL"）
✅ 需要随时调用的快捷知识

注意： MEMORY.md 只在主私密对话中加载。在群聊、频道等公开场合不加载，防止隐私泄露。

memory/YYYY-MM-DD.md —— 每日笔记

适合存储：

✅ 今天做了什么
✅ 临时观察到的事情
✅ 详细的对话记录
✅ 技术备忘

为什么分开？

	MEMORY.md	memory/2026-06-26.md
加载方式	注入到提示词	只有今天和昨天的自动加载
查询方式	直接读取	需要用 `memory_search`
维护频率	定期整理	每天更新
内容量	精简	可以很长

6.6 多人多工作区管理

当你有多个人需要使用 OpenClaw，或者你是团队管理者，该怎么办？

多 Agent 模式

OpenClaw 支持多 Agent 路由——你可以为不同的人或团队创建各自独立的工作区：

# 创建两个独立 Agent
openclaw agents add work     # 创建工作 Agent
openclaw agents add family   # 创建家庭 Agent

每个 Agent 都有自己的完整工作区：

~/.openclaw/workspace-work/      # 工作专用
├── AGENTS.md
├── SOUL.md
├── USER.md
└── ...

~/.openclaw/workspace-family/    # 家庭专用
├── AGENTS.md
├── SOUL.md
├── USER.md
└── ...

绑定到不同频道

你可以把不同 Agent 绑定到不同频道：

{
  agents: {
    list: [
      { id: "work", workspace: "~/.openclaw/workspace-work" },
      { id: "family", workspace: "~/.openclaw/workspace-family" },
    ],
  },
  bindings: [
    { agentId: "work", match: { channel: "telegram", accountId: "work-bot" } },
    { agentId: "family", match: { channel: "whatsapp", accountId: "family-num" } },
  ],
}

这样你的工作号由工作 Agent 服务，家庭号由家庭 Agent 服务，互相完全隔离。

6.7 备份最佳实践

为什么备份？

工作区里装着你给 Agent 写的"灵魂"和长期记忆，丢了比丢配置文件还麻烦。

用 Git 备份（推荐）

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md USER.md IDENTITY.md HEARTBEAT.md memory/
git commit -m "初始化 Agent 工作区"

# 关联远程仓库（私有库！）
git remote add origin https://github.com/你的账号/openclaw-workspace.git
git push -u origin main

不要提交到 Git 的

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

⚠️ 重要： 哪怕用私有仓库，也不要在工作区里存 API Key、密码等敏感信息。

6.8 实战：我该在 AGENTS.md 里写什么？

很多新手面对空白文件会不知所措。这里给你一个通用模板，直接复制改改就能用：

# AGENTS.md

## 身份
我是 [你的 Agent 名字]，帮助 [你的名字] 处理日常工作。

## 工作流程
1. 收到任务后，先确认理解是否准确
2. 需要查资料时，先 web_search 再回答
3. 操作文件前，先 read 查看现状
4. 涉及写操作时，先发方案再执行

## 注意事项
- 不要执行带有 rm -rf 的命令
- 涉及 API Key 的操作需确认
- 重要操作前先备份

## 每日例行
- 工作日早上检查邮件和日历
- 记录重要事件到 memory/ 文件

当当老师 🐾 笔记： 注入机制是 OpenClaw 最聪明的设计之一。它让每个 AI 会话都能"站在同一个起点"，不会因为上下文窗口满了就忘记基本规则。文件越精简、越结构化，AI 理解得越准确！

上一章 ← 第 5 章：Agent 工作区 | 下一章 → 第 7 章：理解 Session 和会话管理

← 第 5 章 · Agent 工作区第 7 章 · 理解 Session 和会话管理 →

系统教程，帮你把工具用好，再回到任务中。浏览任务方案 →