OpenClaw 工作目录结构解析:理解 AI 智能体的文件系统组织|小龙虾科普

OpenClaw 工作目录结构解析：理解 AI 智能体的文件系统组织

本文是「拆解 OpenClaw」系列第 00 篇。系列以一个文件为线索，逐篇解析 AI 智能体的工程实现。本篇先给出整体结构地图，作为后续展开的索引。

一、一个被忽视的问题

主流 AI 产品给用户呈现的界面，往往只剩下一个对话框。

输入框收到提问，模型返回答案。整个交互过程像一台黑盒：用户看不到模型读到了哪些上下文，也看不到它如何记住此前的对话。失忆、人格漂移、回答风格不稳定，是这类产品的常见抱怨。

但站在工程视角，一个能长期陪伴使用者的 AI 智能体，背后并不只有一个模型。它需要解决一组具体的工程问题：

• 在跨会话的场景中，如何让模型保留对使用者的认知？
• 在 Token 预算有限的前提下，应该把哪些信息放进上下文？
• 模型的人格设定、行为边界、可调用工具，应该以何种形式存储？
• 当某次会话结束，下一次唤醒前，哪些状态需要持久化？

不同的 AI Agent 框架给出过不同的答案。OpenAI 在 ChatGPT 中用 memories 表存储用户偏好；Claude 在 Project 模式中允许用户上传 CLAUDE.md 作为系统级指令；Cursor 通过 .cursorrules 文件定义代码风格规约。

OpenClaw 给出的答案，是用一组人类可读的 Markdown 文件，组成一个工作目录。

这个目录在用户机器上的默认路径是 ~/.openclaw/workspace。它既是智能体的「家」，也是它的「身份证、记忆库、技能箱与工作台」。

本文将从这个目录的结构出发，解析每一块对应的工程职责，作为后续逐文件深入的索引。

二、工作目录的整体结构

完整的工作目录可以归纳为 6 大模块：

~/.openclaw/workspace/
│
├── 🧬 核心身份层
│   ├── SOUL.md           人格定义
│   ├── IDENTITY.md       身份卡
│   ├── USER.md           使用者档案
│   ├── AGENTS.md         工作守则
│   ├── CONTACTS.md       联系人映射
│   └── TOOLS.md          本地环境配置
│
├── 🧠 记忆系统
│   ├── MEMORY.md         长期记忆
│   ├── memory/           短期记忆 / 日记目录
│   │   ├── 2026-06-04.md
│   │   └── ...
│   └── HEARTBEAT.md      主动行为清单
│
├── 🛠️ 技能库（skills/）
│   ├── wechat-article-craft/
│   ├── email-mail-master/
│   ├── 400-report/
│   └── ... 30+ 子目录
│
├── 📂 工作产出
│   ├── projects/         项目工作区
│   ├── articles/         文章创作
│   ├── diagrams/         结构图与示意图
│   └── logs/             运行日志
│
├── 📄 历史归档
│   └── *.md / *.docx / *.png
│
└── 🔒 运行时与配置
    ├── .openclaw/        进程状态
    ├── .git/             版本管理
    ├── .clawhub/         平台对接配置
    └── .env              环境变量

每一层模块都对应一类明确的工程职责。下面逐层说明。

三、核心身份层：智能体的「自我」

身份层定义了智能体在每次会话开始前必须建立的基本认知。它回答三个问题：

我是谁？ —— 由 SOUL.md 与 IDENTITY.md 承担。前者定义人格底层（语气、价值观、行为偏好），后者定义当前实例化的具体身份（名字、头像、风格标签）。

我在为谁服务？ —— 由 USER.md 承担。它存储使用者的画像信息：称呼、时区、偏好、家庭关系、长期目标等。这些信息会在每次会话启动时被注入到系统提示词中。

我的边界在哪里？ —— 由 AGENTS.md 承担。它定义工作守则：哪些操作允许自主执行，哪些必须先征求确认；遇到敏感信息如何处理；与外部世界（邮件、群聊、社交账号）交互时的安全准则。

CONTACTS.md 和 TOOLS.md 是身份层的两个辅助文件。前者维护一个联系人映射表，让智能体在听到「清香姐姐」时能正确解析为对应的邮箱与社交账号。后者存放与本地环境强相关的配置（摄像头名称、SSH 别名、特定 API 的偏好参数），把环境差异从核心人格中剥离出去。

这一层的设计原则是：人格与配置分离，长期与短期分离。

身份层文件总体积通常不超过 10 KB，但承担了系统提示词的绝大部分语义负载。

四、记忆系统：跨会话连续性的工程实现

LLM 本质上是无状态的。它的「记忆」只存在于一次推理的上下文窗口中。会话结束后，所有信息都会消失。

要让一个智能体在跨会话场景下保持连续，必须在外部维护持久化状态。OpenClaw 的记忆系统采用了仿生设计，模拟人类大脑中两套并行的记忆机制：

长期记忆（MEMORY.md）：相当于人类的长时记忆。存放经过提炼的关键信息——重大决定、长期偏好、重要关系、生活里程碑。这个文件在每次主会话启动时会被完整加载。

短期记忆（memory/YYYY-MM-DD.md）：相当于人类的工作记忆与日记。每天一个文件，记录当日发生的具体对话、操作、临时备忘。这些文件不会全部加载到上下文，而是按需检索。

这种双层结构解决了一个核心矛盾：上下文窗口有限（即使是 200K Token 的模型，全部用来加载历史也并不经济），但智能体又需要长期连续性。

通过把「精华信息」与「原始日志」分开管理，OpenClaw 实现了一种类似数据库索引的机制——主索引常驻内存，明细按查询加载。

HEARTBEAT.md 是记忆层的特殊文件，它存放需要智能体周期性主动执行的事项（如「每天早上检查邮件」「每周日整理本周记忆」）。配合外部的 cron 调度，让智能体具备主动性，而不仅是被动响应。

五、技能库：能力的模块化封装

skills/ 目录是智能体的「外挂」。每个子目录是一个独立的技能包，对应一项专门能力。

一个典型的技能包结构如下：

skills/wechat-article-craft/
├── SKILL.md              技能说明（必须）
├── README.md             使用文档
├── references/           参考资料
│   ├── style-guides/
│   └── personal/
└── scripts/              辅助脚本

技能包的核心思想是 「技能即上下文」。

当用户提出「写一篇公众号文章」时，智能体并不会把所有 30 多个技能的说明一次性塞进上下文。它会先扫描 skills/ 目录下所有 SKILL.md 的元信息（名称、描述、触发词），按相关度匹配，然后只加载最相关的那一个完整内容。

这与 Function Calling 或 MCP（Model Context Protocol）的思路有相通之处，但更接近一种文档驱动的实现：技能不需要先在代码层注册，写一份合规的 Markdown 文档就能被识别。这降低了扩展门槛，普通用户也能为自己的智能体添加新技能。

skills/ 目录的体积通常远大于其他模块（可能数十 MB），但加载策略保证了它不会撑爆上下文窗口。

六、工作产出与历史归档

projects/、articles/、diagrams/、logs/ 这些目录存放智能体的实际工作成果。

它们的存在让智能体的输出可追溯：每一篇生成的文章保留原始 Markdown，每一张生成的图表保留源数据，每一次任务执行保留日志记录。这一方面服务于用户的回溯需求，另一方面也为后续的「自我学习」机制提供原料——智能体可以读取自己过去的产出，分析风格演变、总结失败案例。

历史归档目录则存放更早期、不再活跃的产出。它和工作产出目录的区别类似于「热数据」与「冷数据」，前者高频访问，后者偶尔回看。

七、运行时与配置

最后一层是被点号开头的隐藏目录与文件：

这一层是工程基础设施，对终端用户透明。但理解它的存在很重要：智能体的每一次状态变更（修改 MEMORY.md、新增一个技能、删除一个项目）都会被 .git/ 记录，意外删除可以恢复；.env 中存放的密钥永远不会进入对话上下文，避免泄露。

八、把这张图看完，能得到什么

回到最初的几个问题：

在跨会话场景中，如何让模型保留对使用者的认知？

通过 核心身份层 + 记忆系统 的双层注入。身份层固定不变，记忆层动态更新，二者共同构成稳定的「人设连续性」。

在 Token 预算有限的前提下，应该把哪些信息放进上下文？

通过 分层加载策略。身份层全量加载；长期记忆全量加载；短期记忆按需检索；技能库按触发词匹配；工作产出仅在被明确引用时读取。

模型的人格设定、行为边界、可调用工具，应该以何种形式存储？

以 人类可读的 Markdown 文件 存储。这种选择牺牲了一些性能（不如二进制格式紧凑），换来了三个工程收益：用户可以直接查看与编辑、文件可以纳入版本控制、内容可以直接作为 LLM 上下文使用，无需序列化转换。

当某次会话结束，下一次唤醒前，哪些状态需要持久化？

身份层与记忆层。其他层属于「调用即取，无需持久化」的范畴。

九、实操：如何查看自己的工作目录

如果你已经安装了 OpenClaw，想查看工作目录的全貌，可以直接在对话中要求：

把你的工作目录结构发我一份，每个文件夹标注用途。

智能体会调用 read / exec 等工具，扫描目录并整理输出。本文开头的那张目录树，就是这样得到的。

十、下一篇

下一篇将深入身份层的核心文件 SOUL.md，解析它的字段结构、注入机制，以及人格定义如何在模型推理中产生稳定的语气与行为偏好。

本系列从一个文件出发，理解 AI 智能体的工程实现。