夜雨聆风
OpenClaw 几个 md 文件到底有什么作用
SPECIAL REPORT
1. AGENTS.md
作用
这是最核心的 workspace 规则文件。
它通常承载：
-
session startup 规则 -
red lines / safety -
记忆使用原则 -
group chat 行为 -
工作方式与协作规范
你可以把它理解成：
agent 在这个 workspace 里的“操作宪法”
内容类型
默认模板里常见内容包括：
-
First Run -
Session Startup -
Memory -
Red Lines -
External vs Internal -
Group Chats
什么时候使用
-
每轮 prompt 注入 -
post-compaction 后额外读取关键 section
src/auto-reply/reply/post-compaction-context.ts 里默认会提取：
-
Session Startup -
Red Lines
作为压缩后强制补回的关键规则。
什么时候更新
-
用户直接维护 -
agent 在需要记录流程/规则/教训时可以更新 -
monorepo hook 也可能注入额外 AGENTS.md 类文件
保存位置
-
workspace/AGENTS.md
特别注意
它不是“人格文件”，而是“操作规则文件”。
小程序非广告，自己开发的一个免费趣味测试
2. SOUL.md
作用
定义 persona、tone、边界感、沟通风格。
内容类型
默认模板强调：
-
Core Truths -
Boundaries -
Vibe -
Continuity
什么时候使用
-
每轮 prompt 注入 -
system prompt 会对 SOUL.md 做特殊语义提升
src/agents/system-prompt.ts 会额外提醒：
如果有 SOUL.md，就要体现它的 persona 和 tone
所以它不是普通上下文文件，而是被 runtime 赋予了“人格优先文件”语义。
什么时候更新
-
首次 onboarding 后由用户和 agent 一起确立 -
后续人格、风格、边界变化时更新
保存位置
-
workspace/SOUL.md
特别注意
它更像“我是谁、我怎么说话”，而不是“我该怎么执行任务”。
3. TOOLS.md
作用
这是本地环境和外部工具使用说明，不是工具注册表。
内容类型
默认模板里强调的是：
-
摄像头名称 -
SSH host/alias -
TTS 偏好 -
设备昵称 -
环境特定说明
什么时候使用
-
每轮 prompt 注入
什么时候更新
-
用户更新本地工具/环境说明 -
agent 发现新的环境约定后也可以补充
保存位置
-
workspace/TOOLS.md
特别注意
最重要的一点：
TOOLS.md 不控制真实工具可用性
真实可用性由：
-
tool registration -
tool policy -
sandbox
决定。
4. IDENTITY.md
作用
定义 agent 的展示身份。
内容类型
默认模板里包括：
-
Name -
Creature -
Vibe -
Emoji -
Avatar
什么时候使用
-
每轮 prompt 注入 -
agent 注册/更新时会被 gateway/server methods 读写
src/gateway/server-methods/agents.ts 里：
-
agents.create 会追加 Name/Emoji/Avatar -
agents.update 也可能追加 Avatar
什么时候更新
-
首次 onboarding 时确定 -
agent 名称/头像/展示身份变化时更新 -
UI/管理接口可能直接写入
保存位置
-
workspace/IDENTITY.md
特别注意
这是目前几份文件里最明显会被系统管理接口直接写的一份。
5. USER.md
作用
记录被服务用户的协作信息。
内容类型
默认模板里包括：
-
Name -
What to call them -
Pronouns -
Timezone -
Notes
什么时候使用
-
每轮 prompt 注入
什么时候更新
-
onboarding 时建立 -
随用户偏好、称呼、背景变化持续更新
保存位置
-
workspace/USER.md
特别注意
它不是 dossier，不应该被写成隐私档案；默认模板也明确强调了这一点。
6. HEARTBEAT.md
作用
保存 heartbeat 定期检查清单。
内容类型
通常应该很短，只写周期性检查任务。
默认模板甚至鼓励：
-
为空 -
或只留注释
什么时候使用
-
每轮 prompt 里会注入 -
heartbeat 运行时尤其关键
默认 heartbeat prompt 在 src/auto-reply/heartbeat.ts 里写死为：
Read HEARTBEAT.md if it exists … If nothing needs attention, reply HEARTBEAT_OK.
什么时候更新
-
用户告诉 agent 增删定期检查任务时 -
agent 可以按指令直接修改
保存位置
-
workspace/HEARTBEAT.md
特别注意
它不是“常规记忆”，而是“周期性检查脚本的人类可读版”。
7. BOOTSTRAP.md
作用
首次启动的 onboarding 仪式文件。
内容类型
默认模板会引导 agent：
-
询问自己的名字、nature、vibe、emoji -
更新 IDENTITY.md -
更新 USER.md -
共同完善 SOUL.md -
然后删除自己
什么时候使用
-
brand-new workspace 初次阶段 -
每轮 prompt 注入，直到被删除
什么时候更新
-
基本不应该被长期维护 -
主要是在新工作区初始化时由模板生成 -
onboarding 完成后通常删除
保存位置
-
workspace/BOOTSTRAP.md
特别注意
它不是永久配置文件，而是一次性引导文件。
小程序非广告，自己开发的一个免费趣味测试
8. MEMORY.md
作用
长期记忆主文件。
内容类型
通常是：
-
durable facts -
preferences -
decisions -
长期约束 -
值得保留的经验
什么时候使用
-
会作为 bootstrap 文件自动注入（如果存在） -
也会进入 memory 系统索引 -
可被 memory_search / memory_get 访问
什么时候更新
-
用户显式要求记住某件事 -
agent 将长期有价值内容从 daily memory 中沉淀出来
保存位置
-
workspace/MEMORY.md
特别注意
它和 memory/*.md 的最大差异是：
MEMORY.md 会自动进入每轮 prompt memory/*.md 不会
9. memory.md
作用
是 MEMORY.md 的替代/兼容形式。
内容类型
和 MEMORY.md 类似，主要承载长期记忆。
什么时候使用
-
若存在，也会被 bootstrap 识别 -
也会被 memory 系统视为默认记忆文件之一
什么时候更新
-
与 MEMORY.md 类似
保存位置
-
workspace/memory.md
特别注意
仓库对 MEMORY.md 和 memory.md 都有兼容逻辑，但真正实践里通常应统一风格，避免双文件并存造成语义混乱。
10. memory/YYYY-MM-DD.md 与 memory/*.md
作用
daily log / 局部长期记忆 / 项目记忆分片。
内容类型
常见是：
-
每日发生了什么 -
临时上下文 -
待跟进事项 -
逐步沉淀的项目笔记
什么时候使用
-
不自动注入每轮 prompt -
主要通过 memory 系统索引和检索
什么时候更新
-
用户或 agent 日常持续记录 -
memory flush / session memory 相关机制也会间接影响这类内容沉淀
保存位置
-
workspace/memory/*.md
特别注意
它们是 memory 系统主力，不是 bootstrap 注入主力。
小程序非广告，自己开发的一个免费趣味测试
11. 总结
-
AGENTS.md 是操作规则，SOUL.md 是人格风格，TOOLS.md 是本地环境说明。 -
IDENTITY.md 和 USER.md 分别描述 agent 身份与用户画像。 -
HEARTBEAT.md 是周期性检查清单，不是普通记忆文件。 -
BOOTSTRAP.md 是一次性 onboarding 文件。 -
MEMORY.md / memory.md 是长期记忆主文件，同时具备 bootstrap 注入和 memory 索引双重身份。 -
memory/*.md 主要属于 memory 系统，不会自动每轮注入。