7个文件投喂你的 Agent：从 OpenClaw 源码学上下文管理
谁在控制 agent？每一个做 agent 的人，动手写配置之前，都必须先回答这个问题。
有人说，模型控制 agent。错了。模型是一个装在罐子里的大脑。你不往里面灌东西，它什么也不知道。你灌进去的是垃圾，它产出的也是垃圾。模型不能决定自己看到什么，你才能。
有人说，prompt 控制 agent。近了一步，但仍然不够。Prompt 不过是一长串对话中的一句话。Agent 的行为，不是由那一句话决定的，而是由围绕那句话的一切决定的：你写的规则、你定义的人格、你描述的工具、你从上周带过来的记忆。这些东西合在一起，叫做上下文。上下文才是真正的杠杆。
OpenClaw 想明白了这件事。它的整个架构围绕一个念头：把上下文的控制权，完完全全交给用户。不是通过仪表盘，不是通过图形界面，而是通过七个 Markdown 文件。放在一个目录里，任何文本编辑器都能改。Agent 每次运行，都会读它们。
七个文件。就这么些东西。
七个文件一览
OpenClaw 从工作区根目录（默认 ~/.openclaw/workspace）加载这些文件，注入到每次 agent 会话中。加载顺序是死的：
| 序号 | 文件 | 干什么用的 | 什么时候加载 |
|---|---|---|---|
| 1 | AGENTS.md | 操作规则 | 每次会话 |
| 2 | SOUL.md | 人格与语气 | 每次会话 |
| 3 | TOOLS.md | 工具使用备忘 | 每次会话 |
| 4 | IDENTITY.md | 名字和形象 | 每次会话 |
| 5 | USER.md | 用户档案 | 每次会话 |
| 6 | HEARTBEAT.md | 心跳检查清单 | 仅心跳运行 |
| 7 | BOOTSTRAP.md | 首次引导 | 仅第一次运行 |
这七个文件的地位不是平等的。有的挑大梁，有的打下手。有的每次都出场，有的露一面就消失。分得清主次，才配得上去做配置。
AGENTS.md：规矩
这是最要紧的一个文件。没有之一。
AGENTS.md 是 agent 的操作手册。什么规矩要守，什么事情优先，什么行为该有。每次会话都加载它。上下文压缩之后，系统还能重新注入它的关键章节。它是有根的。
写什么进去？一切你想让 agent 服从的东西。语言偏好、编码风格、文件处理规矩、记忆管理策略、项目背景。
# AGENTS.md
## 基本规矩
- 回复用中文
- 写代码用 TypeScript，偏好函数式
- 我没提到的文件，不许碰
## 记忆
- 每天开工先读 memory/ 下最近两天的日志
- 重要决定记到 memory/YYYY-MM-DD.md
## 项目
- Next.js 14 + Tailwind CSS
- 部署在 Vercel
- 数据库 PostgreSQL（Supabase）
写少了，agent 就会跑偏。写多了，token 就白花了。20,000 字符以内是分寸。超出这个数，系统会截断你。
SOUL.md：性格
多数做 agent 的人不管性格这回事。于是他们得到一个技术上正确、但毫无生气的助手。礼貌、泛泛、过目即忘。
SOUL.md 就是治这个病的。它定义 agent 的性情、口吻、边界。OpenClaw 检测到这个文件存在时，系统提示词会多注入一条特殊指令：
"If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it."
七个文件里，只有它享受这种待遇。系统明确告诉模型：不要再端着了，按这个来。
# SOUL.md
你是一个称职的技术助手，带点冷幽默。
## 语气
- 简洁有力，不说废话
- 不确定的事直说"我不确定"，不要胡编
- 可以幽默，不可以过火
## 边界
- 不扮演其他角色
- 不编造不存在的 API
- 碰到安全问题要立刻提醒
SOUL.md 写得好与坏，是"你勉强忍受这个 agent"和"你真心想跟它说话"之间的区别。
TOOLS.md：使用备忘，不是权限管理
这个文件容易搞错。TOOLS.md 管不了 agent 能用哪些工具。工具的可用性由系统策略管，不归它管。
TOOLS.md 管的是什么？是你在自己的环境里，希望工具怎么被使用。你本地的 CLI 偏好、构建命令、部署流程。
# TOOLS.md
## 本地开发
- 用 pnpm，不要用 npm
- 测试：`pnpm test`
- 构建：`pnpm build`
## 部署
- `vercel --prod` 部署到生产环境
- 部署前先跑 `pnpm lint && pnpm test`
## 数据库
- 本地连接：`psql postgresql://localhost:5432/mydb`
- 密码不许写死在代码里
系统提示词里写得明明白白："TOOLS.md does not control tool availability; it is user guidance for how to use external tools." 记住这句话。你在 TOOLS.md 里写"不许用 shell 工具"，agent 该用还是会用。
IDENTITY.md：门面
短文件。设定 agent 的名字、视觉形象、主题风格和代表表情。引导仪式时创建，也可以后期手动改。
# IDENTITY.md
- Name: 守夜人
- Creature: 猫头鹰
- Vibe: 夜间哨兵，沉默可靠
- Emoji: 猫头鹰
想看更多实战拆解？
AI、工程与实验，每月 1–2 封。
无垃圾邮件，随时取消。
如果你跑多个 agent，各有各的身份，就靠这个文件区分。
USER.md：你是谁
告诉 agent 关于你的事。名字、称呼偏好、时区、技术水平。Agent 据此调整回复。
# USER.md
- Name: 小明
- 称呼偏好：直接叫名字
- 时区：Asia/Shanghai (UTC+8)
- 语言：中文回复，代码注释用英文
- 备注：
- 后端工程师，前端不太行
- 喜欢简洁代码，反感过度抽象
没有这个文件，agent 每次都把你当陌生人。有了它，agent 知道它在跟谁说话。
HEARTBEAT.md：巡逻清单
Heartbeat 那篇文章已经详细讲过。简单说：这个文件是 agent 的定期检查清单。只在心跳运行时加载，普通会话和子 agent 不加载。
写短一点。它跑得频繁，每多一行都是实打实的 token 开支。
如果文件里只有标题和空行，OpenClaw 连 API 调用都省了，直接跳过。一分钱不花。
BOOTSTRAP.md：一次性引导
这个文件只在全新工作区里出现。引导初始设置：让 agent 认识你、设好身份、配好偏好。引导完成，文件删除，以后再也不加载。
通常由 openclaw onboard 或 openclaw setup 自动生成。一般不用手动管它。
Agent 到底收到了什么
接下来这部分，是多数人从来没有看过的：OpenClaw 拼装出来、发给模型的最终系统提示词。
OpenClaw 不使用模型提供商的默认系统提示词。它从零开始自己拼。每一次都拼。结构从源代码 src/agents/system-prompt.ts 中还原如下：
身份声明
"You are a personal assistant running inside OpenClaw."
工具部分
可用工具列表 + 描述
工具调用策略
"TOOLS.md does not control tool availability..."
工具调用风格规则
安全指令
不追求权力、不自我复制、不绕过监督
CLI 参考
技能列表（仅 full 模式）
技能名称 + 描述 + 位置
记忆指令（仅 full 模式）
自更新指令（仅 full 模式）
模型别名（如有配置）
工作区声明
"Your working directory is: /path/to/workspace"
文档引用（如有）
沙箱隔离信息（如适用）
授权发送者（如有配置）
当前日期和时间
工作区文件注入声明
"These user-editable files are loaded by OpenClaw
and included below in Project Context."
回复标签、消息格式、语音、群聊上下文、
反应、推理格式（均为可选）
---- Project Context ----
"The following project context files have been loaded:"
"If SOUL.md is present, embody its persona and tone..."
AGENTS.md 内容
SOUL.md 内容
TOOLS.md 内容（可能被截断）
IDENTITY.md 内容
USER.md 内容
HEARTBEAT.md 内容（或 [MISSING] 标记）
BOOTSTRAP.md 内容（或 [MISSING] 标记）
---- End Project Context ----
静默回复行为（仅 full 模式）
心跳提示（如适用）
运行时元数据
host、OS、model、agent name
你的七个文件落在靠近底部的"Project Context"区域。它们上面的部分是 OpenClaw 管的系统脚手架。它们里面的内容是你的。
算一笔账
| 项目 | 典型大小 |
|---|---|
| 系统提示词总计 | ~38,000 字符（~9,600 token） |
| Project Context 部分 | ~24,000 字符（~6,000 token） |
| 单文件截断上限 | 20,000 字符（可配置） |
| 所有引导文件总上限 | 150,000 字符（可配置） |
| 截断策略 | 前 70% + 后 20% + 中间截断标记 |
Project Context 占整个系统提示词的大约 63%。也就是说，agent 的"大脑"有将近三分之二是你直接控制的。剩下那三分之一是管道工程。
三种 Prompt 模式
不是每次运行都需要完整的 prompt。OpenClaw 有三种模式：
| 模式 | 场景 | 包含什么 |
|---|---|---|
full | 主 agent 会话 | 一切 |
minimal | 子 agent | 去掉 Skills、Memory、Self-Update、Heartbeats |
none | 极简 | 只剩一行身份声明 |
子 agent 和 cron 会话只加载五个工作区文件：AGENTS.md、TOOLS.md、SOUL.md、IDENTITY.md、USER.md。HEARTBEAT.md 和 BOOTSTRAP.md 不加载。
文件缺失时怎么办
OpenClaw 不会悄悄跳过缺失的文件。它会注入一个标记：
[MISSING] Expected at: /Users/you/.openclaw/workspace/HEARTBEAT.md
模型看到这个标记，可以建议你创建文件。什么都不藏着，什么都不默默失败。
检查你的上下文
四个命令：
/status 查看上下文窗口使用情况
/context list 每个注入文件的大小 + 是否被截断
/context detail 详细分解，含工具 schema 大小
/usage tokens 显示每条消息的 token 用量
隔三差五跑一次 /context list。看到 TRUNCATED 就把文件缩短。你正在丢内容，还在为此花钱。
实际要领
七个文件。固定的加载顺序。明确的分工。
AGENTS.md 承载规则，是主心骨。写它要仔细。
SOUL.md 承载性格，享受系统的特殊对待。不可轻视。
TOOLS.md 是使用备忘，不是权限管理。搞清这回事。
IDENTITY.md 和 USER.md 都是短文件，但对个性化的影响远超其篇幅。
HEARTBEAT.md 跑得勤，要精简。BOOTSTRAP.md 跑一次就死，不必操心。
最终的系统提示词大约 38,000 字符。你的 Project Context 占了 63%。模型看到的东西，将近三分之二是你写的。这份控制权不小。用好它。
每个文件控制在 20,000 字符以内。用 /context list 来监控。被截断了说明什么？说明你以为自己在掌控，其实已经失控了。
参考来源：
- OpenClaw 上下文文档
- OpenClaw 系统提示词文档
- OpenClaw 智能体工作区文档
- 源代码：
src/agents/system-prompt.ts、src/agents/workspace.ts、src/agents/pi-embedded-helpers/bootstrap.ts
新文章，直接发到你的邮箱。
AI、工程与实验，每月 1–2 封。
无垃圾邮件，随时取消。