AGENTS.md 截断规则深度解析——中文用户如何避免规则丢失

2026-06-22 · 技术分享 · #OpenClaw #AGENTS.md

一、问题的由来

很多 OpenClaw 用户发现，自己的 AGENTS.md 文件明明写了不少规则，但跑着跑着就「失忆」了——Agent 的行为开始偏离设定。这不是玄学，而是截断规则在作祟。

OpenClaw 的 bootstrap 文件（AGENTS.md、SOUL.md、MEMORY.md 等）都有总长度 60000 字符、单个文件 20000 字符的上限。一旦超限，就会触发截断。但 AGENTS.md 的截断方式与其他文件完全不同——而且这个差异，对中文用户尤其不友好。

本文将深入分析 AGENTS.md 的截断机制，并给出针对中文用户的优化方案。

二、截断规则对比

其他文件的截断策略

SOUL.md、MEMORY.md、TOOLS.md 等文件的截断规则是简单的「留头留尾」：

• 头部 45% — 原样保留
• 尾部 15% — 原样保留
• 中间 40% — 全部丢弃

这个策略简单粗暴：重要的东西写在开头和结尾，中间的内容可能直接消失。

AGENTS.md 的特殊策略

AGENTS.md 的截断分配比例为：

以 20000 字符上限为例：

• headChars = 9000 — 头部 9000 字符原样保留
• digestBudget = 7000 — 中间 7000 字符走摘要提取
• tailChars = 3000 — 尾部 3000 字符原样保留

关键区别就在这里：其他文件中间部分直接丢弃，但 AGENTS.md 会给中间区域一个「抢救」机会——通过关键字匹配提取重要规则行。

三、240 字符红线

在进入摘要提取流程前，所有行会先经过标准化处理：

• 删除行首行尾空白
• 连续空白压缩成一个空格
• 每行最多 240 字符，超长行保留前 239 字符加「…」

也就是说，如果你的规则行超过 240 字符，截断之后后半部分就没了。中文一个汉字占 2-3 字节，但按 Unicode 字符计数，240 字符大概相当于 80-100 个汉字的行长度。超过这个阈值，内容就会在摘要中被截断。

四、关键字匹配机制

标准化完成后，系统会从完整文件中扫描「候选行」，规则分为两类：

第一类：Markdown 结构行

任何以 Markdown 标题（#、##）或列表标记（-、*、1.）开头的行都会被识别为候选。

第二类：含关键字的普通行

包含以下关键字的行会被匹配（大小写不敏感）：

选取顺序

先扫描所有候选行，优先从高优先级关键字匹配行中选取，填满 7000 字符的摘要配额。如果还有剩余配额，再选普通候选行。

五、中文用户的大坑

注意上面的关键字列表——全是英文。这个匹配流程是纯字符串匹配，没有 LLM 参与理解语义。

这意味着：

• ✅ - Never commit secrets — 会被匹配（命中 never 和 secret）
• ❌ - 私事不外传 — 不会匹配（仅命中 Markdown 列表格式）
• ❌ - 必须：最大委派5轮 — 不会匹配（「必须」不是 required）
• ❌ ## 安全注意事项 — 仅靠 Markdown 标题格式匹配（##），不会命中 security

如果你完全用中文写 AGENTS.md，中间区域的内容能通过 Markdown 结构被保留一部分，但关键字匹配的优势完全享受不到。高优先级规则标记（如 required、must）对中文用户形同虚设。

六、优化建议

1. 核心规则中英双语写

每条重要规则加上英文关键词前缀，确保命中高优先级规则：

2. 控制行长度

每行控制在 200 字符以内（约 60-80 个汉字）。长规则拆成多行 Markdown 列表，既保可读性又匹配列表格式。

3. 关键内容放头部或尾部

头部 45%（约 9000 字符）和尾部 15%（约 3000 字符）是原样保留的，最核心的规则放在这两个区域。

4. 善用 Markdown 结构

用 ##、- 等 Markdown 语法结构化你的规则，即使关键字没匹配，Markdown 结构行本身也能被保留。

5. 监控文件大小

定期检查 ~/.openclaw/agents/main/agent/AGENTS.md 或 workspace 中的 AGENTS.md 文件大小。超过 15000 字符就要开始精简，留出冗余空间。

总结

AGENTS.md 的截断机制是一把双刃剑。它比普通文件多了一道「摘要提取」，试图保留中间区域的重要规则。但关键字匹配完全基于英文，中文用户如果不了解这套规则，辛苦写下的中文配置随时可能被截断丢弃。

了解规则、适配规则——这是让 OpenClaw 稳定记住你设定的关键。

参见：OpenClaw 官方文档 · GitHub 源码