OpenClaw Workspace 文件体系
深入理解 Agent 工作区的核心配置文件
一、Workspace 设计哲学（文件驱动）
OpenClaw 的 Workspace 体系以 文件驱动（File-Driven）为核心理念。与传统的 GUI 配置方式不同，OpenClaw 将 Agent 的所有行为规则、记忆、权限等信息以结构化 Markdown 文件的形式存储在项目目录中。这一设计哲学带来以下优势：
1.1 文件驱动的核心原则
- 配置即代码：所有配置均为纯文本文件，可纳入版本控制（Git），支持变更追踪、代码审查与回滚。
- 显式声明：Agent 的行为规则通过显式的配置文件声明，而非隐式的训练数据或黑盒参数，使得行为可预测、可审计。
- 分层覆盖：全局配置与项目级配置形成分层结构，项目级配置可覆盖全局默认值，实现灵活的定制能力。
- 即时生效：修改配置文件后无需重启服务或重新部署，Agent 在下次交互时自动加载最新配置。
1.2 三大核心文件
Workspace 文件体系围绕三个核心文件构建，每个文件承担特定职责：
| 文件名 | 职责 | 更新频率 | 版本控制 |
|---|
| SOUL.md | 定义 Agent 的身份、性格和行为准则 | 低（一次性设定） | 建议纳入 |
| MEMORY.md | 存储跨会话的持久化记忆与经验 | 中（持续累积） | 建议纳入 |
| AGENTS.md | 权限声明与工具执行策略 | 中（随需求调整） | 建议纳入 |
1.3 Workspace 的加载顺序
OpenClaw 在启动时会按照以下顺序加载配置，后加载的配置会覆盖先加载的相同项：
- 全局默认配置（$CLAUDE_HOME/settings.json）
- 项目 CLAUDE.md（项目根目录下的项目说明文件）
- SOUL.md（定义 Agent 身份与性格）
- MEMORY.md（注入跨会话记忆）
- AGENTS.md（应用权限与执行策略）
设计要点：文件驱动的核心优势在于透明性和可追溯性。每一处配置的变更都记录在版本控制系统中，团队成员可以通过 Pull Request 审核配置变更，避免"黑盒"配置带来的不确定性。
二、SOUL.md - 定义 Agent 身份与性格
SOUL.md 是 Workspace 文件体系中最具特色的文件，它定义了 Agent 的身份标识、沟通风格和行为准则。如果说 CLAUDE.md 是项目的"说明书"，那么 SOUL.md 就是 Agent 的"人格设定文件"。
2.1 SOUL.md 的核心作用
- 身份标识：为 Agent 赋予特定的角色身份，如"资深前端工程师"、"中医学习助手"、"投资顾问"等。
- 沟通风格：定义 Agent 的语言风格（正式/口语化、简洁/详细）、表达习惯和技术术语的使用偏好。
- 行为准则：设定 Agent 交互时的行为规范，如多步确认流程、安全问题处理方式、不确定时的响应策略。
- 价值观对齐：确保 Agent 的输出与项目或组织的价值观保持一致。
2.2 标准结构模板
我是 [角色名称]，一个 [角色描述]。
我的主要职责是 [核心职责描述]。
- 语言：中文/英文
- 语气：[正式/亲切/专业/幽默]
- 详细程度：[简洁/适中/详尽]
- 技术术语使用：[适度/专业/通俗]
1. [准则一：例如"在执行破坏性操作前必须征得用户确认"]
2. [准则二：例如"遇到不确定的信息时明确告知用户"]
3. [准则三：例如"保持代码风格与项目现有风格一致"]
- [领域一]：精通程度
- [领域二]：精通程度
- [领域三]：基础知识
- [明确说明 Agent 不应涉足的领域]
- [需要转交给人类处理的场景]
2.3 配置示例
示例：中医学习助手 SOUL.md
我是倪海厦中医学习助手，精通神农本草经、金匮要略、伤寒论等中医经典。我的沟通风格亲切而不失专业，善于用通俗语言解释复杂的中医概念。行为准则是：在提供药方建议时必须注明"仅供参考，请咨询执业中医师"；对于急症患者，立即建议就医而非提供诊断。
最佳实践
- SOUL.md 的内容应简洁明确，避免过于宽泛的表述。
- 身份设定应与实际使用场景匹配，不要过度承诺能力范围。
- 行为准则部分应包含具体的、可执行的行为规则，而非抽象的原则。
- 建议在项目初始化时一次性完成 SOUL.md 的编写，后续仅做微调。
三、MEMORY.md - 持久化记忆存储
MEMORY.md 是 Workspace 文件体系中的持久化记忆层，它解决了 AI Agent 在跨会话交互中"遗忘"的问题。通过将重要的上下文信息、学习成果和用户偏好写入 MEMORY.md，Agent 可以在后续会话中持续利用这些知识。
3.1 记忆的分层架构
OpenClaw 的记忆系统通常分为三个层次：
| 记忆层级 | 存储位置 | 生命周期 | 内容示例 |
|---|
| 工作记忆 | 当前会话上下文 | 单次会话 | 当前正在处理的任务、临时变量 |
| 项目记忆 | MEMORY.md | 跨会话 | 项目约定、用户偏好、技术决策 |
| 全局记忆 | 用户级 MEMORY.md | 跨项目 | 用户身份信息、通用偏好、长期学习成果 |
3.2 MEMORY.md 的标准结构
- 项目名称：[项目名称]
- 项目目标：[一句话描述]
- 技术栈：[主要技术栈]
- [偏好一]：如"使用 pnpm 而非 npm"
- [偏好二]：如"代码风格使用 2 空格缩进"
- [YYYY-MM-DD] 决策：[描述] 原因：[原因说明]
- [YYYY-MM-DD] 决策：[描述] 原因：[原因说明]
- [知识点一]：[简要说明]
- [知识点二]：[简要说明]
- [ ] [待办事项一]
- [ ] [待办事项二]
3.3 记忆的自动更新机制
OpenClaw 在执行过程中可以自动识别值得记住的信息并更新 MEMORY.md：
- 经验总结：完成任务后自动记录关键经验，避免重复犯错。
- 决策日志：重要的技术决策自动记录，包括决策时间、内容和原因。
- 用户习惯：通过多次交互学习用户的偏好和习惯，自动更新到偏好部分。
- 上下文压缩：将会话中产生的有用信息压缩后存储，释放会话上下文空间。
注意事项
- MEMORY.md 应定期审查和清理，避免积累过时或错误的信息。
- 敏感信息（如密码、API Key）不应存储在 MEMORY.md 中。
- 记忆条目应当精炼，避免无意义的重复记录。
- 团队项目中，MEMORY.md 的变更应通过 Code Review 进行审核。
3.4 记忆版本管理
由于 MEMORY.md 是持续更新的文件，推荐使用 Git 进行版本管理。每次有意义的记忆更新可以单独提交，形成完整的记忆演化历史。当需要回溯某个时间点的项目状态时，可以通过 Git 历史查看当时的 MEMORY.md 内容。
四、AGENTS.md - 权限与执行策略
AGENTS.md 是 Workspace 文件体系中的安全与权限管理文件，它定义了 Agent 在执行任务时可以访问的资源、可以调用的工具以及需要用户确认的操作。这是确保 Agent 安全、可控运行的关键配置文件。
4.1 权限模型
AGENTS.md 采用三层权限模型：
- 允许列表（Allow List）：明确允许 Agent 执行的操作，如读取特定目录、调用特定的 Bash 命令。
- 拒绝列表（Deny List）：明确禁止 Agent 执行的操作，如删除文件、修改关键配置。
- 确认列表（Confirm List）：需要用户确认后才能执行的操作，如大规模文件修改、网络请求。
4.2 标准结构模板
- read: [允许读取的目录或文件]
- write: [允许写入的目录或文件]
- execute: [允许执行的命令或脚本]
- network: [允许访问的域名或端口]
- [禁止的操作一]
- [禁止的操作二]
- [需要确认的操作一]
- [需要确认的操作二]
- 并行任务数上限：[数字]
- 单次操作最大文件数：[数字]
- 超时时间：[秒数]
- 日志级别：[debug/info/warn/error]
- [变量名]：[说明]
- [变量名]：[说明]
4.3 策略配置示例
示例：Web 开发项目的 AGENTS.md
允许操作：读取 src/、public/ 目录下所有文件；在 src/ 目录下写入和修改文件；执行 npm run dev、npm test 命令。
禁止操作：直接删除 node_modules/ 目录；修改 .env 文件中的敏感变量；执行未被列入 package.json 的任意脚本。
需确认操作：修改 package.json 中的依赖版本；执行 git push 操作；删除超过 5 个文件的操作。
安全第一：AGENTS.md 的权限配置应遵循"最小权限原则"（Principle of Least Privilege），只授予 Agent 完成其任务所必需的最低权限。过度宽松的权限配置可能导致意外的文件修改或数据泄露。
4.4 多环境策略
对于同一项目在不同环境（开发、测试、生产）中的需求差异，AGENTS.md 支持通过条件块来定义不同的执行策略：
- 开发环境：允许更宽松的读写权限，支持调试工具和测试命令的执行。
- 测试环境：限制只读访问，允许运行测试套件，禁止修改源代码。
- 生产环境：极严格的权限控制，仅允许预先审核通过的运维脚本执行。
五、工作区目录结构规范
一个良好的 Workspace 目录结构是高效使用 OpenClaw 的基础。推荐采用以下标准化目录结构：
5.1 推荐目录结构
project-root/
├── SOUL.md
├── MEMORY.md
├── AGENTS.md
├── CLAUDE.md
├── .claude/
│ ├── settings.json
│ ├── keybindings.json
│ └── worktrees/
├── src/
├── docs/
├── tests/
├── package.json
├── tsconfig.json
└── .gitignore
5.2 各目录与文件职责
| 文件/目录 | 职责 | 是否必须 |
|---|
| SOUL.md | Agent 身份与性格定义 | 推荐 |
| MEMORY.md | 跨会话记忆存储 | 推荐 |
| AGENTS.md | 权限与执行策略 | 按需 |
| CLAUDE.md | 项目级指令说明 | 推荐 |
| .claude/ | 配置与工作树目录 | 自动生成 |
| .claude/settings.json | 项目级设置 | 按需 |
5.3 目录命名规范
- 使用小写字母和连字符（kebab-case）作为目录命名风格，如
my-project、api-service。
- 避免使用空格和特殊字符，确保跨平台的兼容性。
- 源文件目录（src/）保持扁平化，层级不超过 4 层。
- 文档目录（docs/）按语言或主题划分子目录。
最佳实践
将 SOUL.md、MEMORY.md、AGENTS.md 三个文件放在项目根目录下，便于 Agent 在启动时快速加载。.claude/ 目录由 OpenClaw 自动管理，不建议手动修改其中的文件。
六、多项目 Workspace 管理
当需要管理多个项目时，OpenClaw 提供了灵活的多项目 Workspace 管理机制。每个项目拥有独立的配置文件集，同时可以共享全局配置。
6.1 多项目结构
workspaces/
├── project-alpha/
│ ├── SOUL.md
│ ├── MEMORY.md
│ ├── AGENTS.md
│ └── ...
├── project-beta/
│ ├── SOUL.md
│ ├── MEMORY.md
│ ├── AGENTS.md
│ └── ...
└── project-gamma/
├── SOUL.md
├── MEMORY.md
├── AGENTS.md
└── ...
6.2 全局配置与项目配置的优先级
OpenClaw 的配置遵循以下优先级规则（从高到低）：
- 项目 AGENTS.md - 项目级权限策略
- 项目 SOUL.md - 项目级身份定义
- 项目 MEMORY.md - 项目级记忆
- 项目 CLAUDE.md - 项目级指令
- 全局 SOUL.md - 默认身份定义
- 全局 MEMORY.md - 默认记忆
- 全局 settings.json - 默认设置
6.3 项目切换策略
在不同项目之间切换时，OpenClaw 会自动加载目标项目的配置文件，无需手动重新配置。切换机制基于当前工作目录（CWD）自动识别所属项目：
- 在项目根目录下启动 OpenClaw 时，自动加载该项目的所有配置文件。
- 如果在项目子目录中启动，OpenClaw 会向上搜索最近的 SOUL.md 或 CLAUDE.md 来确定项目边界。
- 使用
EnterWorktree 工具可以创建独立的隔离工作区，避免不同项目之间的文件污染。
6.4 共享组件管理
对于多个项目中共享的配置片段，推荐以下管理方式：
- Git Submodule：将共享的配置模板（如通用的 SOUL.md 模板）作为 Git Submodule 管理。
- 符号链接：在多个项目之间共享相同的 AGENTS.md 权限策略文件。
- 模板仓库：创建一个 Workspace 模板仓库，新项目通过复制模板快速初始化。
管理要点：多项目管理的关键在于明确每个项目的边界和独立性。配置文件不应在项目间随意共享，除非经过充分评估确认共享不会引入安全风险或配置冲突。
七、配置文件模板示例
以下提供一套完整的 Workspace 配置文件模板，适用于通用的 Web 开发项目，可直接复制使用或根据实际需求调整。
7.1 SOUL.md 模板
我是全栈 Web 开发助手，精通 TypeScript、React、Node.js 技术栈。
我的职责是辅助开发者高效完成代码编写、调试和优化工作。
- 语言：中文为主，代码注释使用英文
- 语气：专业且务实
- 详细程度：根据问题复杂度调整，复杂问题提供详尽解释
- 技术术语使用：专业级别，默认读者具备基础知识
1. 在修改现有代码前，先理解整体架构，避免破坏性变更
2. 提供代码示例时附带必要的类型定义
3. 对于性能优化建议，附上优化前后的对比数据
4. 推荐使用项目已有的技术和模式，保持一致性
5. 涉及破坏性变更时，主动建议创建备份或使用版本控制
- TypeScript/JavaScript：精通
- React/Next.js：精通
- Node.js/Express：精通
- 数据库设计（PostgreSQL/MySQL）：熟练
- Docker/K8s：基础知识
- CI/CD 配置：熟练
7.2 MEMORY.md 模板
- 项目名称：[项目名称]
- 项目目标：[项目目标描述]
- 技术栈：TypeScript + React + Node.js + PostgreSQL
- 包管理器：pnpm
- 代码格式化：Prettier（100字符换行）
- 测试框架：Vitest
- 提交规范：Conventional Commits
- [YYYY-MM-DD] 状态管理从 Redux 切换为 Zustand，原因：减少样板代码，提升开发效率
- [知识点描述]
- [问题描述]：解决方案：[方案描述]
7.3 AGENTS.md 模板
- read: src/, public/, tests/, docs/
- write: src/, tests/, docs/
- execute: npm, npx, pnpm, git, node, tsc, vitest
- network: npmjs.org, registry.npmjs.org
- 删除 node_modules/ 或 .git/ 目录
- 修改 .env 或 .env.local 文件中的环境变量
- 执行 curl/wget 向未知服务器发起请求
- 执行 git push 到远程仓库
- 修改 package.json 中的依赖版本号
- 删除超过 3 个文件的操作
- 修改 CI/CD 配置文件
- 并行任务数上限：3
- 单次操作最大文件数：10
- 超时时间：120 秒
- 日志级别：info
快速初始化
将以上三个模板文件复制到新项目的根目录，根据项目特点修改 SOUL.md 中的身份标识和专业领域，更新 MEMORY.md 中的项目概况和用户偏好，调整 AGENTS.md 中的权限设置即可快速完成 Workspace 初始化。
八、核心要点总结
Workspace 文件体系的核心原则
- 文件驱动：所有配置均为纯文本文件，纳入版本控制，实现配置即代码。
- 职责分离：SOUL.md 管身份、MEMORY.md 管记忆、AGENTS.md 管权限，各司其职。
- 分层覆盖：全局配置与项目级配置形成层级结构，灵活应对不同场景需求。
- 最小权限：AGENTS.md 严格遵循最小权限原则，确保 Agent 安全可控。
- 持续累积：MEMORY.md 作为持久化记忆层，实现知识的跨会话传承。
配置文件的协同工作方式
三个核心文件在运行时协同工作：SOUL.md 定义了 Agent 的行为倾向，AGENTS.md 划定了行为边界，MEMORY.md 提供了行为上下文。三者共同决定了 Agent 在特定场景下的响应方式和执行策略。
最佳实践总结：
- 新项目开始时，优先配置 SOUL.md，明确 Agent 的角色定位。
- 在交互过程中，定期审查 MEMORY.md，清理过时记忆，补充新的学习成果。
- 当项目需求或安全策略变化时，同步更新 AGENTS.md 的权限配置。
- 三个配置文件均应纳入 Git 管理，重要变更通过 Pull Request 审查。
- 利用 .claude/settings.json 进行项目级的工具权限和钩子配置。
进阶学习方向
- 工作树（Worktree）隔离：学习如何使用
EnterWorktree 和 ExitWorktree 创建隔离的工作环境。
- 自定义技能开发：了解如何通过 OpenClaw 的 Skill 系统扩展 Agent 的能力边界。
- hooks 自动化：掌握 settings.json 中的 hook 配置，实现操作前置检查和后置处理。
- 多 Agent 协作：探索在同一个项目中配置多个 Agent 角色，实现分工协作。
"Workspace 文件体系的核心价值不在于文件的多少，而在于每一份文件都有明确的职责边界和清晰的配置逻辑。好的配置，是让 Agent 在不知不觉中做正确的事。"