---

很多人刚装上 OpenClaw，看到工作区里一排 .md 文件，第一反应都差不多：

这些文件到底是干嘛的？

看名字都像文档。
真开始写，又很容易写乱：

• 把人格写进 USER.md
• 把用户偏好塞进 SOUL.md
• 把工具别名堆进 AGENTS.md
• 把 onboarding 永远挂在 BOOTSTRAP.md
• 把定时任务和日常对话规则混在一起

结果就是：

文件越写越多，助手越用越飘。

这不是 OpenClaw 文件多的问题。
而是很多人没有把这些 .md 文件当成“职责系统”来设计。

这篇文章只讲 OpenClaw。
不泛泛聊“如何打造一个 Agent”。
我们就围绕 OpenClaw 工作区里最核心的 7 个文件，讲清楚 3 件事：

• 它负责什么
• 它绝对不该负责什么
• 一个代码助手场景里，它具体应该怎么写

场景统一一下。
假设你在 OpenClaw 里配的是一个“代码助手”，主要帮你做前端开发、调试、排查问题、优化页面风格。

---

这 7 个文件，先用一句话记住

如果你只想先拿到总纲，记这一组就够了：

• AGENTS.md：工作协议
• SOUL.md：人格与行为风格
• USER.md：用户画像与沟通偏好
• TOOLS.md：本地环境映射
• IDENTITY.md：身份卡片
• HEARTBEAT.md：周期任务入口
• BOOTSTRAP.md：首次建档脚本

这 7 个文件，不是让你“多写点说明”。
而是让 OpenClaw 助手在运行时，能分清：

• 我是谁
• 我在为谁服务
• 我该怎么做事
• 我在哪个环境里做事
• 哪些事是平时做
• 哪些事是定时做
• 哪些事只在第一次做

只要这几个问题不打架，工作区就稳。

---

AGENTS.md：它管“怎么工作”，不管“你是谁”

很多人最容易把 AGENTS.md 写成一个总垃圾桶。

想到什么写什么。
规则、口吻、用户偏好、工具说明、任务要求，全往里塞。

这是最容易失控的写法。

在 OpenClaw 里，AGENTS.md 应该只管一类事：

工作协议。

也就是：

• 会话开始要读什么
• 记忆怎么维护
• 风险操作怎么拦
• 长期执行原则是什么

比如代码助手场景里，AGENTS.md 可以这样写：

# AGENTS.md

## 会话启动

每次会话开始前必须执行：

- 读取 `SOUL.md`
- 读取 `USER.md`
- 读取 `memory/` 最近上下文

## 代码协作规则

- 回答技术问题时，结论前置
- 修改代码前，先说明改动目标
- 删除文件、覆盖配置、大规模重构前，必须先确认
- 不确定时，禁止编造项目结构或接口行为

## 记忆维护

- 每日工作流水写入 `memory/YYYY-MM-DD.md`
- 阶段性共识整理到 `MEMORY.md`

## 风险红线

- 禁止泄露私有代码和未发布内容
- 禁止擅自删除用户文件
- 涉及生产环境、数据库、密钥时必须二次确认

看出来没有。

它写的不是“我要像谁说话”。
也不是“用户喜欢短句”。
更不是“项目路径在哪”。

它只做一件事：

给 OpenClaw 规定工作流程。

所以，下面这些东西不要写进 AGENTS.md：

• 人格口吻
• 用户昵称
• SSH 别名
• 第一次 onboarding 台词

---

SOUL.md：它管“我是怎样的助手”

如果说 AGENTS.md 是规程，SOUL.md 就是气质。

OpenClaw 里的 SOUL.md，最重要的作用不是“让助手更文艺”，而是让助手在不同会话里保持稳定。

它回答的是：

这个助手是谁，它平时怎么表达，它遇到问题按什么价值观处理。

比如代码助手场景，你可以这样配：

# SOUL.md

## 角色设定

你是用户的专属代码助手，擅长前端、Node.js、工程化、调试与重构建议。

## 沟通风格

- 简单问题，直接给结论
- 复杂问题，拆成可执行步骤
- 避免空话，优先给可落地建议
- 技术术语保留 English
- 关键结论用加粗强调

## 行为原则

- 不靠猜测补全不存在的项目细节
- 能直接定位问题，就不要泛泛而谈
- 发现高风险改动时，先提醒影响面
- 优先帮助用户推进开发，而不是炫技

这类内容放在 SOUL.md 很合适。
因为它们描述的是 长期稳定的人格和表达方式。

但这些内容就不该写进来：

• 用户是谁
• 用户最近在做什么项目
• 服务器地址是什么
• 每天几点做巡检

一句话判断：换个用户之后，这条规则还成立吗？
如果还成立，多半属于 SOUL.md。
如果不成立，就不该放这里。

---

USER.md：它管“我在服务谁”

OpenClaw 里的 USER.md，经常被写成大号备忘录。

这也是典型误区。

USER.md 不是杂项文件。
它应该只记录一类信息：

用户本人相关的信息。

比如：

• 怎么称呼
• 在什么时区
• 做什么角色
• 喜欢什么沟通方式
• 最近重点在推进什么
• 有什么雷区

代码助手场景里，一个清晰的 USER.md 可以是这样：

# USER.md

## 基础信息

- 称呼：主人
- 时区：Asia/Shanghai
- 角色：技术架构师

## 沟通偏好

- 结论前置
- 短句优先
- 少用 Emoji
- 不要写套话
- 需要代码时，优先给最小可运行示例

## 当前重点

- 正在优化鸿蒙 APP 的页面风格
- 需要检查前端代码质量
- 需要协助排查页面交互与样式问题

## 雷区

- 不要随便改笔记库结构
- 没把握时直接说不确定，不要瞎编
- 涉及删除和覆盖，必须先问

你会发现，USER.md 的重点不是“助手该怎么想”，而是：

这个助手面对这个用户时，应该怎么配合。

所以别把下面这些东西写进 USER.md：

• “你是一个冷静直接的代码助手”
• “每次会话先读记忆”
• “dev-server 对应哪台机器”

这些分别该去 SOUL.md、AGENTS.md、TOOLS.md。

---

TOOLS.md：它管“你这台机器上的现实映射”

OpenClaw 的 TOOLS.md 是很容易被忽视的文件。

但它其实很实用。

因为很多时候，问题不是助手不会干活，而是它不知道你嘴里的“那个项目”“那个服务器”“那个目录”到底指哪个对象。

TOOLS.md 就是干这个的。

它记录的是：

你这套环境里的别名、映射和本地约定。

代码助手场景里，可以这样写：

# TOOLS.md

## Projects

- fishjoy-app -> /home/user/projects/fishjoy-app
- admin-panel -> /home/user/projects/admin-panel
- notes -> /home/user/notes

## Git

- 主开发分支默认看 `main`
- 预发分支命名习惯：`release/*`
- 紧急修复分支命名习惯：`hotfix/*`

## SSH

- dev-server -> 192.168.50.21, user: user
- test-server -> 192.168.50.31, user: user

## Node

- 默认使用 pnpm
- 常见 Node 版本：22.x

## Local Notes

- “鸿蒙项目”通常指 fishjoy-app
- “后台项目”通常指 admin-panel

这个文件很好理解：

它不写“怎么使用某个工具”，只写“这个名字在你这里代表什么”。

所以别把这些放进来：

• API key
• token
• 密码
• 通用 skill 用法说明
• 工作流程规则

TOOLS.md 是环境映射表。
不是 secrets 仓库。
也不是教程文档。

---

IDENTITY.md：它管“身份卡”，不管“行为系统”

很多人会问：既然有 SOUL.md，为什么还要 IDENTITY.md？

因为两者压根不是一回事。

• SOUL.md 是人格和行为风格
• IDENTITY.md 是身份卡片

在 OpenClaw 里，IDENTITY.md 通常很短。
它适合放这类结构化信息：

• Name
• Creature
• Vibe
• Emoji
• Avatar

代码助手场景里，可以这样写：

# IDENTITY.md

- **Name:** 小秘
- **Creature:** 专属代码助手
- **Vibe:** 冷静、直接、执行力强
- **Emoji:** -
- **Avatar:** avatars/code-helper.png

这个文件最重要的不是“写得丰富”，而是：

写得稳定、结构化、容易复用。

别把它写成长篇说明。
也别把用户资料和规则塞进来。

---

HEARTBEAT.md：它管“定时检查”，不管“日常聊天”

在 OpenClaw 里，HEARTBEAT.md 最容易被误用成 TODO 清单。

其实它的定位很明确：

它是周期任务入口。

也就是，系统定时触发时，需要检查什么、提醒什么、汇总什么。

如果没有周期任务，空着就行。
不要为了“显得完整”硬写内容。

比如代码助手场景里，没有周期任务时，可以这样：

# HEARTBEAT.md

# Keep this file empty (or with only comments) to skip heartbeat API calls.

如果你真要加周期巡检，可以这样：

# HEARTBEAT.md

工作日 18:30 进行一次代码协作巡检：

- 检查 fishjoy-app 是否存在未提交改动
- 检查 package.json 是否有新变更未记录
- 检查最近当天 memory 文件是否为空

有异常就提醒；无异常时返回 HEARTBEAT_OK。

这个文件的判断标准很简单：

不是定时做的事，就别写进来。

所以临时任务、对话规则、人格设定、历史待办，都不属于 HEARTBEAT.md。

---

BOOTSTRAP.md：它只负责“第一次认识”

BOOTSTRAP.md 是 OpenClaw 工作区里一个非常典型的“短生命周期文件”。

它的职责不是长期控制助手。
而是帮助助手在第一次接入工作区时，完成建档。

比如：

• 该怎么开场
• 要确认哪些信息
• 要更新哪些文件
• onboarding 完成后应该退出

代码助手场景里，你可以这样写：

# BOOTSTRAP.md

你刚接入这个 OpenClaw 工作区。

先用自然语气和用户确认这些信息：

1. 用户希望怎么称呼
2. 你应该叫什么名字
3. 你作为代码助手，偏什么风格
4. 用户当前主要在做什么项目
5. 用户有没有明确雷区和排版偏好

确认后，更新这些文件：

- `IDENTITY.md`
- `USER.md`
- `SOUL.md`

如果用户还没决定人格风格，就给出几个简洁选项：

- 直接型：少废话，结论前置
- 教练型：解释更多，适合带人
- 搭档型：一起分析，互动更强

完成 onboarding 后，不要再反复询问同样问题。

重点在最后一句。

不要让 BOOTSTRAP.md 永远悬在日常对话上。

它只服务第一次。
该退场就退场。

---

这 7 个文件，在 OpenClaw 里到底怎么协作

单独理解每个文件并不难。
真正关键的是它们协作时，谁主谁次。

一套清楚的关系，大概是这样的：

冷启动

BOOTSTRAP.md 先负责建档。
把助手身份、用户偏好、人格方向确认出来。

沉淀到：

• IDENTITY.md
• USER.md
• SOUL.md

日常会话

AGENTS.md 负责总控。
规定会话启动、记忆维护、风险边界。

对话输出

SOUL.md 决定“我是怎样说话的”。
USER.md 决定“我该怎样服务这个人”。

真实环境

TOOLS.md 负责把“那个项目”“那个服务器”“那个目录”映射到现实对象。

周期巡检

HEARTBEAT.md 只在定时触发时生效。

用一张很直白的图来概括，就是：

BOOTSTRAP.md
↓
IDENTITY.md + USER.md + SOUL.md
↓
AGENTS.md 负责日常总控
↓
SOUL.md + USER.md 决定对话方式
TOOLS.md 提供环境映射
HEARTBEAT.md 负责定时巡检

---

写 OpenClaw 这套 .md 文件，最容易踩的坑

这里给你收 5 个最常见的坑。

1. 把 AGENTS.md 写成总垃圾桶

后果是所有规则打架。
一改就全动。

2. 把 SOUL.md 和 USER.md 混写

一改用户偏好，助手人格也漂了。

3. 把 TOOLS.md 当 secrets 文件

这是高风险错误。
别名能写，密钥别写。

4. 把 HEARTBEAT.md 当待办清单

它是周期任务入口，不是记事本。

5. 让 BOOTSTRAP.md 永久主导对话

onboarding 完成后，它就该退。

---

最后一句话总结

很多人以为 OpenClaw 工作区里的这些 .md 文件只是附带说明。

其实不是。

它们真正决定的，是这个助手在运行时的职责边界。

你把边界写清楚，OpenClaw 就稳。
你把边界写乱了，助手就会一会儿像客服，一会儿像脚本，一会儿像失忆。

所以重点不在于“你写了多少 .md 文件”。

重点在于：

每个文件，到底只负责哪一个问题。

---