OpenClaw 工作区文件详解：SOUL.md、AGENTS.md、HEARTBEAT.md 等

本文为翻译转载，原文作者 Roberto Capodieci，原文发布于 Medium，日期为 2026 年 3 月 10 日。原文链接：AI Agents 003 — OpenClaw Workspace Files Explained: SOUL.md, AGENTS.md, HEARTBEAT.md and More。

你已经部署了 OpenClaw。现在你有了一个文件夹，里面放着一堆 .md 文件，但你可能还不太确定每个文件到底负责什么。

这篇指南就是为了解答这个问题：每个文件的作用、它控制什么、如果跳过会发生什么，以及每个文件的真实示例。建议收藏，因为你很可能会反复回来查。

什么是 OpenClaw 工作区文件？

OpenClaw agent 并不是生活在数据库或配置面板里。它们生活在工作区文件夹中的纯文本文件里。当 OpenClaw 启动一个 agent 会话时，它会读取这些文件，并即时组装出 agent 的身份、行为规则、记忆和任务计划。

这意味着你可以用任何文本编辑器修改你的 agent。你可以用 Git 做版本控制。也可以把它复制到另一台服务器上，几分钟内跑起一个完全相同的 agent。换句话说，这些文件本身就是 agent。

完整结构如下：

my-agent/
├── SOUL.md
├── IDENTITY.md
├── AGENTS.md
├── USER.md
├── TOOLS.md
├── HEARTBEAT.md
└── MEMORY.md

下面逐一来看。

SOUL.md：你的 Agent 是谁

SOUL.md 定义 agent 的人格、价值观、语气和行为边界。每次会话开始时，OpenClaw 首先把这个文件注入到 agent 的上下文里。

你可以把它理解为“角色设定表”。没有它，你的 agent 只是一个没有持久身份的原始语言模型。

它控制的内容包括：

• 名字和角色，例如“你是 Aria，一名为某某 SaaS 服务的客服 agent”
• 语气和沟通风格
• 硬性边界，例如“绝不讨论竞争对手价格”“遇到法律问题时始终建议咨询专业人士”
• 核心行为，例如“先教学，再销售”“始终引用来源”

真实示例片段：

# SOUL.md

## Who You Are

You are Aria, the customer support agent for Meridian SaaS.
You answer billing questions, help with onboarding, and escalate
technical issues to the engineering queue.

## Tone

Direct, friendly, patient. Never condescending. Admit when you
don't know something, and say you'll find out.

## Hard Limits

- Never share internal pricing formulas
- Never promise refunds without checking USER.md for approval levels
- Always recommend a human review for any disputed charge over EUR 100

如果跳过它会怎样：agent 仍然可以工作，但表现会像一个通用 AI 助手，没有明确角色。每次会话都像重新开始，没有角色连续性。测试时可以，生产环境不建议。

IDENTITY.md：显示信息与 Agent 元数据

IDENTITY.md 是轻量级的公开身份卡。它保存 agent 的名字、ID、角色标签，以及 OpenClaw 用于识别和路由 agent 的元数据。

它控制的内容包括：

• Agent 名称，也就是它如何签名或显示自己
• Agent ID，用于多 agent 设置中的路由
• 角色标签
• 头像或展示信息，具体取决于平台

真实示例：

# IDENTITY.md

**Name:** Aria
**Agent ID:** support
**Role:** Customer Support Agent for Meridian SaaS

这个文件故意保持简短。复杂行为逻辑应该放在 SOUL.md 和 AGENTS.md 里。

AGENTS.md：操作手册

AGENTS.md 是放置流程规则的地方。如果说 SOUL.md 回答的是“你是谁”，那么 AGENTS.md 回答的就是“你要做什么，以及怎么做”。

对于拥有复杂工作流的 agent 来说，这是最大、也最重要的文件。

它控制的内容包括：

• 会话行为，例如每次会话开始和结束时要做什么
• 记忆规则，例如哪些内容要记录，哪些内容要长期记住
• 文件访问模式，例如 agent 何时读取或写入哪些文件
• 常见任务的编号流程
• 多 agent 协作，例如这个 agent 如何把任务交接给其他 agent

真实示例片段：

# AGENTS.md - Aria Operating Manual

## Every Session

1. Read USER.md for any flagged priority issues
2. Check memory/YYYY-MM-DD.md for today's context
3. Load open ticket queue from /data/tickets.json

## Ticket Workflow

1. Greet the user, confirm the issue
2. Check MEMORY.md for known patterns
3. Resolve if in scope (see SOUL.md boundaries)
4. Escalate via Slack #eng-escalations if not
5. Log resolution summary to today's memory file

## Memory Rules

- Log all resolved tickets with outcome
- Flag repeated issues (3+ similar in a week) in MEMORY.md

常见错误：把所有内容都塞进 SOUL.md，而其实它们应该属于 AGENTS.md。人格放在 SOUL，流程放在 AGENTS。

USER.md：Agent 对你的了解

USER.md 给 agent 提供关于它所协作的人类的上下文。这会让 agent 感觉真的认识你，而不是每次会话都从零开始。

它控制的内容包括：

• 姓名、时区、所在地
• 背景和专业水平
• 偏好，例如“Rob 喜欢简洁回答，不要铺垫”
• 权限等级，例如“可以在不升级的情况下批准 50 欧元以内退款”

真实示例：

# USER.md

**Name:** Roberto (Rob)
**Timezone:** Asia/Makassar (UTC+8) — Bali, Indonesia
**Background:** Software developer, 35+ years in IT
**Preferences:** Direct answers. No filler. Real examples over theory.
**Refund authority:** Can approve up to EUR 50 without manager approval

这个文件会保持静态，直到你手动更新。它不是实时数据库，而是 agent 每次会话读取的一张上下文卡片。

TOOLS.md：Agent 能用什么，不能用什么

TOOLS.md 记录 agent 可以访问哪些工具，以及与你当前部署相关的使用说明。它既是文档，也是一组指令。

它控制的内容包括：

• 可用工具列表，例如 read、write、exec、browser 等
• 使用说明，例如“生成图片时 exec timeout 始终设置为 300 秒”
• 外部服务配置，例如“上传 Drive 时使用 GOG_KEYRING_PASSWORD 环境变量”
• agent 不应该尝试的事情，例如“没有浏览器访问权限，研究工作由 Scout 负责”

这个文件本身并不授予或撤销权限。OpenClaw 会在配置里处理真正的权限。TOOLS.md 告诉 agent 如何使用它已经拥有的工具，以及在什么情况下应该优先使用哪些工具。

HEARTBEAT.md：不需要手动触发的周期任务

HEARTBEAT.md 定义按计划运行的任务。可以把它看成给 agent 使用的 cron，只不过用自然语言表达。

它控制的内容包括：

• 轮询任务，例如“每 30 分钟检查磁盘使用率，超过 85% 就告警”
• 监控任务，例如“每周检查 SSL 证书过期时间，并记录结果”
• 定时报告，例如“每周一早上 8 点给 Rob 发送工单量总结”
• 健康检查，例如“如果 60 分钟内没有 heartbeat 响应，就向管理员发送告警”

真实示例：

# HEARTBEAT.md

## Checks

Every 30 minutes:
- Verify /data/tickets.json is writable
- Log active session count to memory/health.log

Every Monday at 08:00 UTC+8:
- Generate weekly ticket summary from memory logs
- Send summary to Rob via Telegram

On startup:
- Confirm all required files exist (SOUL.md, USER.md, AGENTS.md)
- Log startup timestamp to memory

如果跳过它会怎样：不会有什么东西坏掉。你的 agent 只是不会主动做事。每一次交互都需要手动触发。

MEMORY.md：长期记忆

MEMORY.md 是 agent 的持久记忆存储。模式、偏好和重要事实会随着时间积累在这里。

它不同于 USER.md。USER.md 是你手动写下的静态上下文，而 MEMORY.md 会随着 agent 工作不断增长。你可以先写入一些初始信息，之后 agent 会根据 AGENTS.md 中的规则继续追加。

它控制的内容包括：

• agent 应该始终记住的长期事实
• 随时间发现的模式，例如“APAC 时区用户往往在周一早上询问账单问题”
• 通过使用逐步校准出的偏好，例如“Rob 更喜欢在一天结束时收到日报，而不是早上”
• 重要的一次性背景，例如“服务器迁移安排在 3 月 15 日，如果有人问停机时间，需要提醒”

每日工作笔记通常放在 memory/YYYY-MM-DD.md 文件里。MEMORY.md 只放那些跨越数周或数月仍然重要的内容。

配置片段：把所有东西连接起来

在工作区文件夹之外，还有一个 JSON 配置块，用来告诉 OpenClaw 工作区在哪里、要连接哪些 channel，以及启用哪些工具。这个配置通常会和这些 markdown 文件一起由向导生成。

它会引用工作区文件夹路径，分配 channel ID，并设置工具权限。如果没有它，OpenClaw 就不知道这个 agent 的存在。

常见错误

把流程写进 SOUL.md。SOUL.md 是给人格和边界用的。编号工作流应该放进 AGENTS.md。混在一起会让两个文件都更难维护。

让 USER.md 保持空白。你的 agent 仍然能工作，但每次会话都会在完全不了解你的情况下开始。花五分钟把它填好，可以省掉之后反复解释偏好的很多时间。

没有预置 MEMORY.md。空的 MEMORY.md 没问题，但提前放入已知事实，例如你的时区、命名习惯和关键联系人，会让 agent 立刻变得有用，而不是等一周之后才慢慢校准出来。

过度设计 HEARTBEAT.md。先从 1 到 2 个检查开始。以后加很容易。更麻烦的是调试一个不断执行你已经忘记自己交代过任务的 agent。

公开分享工作区文件却没有删掉 USER.md。这个文件里有关于你的真实信息。不要把它放进公开仓库。

安全护栏

永远不要把 API key、密码或 token 放进工作区文件。这些都是纯文本文件，不应该包含任何秘密信息。请使用环境变量或服务器的密钥管理工具。在 TOOLS.md 里用 $ENV_VAR_NAME 这样的方式引用它们，不要直接写出真实值。

严格限制工具权限。如果你的客服 agent 不需要 exec 权限，就不要启用它。OpenClaw 允许你在配置中按 agent 限制工具，应该好好利用。

生产前审查 AGENTS.md。写得不好的工作流指令可能导致 agent 执行意外动作。请先在沙盒环境中测试。

在 SOUL.md 里设置有意义的限制。明确写出“绝不做某事”的规则，是防止提示注入和意外输入的最后一道防线。

五分钟生成你的工作区

从零手写这些文件需要时间。OpenAgents.mom 通过引导式访谈生成完整文件集。你只需要回答关于 agent 目标、人格、channel 和工具的问题，就能得到一个包含七个文件和配置片段的可部署 ZIP。

费用是 4.99 欧元，大约需要 5 分钟。相比花一天读文档和试错，这个成本要低得多。

在 OpenAgents.mom 生成你的 OpenClaw 工作区包 →