Agent 工作区结构说明

OpenClaw 有一个很关键的设计特点：它尽量把状态和规则落到文件系统里，而不是藏在不可见的黑箱配置里。

这意味着如果你想真正理解 OpenClaw，必须知道工作区里常见文件各自负责什么。

1. 为什么工作区很重要

工作区不是普通缓存目录，而是 Agent 的长期运行现场。它通常承接这些内容：

• 身份和规则
• 用户信息
• 长期记忆
• 每日日志
• 本地技能
• 会话元数据

你可以把它理解成“这个 Agent 的可编辑生活空间”。

2. 一组最值得先认识的核心文件

AGENTS.md

更适合作为 Agent 的总体定义文件，通常放：

• 身份定位
• 行为边界
• 回复风格
• 面向当前工作区的规则

它更像系统级行为说明。

SOUL.md

比 AGENTS.md 更接近人格内核，回答的是：

• 这个 Agent 是谁
• 价值观和底线是什么
• 遇到模糊情况优先怎么判断

它通常比普通工作规则更稳定。

USER.md

适合承接：

• 用户称呼
• 偏好
• 长期关系信息
• 适合被长期记住的协作习惯

MEMORY.md

更适合记录：

• 已确认事实
• 已做出的决策
• 后续会反复用到的背景信息

memory/YYYY-MM-DD.md

这类文件更接近日志。适合记录：

• 某天发生过什么
• 某个任务推进到哪里
• 今天和昨天需要连续保留的上下文

skills/

工作区级技能目录。它的价值在于：

• 只对当前项目生效
• 可以覆盖更低优先级的全局或内置技能
• 特别适合团队协作和仓库内共享能力

sessions.json

会话状态和元数据的承接位置，用来帮助系统区分不同来源、不同 session 的上下文。

3. 这些文件的职责怎么分

一个更容易记住的分法是：

• AGENTS.md / SOUL.md：定义“怎么思考和行动”
• USER.md / MEMORY.md：定义“记住谁、记住什么”
• memory/：定义“最近发生了什么”
• skills/：定义“能做什么”
• sessions.json：定义“当前在哪个上下文里”

如果一开始就把这些职责混在一起，后续会越来越难维护。

4. 为什么“一切皆文本”很重要

OpenClaw 这套方式的一个优势在于：

• 文件可直接查看
• 出问题时容易排查
• 团队协作时更容易理解差异
• 可以纳入版本控制

这对中文用户尤其重要，因为很多问题不是“功能没有”，而是“状态看不见”。

5. 工作区级技能为什么优先级最高

当同名技能在不同来源同时存在时，工作区级技能更适合用来：

• 针对当前项目改行为
• 重写某个内置技能
• 增加团队私有约束

它不会影响其他项目，这也是它特别适合放进仓库一起协作的原因。

6. 最常见的维护误区

把所有内容都写进一个文件

这样短期方便，长期非常难维护。

把工作区当临时目录

工作区越长期运行，越需要清晰分层，而不是随手堆文件。

不区分人格层和流程层

人格层更稳定，流程层更容易变化，应该分开。

7. 一条更稳的整理方式

建议按下面顺序建立自己的工作区：

1. 先写清 SOUL.md
2. 再补 AGENTS.md
3. 再区分 USER.md 和 MEMORY.md
4. 再决定哪些技能放进 skills/
5. 最后再做自动化和 hooks

下一步推荐

• OpenClaw 记忆系统怎么工作
• Session 与配对机制
• Skills 系统怎么工作
• OpenClaw 安装与环境