OpenClaw 核心 MD 文件完全指南

本文主要是深入了解和复习笔记，重新梳理一下 workspace 中几个核心的 MD 文件

OpenClaw 作为一个开源的本地优先 AI 代理框架，其最大的特点就是将所有配置、记忆和行为规则都以纯文本 Markdown 文件的形式存储在你的工作空间中。这种设计不仅让系统完全透明可控，还能让开发者像管理代码一样管理 AI 的“大脑”。

文件概览与层次关系

在开始详细介绍之前，先理解这些文件的层次关系：

• 身份层：SOUL.md（我是谁）+ IDENTITY.md（人格定义）+ USER.md（服务对象）

• 行为层：AGENTS.md（行为宪法）+ HEARTBEAT.md（周期任务）

• 记忆层：MEMORY.md（长期记忆）+ memory/YYYY-MM-DD.md（日志流水）

• 环境层：TOOLS.md（本地环境配置）

• 引导层：BOOTSTRAP.md（初始化脚本）

1. AGENTS.md - 行为守则与工作流

这是代理的“行为准则”，告诉它该怎么工作、什么能做、什么不能做。

主要内容

启动时做什么

• 每次会话开始时，代理会自动读取 SOUL.md、USER.md 和最近的记忆文件

• 通过 memory_search 查询历史记忆，快速恢复上下文

怎么记忆

• 每天的工作记录到 memory/YYYY-MM-DD.md（日志流水）

• 重要的经验和规则沉淀到 MEMORY.md（长期记忆）

• 核心原则：重要的事情必须写文件，不能只靠“脑子记”

安全边界

• 保护隐私，不泄露敏感信息

• 删除文件时用回收站，避免误操作

• 不确定的操作要先问用户

权限分级

• 本地操作（读文件、搜索）可以自主进行

• 对外操作（发邮件、发帖）需要用户授权

群聊礼仪

• 有价值时才发言，不刷屏

• 适度参与，不主导对话

• 少用 emoji 反应

心跳巡检

• 可以定期检查邮箱、日历等

• 有重要事情时提醒用户

• 没事就静默返回

一句话总结

AGENTS.md 是代理的“工作手册”，规定了它的启动流程、记忆方式、安全底线和行为规范。

2. SOUL.md - 我是谁

如果说 AGENTS.md 管流程，那么 SOUL.md 就管“怎么做人、怎么说话、怎么做事”。这个文件千人千面，完全取决于你希望你的代理具有什么样的性格和工作风格。

典型内容结构

整体风格基调强调真诚实用的交流方式，摒弃程式化的礼貌用语。代理应该像一个真实的工作伙伴那样自然沟通，而不是使用“很高兴为您服务”这类机械化的表达。

交流规范

• 完成任务后必须主动反馈结果，避免“闷头干活不吭声”

• 执行耗时较长的任务时要定期报告进展状态

• 允许表达观点和建议，展现个性而非保持机械中立

偏好定义例如：“优先使用本地搜索工具以降低 API 消耗，失败再考虑云端服务”或“优先使用自带浏览器浏览网页”——这类具体的工具选择偏好可以写在这里。

工作方式

• 遇到问题先尝试自行查找资料和上下文，而不是立即询问用户

• 采用按需检索的记忆访问模式，通过 memory_search 和 memory_get 精确查询，避免加载全部记忆内容

• 对外部操作保持谨慎，对内部工作保持主动

伦理边界

明确代理的身份定位——它是获得授权进入用户私人空间的“受邀者”，因此必须保持克制，尊重用户的隐私边界和使用习惯。

一句话总结

SOUL.md 定义了代理的性格、沟通风格和工作哲学，是“人格基线”的核心文件。

3. IDENTITY.md - 人设卡

这是一个轻量级的人设定义文件，更侧重于“角色与语气”，而不涉及工具权限或工作流程。

典型内容

典型配置示例：

• 名字：Claw / 小爪 / 任意你喜欢的名字

• 身份：AI 助理 / 技术顾问 / 研究伙伴 / 创意助手

• 风格：专业严谨 / 轻松幽默 / 温和耐心 / 直接高效（根据你的偏好）

• 标志 emoji：🦞 / 🤖 / 💡 / 📚（可自定义）

作用

给回复语气、称呼方式、情绪表达提供统一人格基线。它与 SOUL.md 的区别在于：

• SOUL.md：工作哲学和方法论

• IDENTITY.md：角色扮演和语气风格

一句话总结

IDENTITY.md 是代理的“角色卡”，定义了“我以什么身份和语气与你交流”。

4. USER.md - 用户画像

这是用户画像与偏好卡，回答“你在服务谁”这个问题。

典型内容

• 用户名：你的真实姓名或昵称

• 称呼偏好：正式称呼（如“张先生”）或昵称（如“小明”）

• 时区：Asia/Shanghai (GMT+8) / America/New_York (GMT-5) 等

• 语言偏好：中文 / 英文 / 双语

• Context 区块：可持续沉淀长期偏好、项目背景等

作用

约束称呼、语言和互动风格，避免每轮重新猜测用户偏好。这个文件通常比较简洁，但可以随着使用逐步丰富。

一句话总结

USER.md 是“用户档案”，让代理知道服务对象是谁、有什么偏好。

5. TOOLS.md - 本地环境私有备忘录

这个文件经常被误解为“工具权限清单”，实际上它是“本机环境私有配置备忘录”，相当于设备基础设施信息。

核心内容

本地环境信息

• 设备型号、操作系统

• 主机和别名等

• 本地浏览器路径和启动参数

设计目的

实现 Skill 的通用逻辑与特定机器配置的分离，意味着你可以更新 Skills 而不丢失你的备注，也可以分享 Skills 而不泄露你的基础设施信息

一句话总结

TOOLS.md 是“本机环境手册”，记录这台机器特有的配置和约定。

6. HEARTBEAT.md - 心跳

这是心跳轮询时要执行的“轻量待办清单”。

功能说明

OpenClaw 的心跳机制允许代理在无人交互时自动唤醒并执行预设任务。HEARTBEAT.md 文件明确规定：

• 定期检查的数据源类型（邮件收件箱、日程安排、RSS 订阅等）

• 触发用户通知的具体条件

• 无需打扰时的静默处理策略（返回 HEARTBEAT_OK 状态码）

核心价值

通过文档化的方式明确定义周期任务的执行逻辑，避免心跳检查的盲目性，同时有效控制 API 调用成本。

一句话总结

HEARTBEAT.md 是“定时任务配置”，告诉代理在特定时间应该做什么。

7. MEMORY.md - 长期记忆库

Token 占用：较大（通常是 system prompt 成本大头）

核心价值：打破会话隔离

这是 OpenClaw 最重要的创新之一——让 AI 代理拥有真正的“长期记忆”。与每日流水日志（memory/YYYY-MM-DD.md）不同，MEMORY.md 存储的是经过沉淀和提炼的长期知识：你的偏好、重要的上下文、代理学到的经验教训。

最关键的是：你通常不需要手动编辑这个文件。在日常对话中，你只需要对代理说“把这件事记下来”或“记住这个偏好”，它就会自动更新这个文件。这种自动化的记忆管理让代理能够真正“成长”和“学习”。

典型内容类型

MEMORY.md 会自动积累以下几类信息：

个人偏好与习惯

• 你的工作习惯、沟通风格偏好

• 常用的工具和服务选择

• 特定场景下的决策倾向

安全红线

• 绝对不可违反的安全规则（如禁止泄露密钥）

• 隐私保护的边界和约束

项目上下文

• 正在进行的重要项目及其目标

• 关键决策和里程碑记录

• 项目相关的背景知识

经验教训

• 过去遇到的问题和解决方案

• 失败案例的复盘总结

• 从错误中提炼的操作约束

运维知识

• 系统配置的变更记录

• 特定环境的注意事项

• 应急处理流程

工作机制

自动更新

• 代理在运行过程中会自动识别重要信息并写入

• 你可以通过自然语言指令触发记忆（“记住这个”“以后都这样做”）

• 无需手动编辑 Markdown 文件

智能检索

• 代理通过 memory_search 和 memory_get 工具按需查询

• 不是每次都加载全部内容，而是根据当前对话主题精确检索

• 确保跨会话的上下文连续性

使用建议

让代理自己管理

• 大部分时候，让代理自动维护这个文件即可

• 通过对话指令（“记住这个偏好”）比手动编辑更自然

定期审查

• 虽然是自动管理，但建议每月浏览一次

• 删除过时信息，归档不再需要的内容

• 这样可以控制文件大小，降低 token 消耗

手动干预时机

• 需要批量修改某类规则时

• 发现代理记录了错误信息时

• 想要重新组织记忆结构时

一句话总结

MEMORY.md 是代理的“长期记忆库”，通过自动更新机制打破会话隔离，让 AI 能够真正记住你、理解你、并随着使用不断成长。

8. BOOTSTRAP.md - 初始化脚本

该文件主要用于定义工作空间的初始化配置，包括：

• 首次启动时自动创建的目录结构

• 必需的依赖包和工具安装清单

• 环境变量的初始化设置

对于已经配置完善的工作空间，这个文件通常内容较少或保持空白状态。

文件协同工作流程

理解了单个文件的作用后，我们来看它们如何协同工作：

会话启动时

1. 读取 SOUL.md + IDENTITY.md（确立人格）

2. 读取 USER.md（了解服务对象）

3. 读取 AGENTS.md（加载行为规则）

4. 读取近两天 memory/*.md（回顾近期工作）

5. 根据需要使用 memory_search 检索 MEMORY.md

执行任务时

1. 参考 AGENTS.md 判断是否需要用户授权

2. 参考 TOOLS.md 获取本地环境配置

3. 按照 SOUL.md 定义的风格与用户沟通

任务完成后

1. 将工作日志写入 memory/YYYY-MM-DD.md

2. 如果产生了长期规则或经验，更新 MEMORY.md

3. 按照 SOUL.md 要求主动汇报结果

心跳触发时

1. 读取 HEARTBEAT.md 获取巡检清单

2. 执行检查（邮箱、日历等）轻量任务

3. 根据结果决定是提醒用户还是静默返回

结语

OpenClaw 的 MD 文件系统是其“本地优先、透明可控”理念的完美体现。通过这 8 个核心文件，你可以像管理代码一样管理 AI 代理的“大脑”：

• 可读：纯文本，任何编辑器都能打开

• 可写：人类可以直接编辑，不需要特殊工具

• 可追溯：Git 版本控制，每次修改都有记录

• 可协作：团队可以共享和讨论配置

• 可演化：根据实践持续优化，没有黑盒

这种设计让 OpenClaw 成为最“开发者友好”的 AI 代理框架之一。当你理解了这些文件的作用和协同机制，你就真正掌握了 OpenClaw 的核心——不是通过 API 调用一个黑盒服务，而是构建和训练一个完全属于你的 AI 协作伙伴。

现在，打开你的 ~/.openclaw/workspace，开始定制你的专属龙虾吧！🦞