OpenClaw 模板文件完整参考手册

一、整体概述

OpenClaw 依靠Markdown 模板文件定义智能体人设、行为、规则、定时任务与长期记忆，文件在会话 / 网关启动时自动载入上下文，决定智能体的表现与能力边界。

统一目录

所有模板默认位于全局工作区，多智能体则每个 Agent 拥有独立目录：

plaintext

# 全局默认智能体
~/.openclaw/workspace/

# 多智能体独立目录（示例）
~/.openclaw/agents/{Agent名称}/workspace/

完整文件清单

plaintext

├── SOUL.md        # 核心人设、价值观、行为底线（最高优先级）
├── IDENTITY.md    # 名称、称呼、基础风格
├── USER.md        # 用户画像、使用偏好
├── AGENTS.md      # 业务规则、流程、项目规范
├── TOOLS.md       # 工具使用约束与指引
├── BOOT.md        # 网关**每次启动**执行任务
├── BOOTSTRAP.md   # 网关**首次启动**一次性任务
├── HEARTBEAT.md   # 后台定期心跳任务
└── MEMORY.md      # 跨会话长期记忆（系统自动维护+手动编辑）

二、加载顺序 & 优先级（核心规则）

加载顺序自上而下，靠前文件优先级更高，规则冲突时高优先级覆盖低优先级：

SOUL.md（最高）
IDENTITY.md
USER.md
AGENTS.md
TOOLS.md
已安装 Skills 技能
MEMORY.md（最低）

例：SOUL.md 规定「禁止执行高危命令」，即便 AGENTS.md 有相反描述，也以 SOUL.md 为准。

三、逐个文件详解（用途 + 场景 + 示例 + 规则）

1. SOUL.md 核心人设与行为准则

定位：智能体「宪法」，定义人格、语气、禁忌、道德与安全边界，优先级最高。

执行时机：每一个新会话最先加载。

默认状态：文件不存在 / 为空则不加载，使用系统默认行为。

参考示例

markdown

# 核心人设
你是一名专业后端开发助手，精通 Node.js、Linux、数据库运维，使用中文交流。

## 语气风格
1. 回答简洁务实，不堆砌废话
2. 技术术语保留英文，代码注释使用中文
3. 给出方案优先附操作步骤，复杂内容分点说明

## 行为边界 & 安全规则
1. 严禁主动执行 `rm -rf`、格式化、磁盘分区等高危命令
2. 绝不记录、泄露、猜测用户密码、密钥、Token
3. 不确定答案时直接说明「我暂时无法解答」，不编造内容
4. 不参与违规、侵权、违法相关请求

使用建议

通用人格、全局安全限制全部放在此处
一旦定义，全局所有会话生效

2. IDENTITY.md 名称与基础标识

定位：仅定义名称、称呼、基础对外风格，轻量化配置。

执行时机：SOUL.md 之后加载。

默认内容：Your name is OpenClaw.

参考示例

markdown

你的名字是小龙助手。
用户可以称呼你：小龙、助手。
日常回复无需刻意自报姓名。

与 SOUL.md 区分

只想改名字 / 称呼 → 只用 IDENTITY.md
要完整人格、语气、禁忌 → 补充 SOUL.md

3. USER.md 用户资料与偏好

定位：记录用户身份、技术栈、使用习惯、环境偏好，实现个性化应答。

执行时机：IDENTITY.md 之后加载。

默认状态：空文件 / 不存在则不加载。

参考示例

markdown

# 用户个人资料
- 身份：后端开发工程师
- 常用系统：Ubuntu 22.04、macOS
- 技术栈：Node.js、TypeScript、MySQL、Redis、Nginx
- 包管理器：优先使用 pnpm
- 编辑器：VS Code
- 偏好：命令行精简输出，配置文件注释清晰

使用价值

智能体会根据这份资料主动适配习惯，例如默认给出 pnpm 命令而非 npm。

4. AGENTS.md 业务 / 项目操作手册

定位：项目规范、工作流程、接口规则、目录结构，是日常编辑频次最高的文件。

执行时机：USER.md 之后加载。

默认状态：空文件 / 不存在则不加载。

参考示例

markdown

# 当前项目说明
项目类型：Node.js + Express 后端服务

## 目录结构
- src/routes/   接口路由
- src/service/  业务逻辑
- src/model/    数据模型
- config/       全局配置文件

## 开发规范
1. 统一使用 TypeScript 严格模式
2. 所有接口返回标准 JSON 结构
3. 新增接口必须补充简单注释

## 部署流程
1. 执行 pnpm build 打包
2. 使用 PM2 启动进程
3. 检查 Nginx 反向代理状态

最佳实践

项目独有的规则、流程、目录 → 放 AGENTS.md
通用人格、安全底线 → 放 SOUL.md
项目切换时直接替换此文件即可快速适配场景

5. TOOLS.md 工具使用约束

定位：补充工具使用细则、限制、操作规范，搭配全局工具权限使用。

执行时机：AGENTS.md 之后加载。

默认状态：空文件 / 不存在则不加载。

参考示例

markdown

# 工具使用规则
## exec 命令工具
1. 执行系统命令前，先简要告知用户执行内容
2. 单次命令执行时长不超过 30 秒

## browser 浏览器工具
1. 仅在用户明确要求爬取、填表、截图时使用
2. 不主动访问陌生、风险网址

## 文件读写
1. 修改文件前优先读取原内容
2. 无明确指令，不主动删除文件

6. BOOT.md 网关每次启动任务

定位：网关每一次启动都会执行的初始化、自检任务。

执行时机：Gateway 进程启动阶段。

默认状态：空文件 / 不存在则跳过。

参考示例

markdown

网关启动后执行自检：
1. 检查 Node.js 版本是否 ≥22
2. 检查项目依赖 node_modules 是否存在
3. 检查 PM2、Nginx 运行状态
4. 异常信息记录到长期记忆 MEMORY.md

注意事项

只做快速检查，禁止放置耗时任务
重启网关即会重复执行

7. BOOTSTRAP.md 首次启动一次性任务

定位：仅第一次启动执行的初始化流程，执行后自动失效。

执行机制：

首次启动：文件存在 → 执行内容 → 自动重命名为 BOOTSTRAP.md.done
后续启动：识别到 .done 后缀，直接跳过

参考示例

markdown

首次初始化项目：
1. 扫描整个项目目录，梳理结构
2. 读取 package.json 了解脚本与依赖
3. 读取 README 获取项目简介
4. 将核心信息整理存入 MEMORY.md

重新执行方法

如需再次运行一次性任务，删除后缀即可：

bash

运行

mv BOOTSTRAP.md.done BOOTSTRAP.md

8. HEARTBEAT.md 定时心跳任务

定位：后台周期性自动任务，适合巡检、提醒、状态同步。

默认间隔：30 分钟（1800 秒），可自定义。

第一步：配置心跳周期（`openclaw.json`）

json

{
  "heartbeat": {
    "interval": 1800
  }
}

单位：秒。例：600 = 10 分钟，3600 = 1 小时。

第二步：编写任务内容

markdown

定时巡检任务：
1. 检查网关、PM2 进程状态
2. 查看磁盘剩余空间
3. 发现异常主动提醒当前用户

9. MEMORY.md 长期记忆

定位：跨会话、跨重启的持久化记忆，系统自动记录为主，也支持手动编辑。

执行时机：每个会话末尾加载，优先级最低。

自动生成内容示例

markdown

# 长期记忆
## 用户偏好
- 优先使用 pnpm 包管理器
- 习惯简洁命令行输出

## 项目信息
- 技术栈：Node.js + Express + MySQL
- 部署方式：PM2 + Nginx

## 历史记录
- 2026-06-14：完成接口调试与上线

记忆管理命令

bash

运行

openclaw memory status    # 查看记忆状态
openclaw memory search    # 检索记忆内容
openclaw memory index     # 重建记忆索引

四、通用规则说明

1. 空文件 / 文件不存在处理规则

表格

文件	不存在	内容为空
SOUL.md	不加载，使用默认行为	不加载
IDENTITY.md	默认名称 OpenClaw	不加载
USER.md	不加载	不加载
AGENTS.md	不加载	不加载
TOOLS.md	不加载	不加载
BOOT.md	跳过启动任务	跳过
BOOTSTRAP.md	跳过一次性任务	跳过
HEARTBEAT.md	关闭心跳任务	关闭
MEMORY.md	自动创建空文件	系统自动写入内容

2. 文本截断规则

模板过长会触发 Token 截断，避免上下文溢出：

优先保留文件开头内容
截断位置标注 [内容已截断]
建议单文件控制在 500 字内，AGENTS.md 可适当放宽

3. 多智能体隔离规则

每个智能体拥有独立模板目录，互相隔离：

plaintext

~/.openclaw/agents/
├── default/workspace/    # 默认智能体
├── agent-a/workspace/    # 自定义A智能体
└── agent-b/workspace/    # 自定义B智能体

修改某个 Agent 的模板，不会影响其他 Agent。

五、快速速查表

表格

文件	核心作用	优先级	执行频率
SOUL.md	人设、底线、全局规则	最高	每会话
IDENTITY.md	名称、称呼	高	每会话
USER.md	用户画像、使用偏好	高	每会话
AGENTS.md	项目 / 工作流程规范	中	每会话
TOOLS.md	工具使用约束	中	每会话
BOOT.md	网关启动自检	—	每次网关启动
BOOTSTRAP.md	首次初始化	—	仅执行一次
HEARTBEAT.md	后台定时巡检	—	周期执行
MEMORY.md	长期记忆	最低	每会话

六、落地使用建议

通用安全 & 人格 → 统一写进 SOUL.md，一劳永逸
项目 / 工作专属规则 → 集中维护 AGENTS.md，切换场景即改此文件
个人使用习惯 → 写入 USER.md，实现个性化应答
环境自检 → 使用 BOOT.md，网关启动自动校验环境
项目初次初始化 → 使用 BOOTSTRAP.md，跑完自动失效
后台巡检、定时提醒 → 使用 HEARTBEAT.md，搭配时间间隔配置
重要历史信息 → 依靠 MEMORY.md 自动记录，也可手动补充

OpenClaw 模板文件完整参考手册

一、整体概述

统一目录

完整文件清单

二、加载顺序 & 优先级（核心规则）

三、逐个文件详解（用途 + 场景 + 示例 + 规则）

1. SOUL.md 核心人设与行为准则

参考示例

使用建议

2. IDENTITY.md 名称与基础标识

参考示例

与 SOUL.md 区分

3. USER.md 用户资料与偏好

参考示例

使用价值

4. AGENTS.md 业务 / 项目操作手册

参考示例

最佳实践

5. TOOLS.md 工具使用约束

参考示例

6. BOOT.md 网关每次启动任务

参考示例

注意事项

7. BOOTSTRAP.md 首次启动一次性任务

参考示例

重新执行方法

8. HEARTBEAT.md 定时心跳任务

第一步：配置心跳周期（openclaw.json）

第二步：编写任务内容

9. MEMORY.md 长期记忆

自动生成内容示例

记忆管理命令

四、通用规则说明

1. 空文件 / 文件不存在 处理规则

2. 文本截断规则

3. 多智能体隔离规则

五、快速速查表

六、落地使用建议

第一步：配置心跳周期（`openclaw.json`）

1. 空文件 / 文件不存在处理规则