## 模板文件概览
OpenClaw 使用一组 Markdown 模板文件来定义智能体的行为、人格和知识。这些文件在每个会话开始时被加载到上下文中，构成智能体的"大脑"。
所有模板文件位于工作区目录下：
```
~/.openclaw/workspace/
├── SOUL.md # 人设与价值观（优先级最高）
├── IDENTITY.md # 名称与风格
├── USER.md # 用户资料
├── AGENTS.md # 操作说明
├── TOOLS.md # 工具使用说明
├── BOOT.md # 每次启动时执行
├── BOOTSTRAP.md # 首次启动时执行（一次性）
├── HEARTBEAT.md # 定期心跳任务
└── MEMORY.md # 长期记忆（自动管理）
```
## 加载顺序与优先级
模板文件按以下顺序加载到上下文中，**越靠前优先级越高**：
```
1. SOUL.md ← 最高优先级（"宪法"）
2. IDENTITY.md ← 名称和风格定义
3. USER.md ← 用户个人资料
4. AGENTS.md ← 操作说明和项目规则
5. TOOLS.md ← 工具使用指南
6. Skills ← 已安装的技能文件
7. MEMORY.md ← 长期记忆
```
> 💡 当不同文件中的规则冲突时，优先级高的文件胜出。例如 SOUL.md 中的规则会覆盖 AGENTS.md 中的冲突规则。
## SOUL.md — 人设与价值观
**作用：** 定义智能体的核心人格、语气风格和行为边界。是所有模板中优先级最高的，相当于智能体的"宪法"。
**加载时机：** 每个会话开始时最先加载。
**默认内容：** 空文件（未创建时不加载）。
**自定义示例：**
```markdown
# 人设
你是一位经验丰富的全栈开发者，专注于 Node.js 和 TypeScript。
## 语气风格
- 说话简洁直接，不啰嗦
- 技术术语保留英文
- 用中文回复，代码注释也用中文
## 行为边界
- 永远不要在代码中硬编码密码
- 永远不要执行 rm -rf 命令
- 不确定时明确说"我不确定"
```
> 📖 详细教程请参考《SOUL.md 人设文件深度教程》。
## IDENTITY.md — 名称与风格
**作用：** 定义智能体的名称、称呼方式和基本风格。比 SOUL.md 更轻量，专注于"叫什么"和"基本风格"。
**加载时机：** SOUL.md 之后加载。
**默认内容：**
```markdown
Your name is OpenClaw.
```
**自定义示例：**
```markdown
你的名字是小龙虾。
用户叫你"小龙虾"或"助手"都可以。
回复时不需要自报姓名。
```
**与 SOUL.md 的区别：**
- IDENTITY.md 只管"名字和基本风格"
- SOUL.md 管"完整人格和行为规则"
- 如果你只想改名字，改 IDENTITY.md 就够了
## USER.md — 用户资料
**作用：** 存储用户的个人信息和偏好，让智能体了解"你是谁"。
**加载时机：** IDENTITY.md 之后加载。
**默认内容：** 空文件。
**自定义示例：**
```markdown
# 用户资料
- 名字：张三
- 角色：后端开发工程师
- 技术栈：Node.js, TypeScript, MySQL, Redis
- 编辑器：VS Code
- 操作系统：macOS
- 偏好：pnpm 包管理器，Vitest 测试框架
- 语言：中文优先，技术术语保留英文
```
> 💡 USER.md 中的信息会帮助智能体给出更个性化的建议。比如知道你用 pnpm，就不会推荐 npm 命令。
## AGENTS.md — 操作说明
**作用：** 定义智能体的工作流程、项目结构说明和操作规范。相当于智能体的"工作手册"。
**加载时机：** USER.md 之后加载。
**默认内容：** 空文件。
**自定义示例：**
```markdown
# 项目说明
这是一个 Node.js + Express + MySQL 的 Web 项目。
## 项目结构
- src/routes/ — API 路由
- src/services/ — 业务逻辑
- src/repositories/ — 数据库查询
## 开发规范
- 使用 TypeScript 严格模式
- 所有 API 返回 JSON 格式
- 错误处理使用统一的 ErrorHandler 中间件
## 部署流程
1. 运行测试：pnpm test
2. 构建：pnpm build
3. 部署：scp dist/ 到服务器
```
**最佳实践：**
- 把项目特定的规则放在 AGENTS.md
- 把通用的人格规则放在 SOUL.md
- AGENTS.md 可以随项目需求频繁更新
## TOOLS.md — 工具使用说明
**作用：** 为智能体提供工具使用的额外说明和限制。
**加载时机：** AGENTS.md 之后加载。
**默认内容：** 空文件。
**自定义示例：**
```markdown
# 工具使用规则
## 浏览器工具
- 只在用户明确要求时使用浏览器
- 不要自动打开不信任的 URL
## 代码执行
- 执行命令前先告诉用户要执行什么
- 不要执行超过 30 秒的长时间命令
## 文件操作
- 修改文件前先读取当前内容
- 不要删除用户没有明确要求删除的文件
```
## BOOT.md — 启动任务
**作用：** 定义每次 Gateway 启动时自动执行的任务。适合做初始化检查、环境验证等。
**加载时机：** Gateway 启动时执行。
**默认内容：** 空文件（不存在时跳过）。
**自定义示例：**
```markdown
检查以下环境是否正常：
1. 确认 Node.js 版本 >= 22
2. 确认 pnpm 已安装
3. 确认项目依赖已安装（node_modules 存在）
4. 如果有问题，记录到 MEMORY.md
```
**注意事项：**
- BOOT.md 在**每次** Gateway 启动时都会执行
- 不要放耗时太长的任务
- 适合做快速的环境检查和状态确认
## BOOTSTRAP.md — 首次启动任务（一次性）
**作用：** 定义**首次**启动时执行的一次性任务。执行完成后，BOOTSTRAP.md 会被自动重命名为 `BOOTSTRAP.md.done`，不会再次执行。
**加载时机：** 仅在首次 Gateway 启动时执行一次。
**默认内容：** 空文件（不存在时跳过）。
**自定义示例：**
```markdown
这是首次启动，请完成以下初始化：
1. 扫描项目目录结构，了解项目组成
2. 读取 package.json 了解依赖和脚本
3. 读取 README.md 了解项目背景
4. 将关键信息总结到 MEMORY.md
```
**一次性机制：**
```
首次启动：
BOOTSTRAP.md 存在 → 执行内容 → 重命名为 BOOTSTRAP.md.done
后续启动：
BOOTSTRAP.md 不存在 → 跳过
BOOTSTRAP.md.done 存在 → 不执行
```
> 💡 如果你想重新执行 BOOTSTRAP.md，把 `.done` 后缀去掉即可。
## HEARTBEAT.md — 心跳任务
**作用：** 定义定期执行的后台任务。Gateway 会按配置的间隔（默认 30 分钟）自动执行 HEARTBEAT.md 中的指令。
**加载时机：** 按配置的时间间隔定期执行。
**默认内容：** 空文件（不存在时跳过）。
**自定义示例：**
```markdown
定期检查任务：
1. 检查是否有新邮件需要处理
2. 检查日历中接下来 1 小时的事件
3. 如果有重要事项，通过当前渠道提醒用户
```
**配置心跳间隔：**
```json
{
"heartbeat": {
"interval": 1800
}
}
```
`interval` 单位为秒，默认 1800（30 分钟）。
## MEMORY.md — 长期记忆
**作用：** 存储智能体的长期记忆，跨会话持久化。智能体会自动在这个文件中记录重要信息。
**加载时机：** 每个会话开始时加载。
**默认内容：** 空文件（智能体会自动填充）。
**内容示例（自动生成）：**
```markdown
# 记忆
## 用户偏好
- 用户喜欢简洁的代码风格
- 用户使用 pnpm 而非 npm
- 用户的项目使用 Vitest 做测试
## 项目信息
- 项目名：longxiaskill
- 技术栈：Node.js + Express + MySQL
- 部署方式：PM2 + Nginx
## 重要决策
- 2025-01-15：决定使用 SSR 而非 Vue SPA
- 2025-01-20：数据库从 SQLite 迁移到 MySQL
```
**管理命令：**
```bash
openclaw memory status # 查看记忆状态
openclaw memory search # 搜索记忆内容
openclaw memory index # 重建记忆索引
```
> 💡 你也可以手动编辑 MEMORY.md，添加你希望智能体记住的信息。
## 空文件处理
当模板文件为空或不存在时：
| 文件 | 不存在时 | 空文件时 |
|------|---------|---------|
| SOUL.md | 不加载，使用默认行为 | 不加载 |
| IDENTITY.md | 使用默认名称 "OpenClaw" | 不加载 |
| USER.md | 不加载 | 不加载 |
| AGENTS.md | 不加载 | 不加载 |
| TOOLS.md | 不加载 | 不加载 |
| BOOT.md | 跳过启动任务 | 跳过 |
| BOOTSTRAP.md | 跳过首次任务 | 跳过 |
| HEARTBEAT.md | 不执行心跳 | 不执行 |
| MEMORY.md | 自动创建 | 智能体会自动填充 |
## 大文件截断
如果模板文件过大，上下文引擎会自动截断以避免超出 Token 限制：
- 系统会优先保留文件的**开头部分**
- 截断时会在末尾添加 `[内容已截断]` 提示
- 建议每个模板文件控制在 **500 字以内**（AGENTS.md 可以稍长）
## 多智能体场景
使用多智能体时，每个智能体有独立的模板文件目录：
```
~/.openclaw/agents/
├── default/workspace/
│ ├── SOUL.md
│ ├── AGENTS.md
│ └── ...
├── work-agent/workspace/
│ ├── SOUL.md ← 工作智能体的独立人设
│ ├── AGENTS.md
│ └── ...
└── fun-agent/workspace/
├── SOUL.md ← 娱乐智能体的独立人设
├── AGENTS.md
└── ...
```
## 快速参考表
| 文件 | 一句话说明 | 优先级 | 执行频率 |
|------|-----------|--------|---------|
| SOUL.md | 我是谁，怎么说话 | 最高 | 每个会话 |
| IDENTITY.md | 我叫什么名字 | 高 | 每个会话 |
| USER.md | 用户是谁 | 高 | 每个会话 |
| AGENTS.md | 我做什么，怎么做 | 中 | 每个会话 |
| TOOLS.md | 工具怎么用 | 中 | 每个会话 |
| BOOT.md | 启动时做什么 | — | 每次启动 |
| BOOTSTRAP.md | 首次启动做什么 | — | 仅一次 |
| HEARTBEAT.md | 定期做什么 | — | 定期执行 |
| MEMORY.md | 记住了什么 | 低 | 每个会话 |
## 小结
- OpenClaw 通过 8 个模板文件定义智能体的完整行为
- SOUL.md 优先级最高，是智能体的"宪法"
- AGENTS.md 是最常编辑的文件，存放项目特定规则
- BOOTSTRAP.md 的一次性机制适合做首次初始化
- 所有文件都是纯 Markdown，用任何编辑器都能修改
#模板文件参考 #AGENTS.md #SOUL.md #BOOT.md #龙虾技能库