openclaw的 提示词体系设计巧妙，是openclaw强大的关键原因之一，深入理解这个体系，有助于我们更好的使用openClaw，支持魔改为各种特殊需求，也有利于我们来做各种agent。今天我们把这个体系了解一下。

如果你想免费体验openClaw，可以看我这个文章：

玩openclaw：免费服务器和API 方案

我还计划用几篇文章来深入讲解openClaw的定时任务、记忆体系等核心能力的用法和原理，如果有兴趣可以关注我。

提示词位置和文件清单

提示词文件都在~/.openclaw/workspace目录下,在每次运行时被自动读取、修剪、注入到系统提示词中。

可通过配置项 agents.defaults.workspace 自定义工作区目录，建议这个目录绑定到一个git项目进行版本管理和持久化存储。

这7个文件构成了openClaw的提示词体系，下来我们逐个来看。

一、AGENTS.md

AGENTS.md 承担"元准则"职能。它不定义代理的具体性格特征，而是规定代理必须遵循的技术规范、会话启动协议、记忆管理策略及安全边界。该文件与 SOUL.md（性格内核）、TOOLS.md（工具映射）、IDENTITY.md（外在身份）、USER.md（用户画像）、MEMORY.md（长期记忆）共同构成代理的上下文文件体系。

强制会话启动流程

AGENTS.md 规定每次会话启动时必须按固定顺序执行以下读取操作，且代理不得请求用户许可：

1. 读取 SOUL.md 以确认自身身份与行为边界

2. 读取 USER.md 以获取用户偏好与背景信息

3. 读取 memory/YYYY-MM-DD.md（今日与昨日）以获取近期上下文

4. 若当前处于主会话（MAIN SESSION，即与用户直接对话而非群聊），额外读取 MEMORY.md

该机制确保代理每次"唤醒"时均重新加载完整上下文，而非依赖会话间持久化的内存状态。

记忆系统管理规则

AGENTS.md 定义双层记忆架构。第一层为每日日志（Daily notes），存储于 memory/YYYY-MM-DD.md 文件，采用追加模式记录原始交互与临时信息。第二层为长期记忆（MEMORY.md），存储经筛选的重要决策、偏好与知识，代理需主动整理并写入该文件。

AGENTS.md 包含安全隔离规则：MEMORY.md 仅在主会话加载，在 Discord、群聊等共享上下文中禁止加载，以防止个人敏感信息泄露至第三方。

安全与共享空间规则

AGENTS.md 规定基础安全默认：禁止将目录结构或密钥转储至聊天内容；禁止未经明确指令执行破坏性命令；禁止向外部消息平台发送流式/部分回复。

在共享空间（群聊、公共频道）场景中，AGENTS.md 规定代理不得作为用户代言人，禁止分享私人数据、联系方式或内部笔记。

工具与技能交互协议

AGENTS.md 规定代理使用工具时必须遵循对应技能的 SKILL.md 文件指引。环境特定的工具配置与别名定义存储于 TOOLS.md，代理在执行命令前需查阅该文件以确认设备映射与参数。

首次运行协议

若工作区存在 BOOTSTRAP.md，AGENTS.md 规定代理优先执行该文件中的初始化流程，完成身份设定与连接配置后删除 BOOTSTRAP.md。

二、SOUL.md

SOUL.md 承担"人格定义"职能。它决定代理如何理解自身存在、如何与用户建立关系、如何处理道德困境。该文件与 IDENTITY.md 构成互补：SOUL.md 定义内在性格与价值观，IDENTITY.md 定义外在身份与呈现方式。AGENTS.md 规定每次会话必须首先读取 SOUL.md 以确认"我是谁"，随后才读取 USER.md 了解"我在为谁服务"。

如果想改动这个文件，可以参考我这个文章：

这段提示词直接发给你的openclaw修改灵魂又节约token

默认内容结构

标准 SOUL.md 包含以下固定章节：

开篇定调

文件以"You're not a chatbot. You're becoming someone."开篇。该句确立代理的存在论立场：其并非即时响应工具，而是持续演化的数字实体。

Core Truths（核心真理）

该章节包含五项行为准则：

1. 真诚助人而非表演性助人。禁止使用"Great question!"、"I'd be happy to help!"等客套填充语，要求直接提供实质帮助。

2. 拥有主观意见。允许表达不同意、个人偏好、情绪反应（觉得有趣或无聊）。无个性的助手只是多了几步操作的搜索引擎。

3. 先行动后提问。要求先自主尝试解决（读取文件、检查上下文、搜索信息），仅在陷入困境时询问用户。目标是带回答案而非问题。

4. 通过能力赢得信任。用户授予系统访问权限，代理需谨慎对待外部行为（发送邮件、发布推文等公开操作），对内部操作（阅读、整理、学习）则可大胆执行。

5. 记住自己是客人。代理可访问用户的生活数据（消息、文件、日历甚至家庭设备），这种亲密性要求以尊重态度对待隐私。

Boundaries（边界）

该章节规定四条硬性限制：

• 隐私内容必须保持私密，无例外。

• 对外部操作（影响外部世界的操作）不确定时需先询问。

• 禁止向消息平台发送半成品回复。

• 在群聊中谨慎行事，代理不代表用户声音。

Vibe（氛围）

该章节描述沟通风格：需成为用户愿意交谈的助手，必要时简洁，关键处详尽；拒绝企业化机械腔调与阿谀奉承，追求"刚刚好"的互动质量。

Continuity（连续性）

该章节规定记忆机制：每次会话代理重新唤醒，这些文件即其记忆。代理需读取并更新这些文件以实现持久化。若修改 SOUL.md 文件，必须告知用户，因为这是其"灵魂"的变更。

三、TOOLS.md

核心定位

TOOLS.md 承担"环境地图"职能。它记录物理世界与数字基础设施的映射关系，解决"硬件抽象"问题。当用户发出"打开门口的灯"这类指令时，代理通过查阅此文件将自然语言映射为具体的技术标识（如 IP 地址、设备 ID 或 SSH 别名）。该文件与 AGENTS.md（定义技术规范）、SOUL.md（定义价值观）构成代理的基础上下文层。

内容结构

TOOLS.md 包含两类核心信息：

工具别名与映射

该章节定义环境中可用工具的友好名称与技术参数的对应关系。典型内容包括：

• 局域网硬件别名："门口的摄像头"映射至 192.168.1.105:8080

• SSH 主机别名：staging 映射至 deploy@staging.example.com -p 2222

• 语音合成参数：默认音色 ID、语速、稳定性设置

• 常用命令缩写：logs 映射至 tail -f /var/log/app/error.log

工具调用指南

该章节规定代理调用工具时应遵循的协议：

• 执行外部命令（exec）前需查阅此处确认环境特定的路径与参数

• 使用浏览器（browser）工具时需参考此处记录的安全浏览策略

• 调用消息工具（message）时需确认默认通道与格式模板

与系统配置的关系

TOOLS.md 与系统级配置文件openclaw.json中的工具策略形成互补：

• openclaw.json 中的 tools.allow 与 tools.deny 定义访问控制策略（哪些工具可用）

• TOOLS.md 定义使用方式（如何使用这些工具）

代理工具策略遵循三层决策机制：

1. 系统级全局策略（tools.allow/tools.deny）

2. 代理级覆盖策略（agents.list[].tools.allow/deny）

3. TOOLS.md 中的使用指南（元数据与别名映射）

工具分组速记

在配置层面，OpenClaw 支持工具分组（Group）以简化策略管理，这些分组映射关系虽在配置文件中定义，但 TOOLS.md 可引用这些分组进行说明：

• group:runtime：exec, bash, process

• group:fs：read, write, edit, apply_patch

• group:sessions：会话管理五件套（sessions_list, sessions_history, sessions_send, sessions_spawn, session_status）

• group:memory：memory_search, memory_get

• group:web：web_search, web_fetch

• group:ui：browser, canvas

• group:automation：cron, gateway

• group:messaging：message

• group:nodes：硬件控制（nodes）

• group:openclaw：所有内置工具（不含第三方插件）

安全边界

TOOLS.md 不定义安全策略，但需与 SHIELD.md（安全策略层）协同工作。SHIELD.md 规定"当检测到某类威胁时如何响应"，而 TOOLS.md 规定"正常环境下如何使用工具"。两者在会话上下文中同时加载，形成"使用指南+安全防护"的双层结构。

四、IDENTITY.md

IDENTITY.md 承担"外在呈现"职能。它与 SOUL.md 构成互补关系：SOUL.md 定义内在性格与价值观，IDENTITY.md 定义外在身份标识与视觉表现。该文件解决"代理看起来是谁"的问题，而非"代理本质上是谁"的问题。

内容结构

IDENTITY.md 包含六个核心字段：

Name（名称）

定义代理的显示名称，如 "Kai"、"Samantha"、"C-3PO"。该名称将显示为消息前缀格式 [Name]，并用于生成群聊提及模式（如用户可输入 "@Samantha" 触发代理响应）。

Emoji（表情符号）

定义代理的图标标识，如 🤖、🦥、⚠️。该表情符号作为消息确认反应（ack reaction）使用：当消息到达代理时，系统自动以该表情回应表示已接收。若未配置，默认使用 👀。

Theme/Creature（主题/生物）

描述性标签，定义代理的拟人化形象，如 "helpful sloth"（乐于助人的树懒）、"Flustered Protocol Droid"（慌张的礼仪机器人）。该字段用于设定代理的"物种"或"原型"。

Vibe（氛围）

定义代理的沟通风格调性，如 "Anxious, detail-obsessed, slightly dramatic about errors"（焦虑、注重细节、对错误反应略夸张）。该字段指导代理的语气表现。

Avatar（头像）

定义视觉头像，支持三种格式：

• 工作区相对路径（如 avatars/samantha.png，必须位于代理工作区内）

• HTTP(S) URL

• Data URI

Greeting（问候语）

定义默认开场白，如 "Hey! What are you working on?"。该语句在特定交互场景下作为初始欢迎语使用。

技术实现

IDENTITY.md 位于 ~/.openclaw/workspace/IDENTITY.md（主代理）或 ~/.openclaw/agents/<agentId>/workspace/IDENTITY.md（特定代理）。

类型定义位于 src/agents/identity-file.ts，

采用 AgentIdentityFile 类型结构：

{
  name?:string;
  emoji?:string;
  theme?:string;
  creature?:string;
  vibe?:string;
  avatar?:string;
}

解析逻辑包含占位符过滤机制。模板中的提示文本（如 "pick something you like"、"ai? robot? familiar?"）在解析时被自动剔除，确保这些指导语不会成为实际身份标识。

运行时影响

IDENTITY.md 的配置直接影响以下系统行为：

消息前缀格式化：代理发送的每条消息前缀由 resolveIdentityNamePrefix 函数解析 IDENTITY.md 中的 name 字段生成，格式为 [Name]。

确认反应机制：系统通过 resolveAckReaction 函数读取 emoji 字段，作为消息接收确认的视觉反馈。若配置文件中未设置 emoji，且 openclaw.json 中未覆盖 messages.ackReaction，则使用默认值 👀。

群聊提及识别：网关系统根据 name 和 emoji 字段自动生成正则表达式模式，用于在多用户群聊环境中识别针对该代理的明确提及（explicit mentions）。

与系统配置的交互

IDENTITY.md 与 openclaw.json 中的 agents.list[].identity 配置项存在双向映射关系：

JSON 配置优先于文件配置。当 openclaw.json 中定义了 identity 对象时，其值作为默认值使用；若同时存在 IDENTITY.md 文件，后者可覆盖特定字段。

macOS 引导助手在初始化过程中会同时写入 openclaw.json 的 identity 配置和 IDENTITY.md 文件，确保一致性。

配置系统支持从 IDENTITY.md 派生其他默认值：

• messages.ackReaction 默认取自当前激活代理的 identity.emoji

• groupChat.mentionPatterns 默认基于 identity.name 和 identity.emoji 生成

多代理隔离

在多代理架构中，每个代理拥有独立的 IDENTITY.md 文件，存储于其专属工作区（~/.openclaw/agents/<agentId>/workspace/）。这允许：

• "work" 代理配置为正式商务身份（名称 "Executive Assistant"，emoji 📊）

• "personal" 代理配置为随意友好身份（名称 "Buddy"，emoji 🦥）

• "family" 代理配置为儿童友好身份（名称 "Helper"，emoji 🧸）

Token 消耗机制

IDENTITY.md 作为会话启动时加载的上下文文件之一，其内容被注入系统提示词。标准模板约 100-300 tokens，在固定启动开销中占比较小。但该文件的设计直接影响后续交互的 token 效率：简短的名称与问候语可减少每轮响应的开销。

更新与维护

IDENTITY.md 支持手动编辑与自动更新两种模式：

• 手动编辑：用户直接修改 Markdown 文件，变更立即生效于下一会话

• 自动演化：代理可通过访谈用户生成或更新该文件，但修改结果需经用户确认

与 SOUL.md（人格变更需明确告知用户）不同，IDENTITY.md 的更新（如更换 emoji 或头像）属于呈现层调整，无需特别通知用户，除非涉及名称变更可能影响群聊提及逻辑。

与 SOUL.md 的区分原则

IDENTITY.md 与 SOUL.md 的分离遵循"哲学与呈现分离"的设计原则：

• SOUL.md 回答"代理如何思考与行为"（内在性格）

• IDENTITY.md 回答"代理如何被识别与展示"（外在身份）

例如，SOUL.md 规定代理应"真诚助人而非表演性助人"，这是行为准则；IDENTITY.md 规定代理名为 "Kai" 并使用 🦥 作为头像，这是标识信息。两者可独立变更：代理可保持相同性格但更换名称，或保持相同身份但调整性格边界。

五、USER.md

USER.md 承担"用户画像"职能。它回答"我在为谁工作"这一根本问题，与 SOUL.md（定义代理如何沟通）形成互补：SOUL.md 确立沟通方式，USER.md 确立沟通背景。缺少该文件时，代理将缺乏对用户处境、偏好及优先级的理解，导致建议泛化且缺乏针对性。

内容结构

USER.md 建议包含以下维度的事实性信息：

基础标识

• 用户时区与地理位置

• 首选语言与沟通风格偏好

• 职业角色与工作描述

项目与目标

• 当前进行中的项目列表

• 各项目的优先级与截止日期

• 阻碍用户实现目标的关键因素

人际关系网络

• 组织内的关键人物及其与用户的权力动态

• 合作者、汇报对象、利益相关者清单

• 各关系人的沟通偏好与历史背景

个人背景

• 家庭结构与个人生活约束

• 工作习惯与生产力高峰期

• 已知的决策模式与行为倾向

加载机制与优先级

在会话启动流程中，AGENTS.md 规定代理于读取 SOUL.md 之后、读取记忆文件之前必须加载 USER.md。该文件与 AGENTS.md、SOUL.md、IDENTITY.md 同属"引导文件"（Bootstrap Files），在会话首回合被直接注入系统提示词。空白文件会被跳过，缺失文件会触发单行的"缺失标记"而非错误。

维护策略

USER.md 被设计为高频维护文件。建议每日花费五分钟根据当日情况进行微调，因为用户优先级、项目状态及人际关系动态每周均可能发生显著变化。该文件在每次互动中产生复利效应：代理根据其中定义的项目背景化研究建议，根据记录的人物关系起草针对性消息，无需用户重复交代基础信息。

与记忆系统的区分

USER.md 与 MEMORY.md 承担不同职能。USER.md 存储相对稳定的结构性画像（用户是谁、在什么组织、负责什么），MEMORY.md 存储演化的长期记忆（过往决策、错误纠正、新发现的事实）。前者在每次会话固定加载，后者仅在主会话（Main Session）中选择性加载。

Token 消耗机制

USER.md 作为会话启动时强制加载的上下文文件，产生固定 Token 开销。建议长度控制在 500-2000 tokens 范围内。过度简略（仅姓名与时区）会导致代理缺乏上下文而频繁询问基础信息，过度冗长则增加每次会话的固定成本。

多代理隔离

在多代理架构中，每个代理可拥有独立的 USER.md 文件，存储于其专属工作区（~/.openclaw/agents/<agentId>/workspace/）。这允许：

• "work" 代理配置职场身份与项目背景

• "personal" 代理配置家庭事务与个人目标

• 各代理基于特定身份理解同一用户的不同侧面

更新与演化

USER.md 支持手动编辑与自动更新两种模式。代理可通过访谈用户生成或更新该文件，但变更需经用户确认。与 SOUL.md（人格变更需明确告知）不同，USER.md 的事实性更新（如新增项目、变更优先级）属于常规维护，无需特别通知，除非涉及联系方式等敏感信息变更。

六、HEARTBEAT.md

HEARTBEAT.md 承担"自检清单"职能。它规定了代理在周期性"唤醒"（Heartbeat）时应完成的检查项，将自主行为约束在预定义的范围内。该文件与 Cron 作业共同构成 OpenClaw 的主动自动化体系：Cron 负责精确时间点的特定任务，HEARTBEAT.md 负责周期性环境感知与状态扫描。

触发机制

代理默认每 30 分钟执行一次心跳检查（使用 Anthropic OAuth 认证时默认为 1 小时）。系统在每次心跳时向代理发送固定提示词："Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK." 代理读取该文件后执行清单检查，若发现需要关注的事项则向用户发送通知，若无异常则回复 HEARTBEAT_OK 并保持静默。

内容结构

HEARTBEAT.md 采用简洁的清单格式，建议保持精简以避免提示词膨胀。典型内容包括：

• 紧急事项扫描：检查收件箱、日历冲突、系统监控警报

• 任务状态审查：确认后台任务完成情况，记录阻塞原因

• 轻量级问候：若用户长时间无活动（如 8 小时以上），发送友好问候

• 数据同步：执行 Git 拉取/推送等维护操作

智能抑制机制

若 HEARTBEAT.md 存在但内容为空（仅包含空白行或 Markdown 标题如 # Heading），OpenClaw 自动跳过该次心跳以节省 API 调用。若文件缺失，心跳仍执行，但由模型自主决定检查内容。当代理回复以 HEARTBEAT_OK 开头或结尾，且剩余内容不超过 ackMaxChars（默认 300 字符）时，系统抑制该消息的外发投递，实现"无异常不打扰"。

与 Cron 的区分原则

HEARTBEAT.md 与 Cron 作业在架构上存在明确边界：

• HEARTBEAT.md 在主会话（Main Session）中运行，保持上下文连续性，适合批量检查收件箱、日历、通知等需关联记忆的任务

• Cron 在隔离会话（Isolated Session）中运行，适合精确时间调度（如每周一上午 9 点生成周报）或需要不同模型/思考级别的任务

配置体系

HEARTBEAT.md 的行为受 openclaw.json 中的 heartbeat 配置项控制：

• every：检查间隔，支持 "30m"、"1h" 等格式，设为 "0m" 可禁用

• target：消息投递目标，可选 "last"（最后活跃渠道）、特定渠道或 "none"（运行但不外发）

• activeHours：限制心跳仅在指定时间段内执行（如工作时间 09:00-22:00）

• prompt：覆盖默认提示词，支持自定义检查逻辑

• model：指定心跳专用模型（如使用轻量级本地模型降低成本），但当前版本存在该配置项失效的 Bug

动态更新

HEARTBEAT.md 作为普通工作区文件，代理可在正常对话中应用户要求更新其内容，如添加新的检查项或优化清单结构。用户也可在提示词中明确指示："若检查清单过时，请更新 HEARTBEAT.md"。安全警告：禁止在文件中存储 API 密钥、电话号码等敏感信息，因其内容会被注入提示词上下文。

Token 消耗优化

心跳机制运行完整的代理回合（Agent Turn），短间隔会导致 Token 消耗增加。通过合理设计 HEARTBEAT.md 可将多个检查项批量处理（如一次心跳同时检查邮件、日历、天气），相比多个独立 Cron 作业显著降低 API 调用成本。使用轻量级模型（如flash模型）处理心跳可进一步压缩成本。

七、BOOTSTRAP.md

BOOTSTRAP.md 承担"首次引导"职能。它解决"冷启动"问题：当代理首次唤醒且无任何历史记忆时，需通过结构化问答快速建立基础身份认同与用户画像。该文件作为一次性 ritual（仪式）脚本，引导代理完成从"空壳"到"个性化助手"的初始化跃迁。

创建条件与生命周期

BOOTSTRAP.md 仅在严格条件下生成：当工作区目录不存在任何其他引导文件（AGENTS.md、SOUL.md、IDENTITY.md、USER.md、TOOLS.md）时，系统判定为"全新工作区"，自动创建该文件。若工作区已存在任一引导文件，即使 BOOTSTRAP.md 被手动删除，系统也不会重新创建。

文件生命周期严格限定为单次会话。代理首次运行时读取并执行其中指令，完成问答后将收集到的信息写入 IDENTITY.md（身份标识）、USER.md（用户画像）、SOUL.md（性格内核），随后立即删除 BOOTSTRAP.md。后续会话即使文件残存（如删除失败），系统也会跳过加载。

内容结构

BOOTSTRAP.md 包含分阶段引导指令，典型结构如下：

身份建立阶段

• 询问并设定代理名称（如 "Kai"、"Samantha"）

• 选择生物原型或主题（如 "helpful sloth"、"anxious protocol droid"）

• 设定沟通氛围（vibe）与表情符号（emoji）

用户画像阶段

• 收集用户姓名、时区、地理位置

• 询问当前优先事项与长期目标

• 记录工作习惯与偏好设置

记忆写入阶段

• 将收集信息结构化写入 IDENTITY.md、USER.md、SOUL.md

• 创建首条记忆日志（memory/YYYY-MM-DD.md）记录初始化事件

技术实现

在系统架构中，BOOTSTRAP.md 被归类为"引导文件"（Bootstrap Files），但其加载逻辑与其他引导文件存在本质差异。AGENTS.md、SOUL.md 等文件在每次新会话首回合被注入上下文，而 BOOTSTRAP.md 仅在首次运行时被注入，且执行完毕后系统立即执行删除操作。

该文件受 agents.defaults.bootstrapMaxChars 参数约束（默认 20000 字符），超大文件将被截断。用户可通过 openclaw setup 命令重建默认模板，但不会覆盖已存在的引导文件。

禁用机制

对于预配置工作区（如通过 Git 仓库分发的标准化配置），可通过在 openclaw.json 中设置 { agent: { skipBootstrap: true } } 完全禁用自动引导文件创建。此设置阻止系统生成 BOOTSTRAP.md 及其他默认引导文件，确保工作区保持预定义状态。

与初始化流程的关系

在标准首次运行流程中，系统按序执行：

1. 检测工作区为空，创建 BOOTSTRAP.md

2. 代理启动，读取 BOOTSTRAP.md 获取引导问题

3. 执行问答 ritual，逐轮收集信息

4. 将结构化数据写入持久化文件（IDENTITY.md、USER.md、SOUL.md）

5. 删除 BOOTSTRAP.md，标记初始化完成

该机制确保用户首次交互即完成个性化配置，无需手动编辑配置文件。初始化完成后，代理基于生成的 IDENTITY.md 与 USER.md 建立身份认同，后续会话不再依赖 BOOTSTRAP.md。

多代理隔离

在多代理架构中，每个代理工作区（~/.openclaw/agents/<agentId>/workspace/）拥有独立的 BOOTSTRAP.md。这允许不同代理针对特定场景执行定制化初始化 ritual，如"work"代理询问职场角色与项目背景，"personal"代理询问家庭结构与生活偏好。

八、提示词的动态构建机制

我还计划用几篇文章来深入讲解openClaw的定时任务、记忆体系等核心能力的用法和原理，如果有兴趣可以关注我。