03-多Agent · 02 共享规范

预计阅读：10 分钟适用版本：公开稳定包 OpenClaw 2026.5.2；作者端已验证 2026.5.7 · 最后审核：2026-05-09 本章回答：shared/ 下的 SOUL.md / AGENTS.md / TOOLS.md 到底怎么组织？bootstrap-extra-files 怎么演化？什么该共享、什么该独立？

问题的起点

多 agent 系统运行一段时间，你会发现：

每个 agent 的 SOUL.md 开头都是一样的几段（核心原则、禁区）
每个 agent 的 TOOLS.md 都列了一遍飞书工具
每次改派发规则，要同步改 5 个 agent 的 AGENTS.md

解决：抽出共享的一层 → ~/.openclaw/shared/。

这一层通过 bootstrap-extra-files 机制，在每个 agent 启动时自动注入 Project Context。改一次，所有 agent 下次启动时生效。

文件分工

文件	作用	变动频率
`shared/SOUL.md`	所有 agent 的共同核心原则（test-after-write、混淆写法禁用、多文件改动一变三查…）	低（稳定规则）
`shared/AGENTS.md`	通用协作规范（派发决策树、派发前确认流程、记忆五层架构）	中（每月可能调一次）
`shared/TOOLS.md`	所有 agent 共享的工具清单 + 路径别名 + 执行规范	中（加工具时改）

每个 agent 自己的 SOUL.md / AGENTS.md / TOOLS.md 补充特定于该 agent 的内容。

共享 vs 独立的判据

放 shared/ 的判据：

✅ 所有 agent 都要遵守的规则（如禁区、test-after-write）
✅ 通用工具（飞书工具链、LCM 工具、记忆工具）
✅ 通用协作规范（派发决策树、收口规则）

放 agent 自己的 判据：

✅ 该 agent 独有的职责 / 人设
✅ 该 agent 独有的工具（如 shangfang 的浏览器自动化工具）
✅ 该 agent 独有的业务知识（如 minsu 的房态 / 定价规则）

两边都不放（写在更细颗粒）：

📂 日志类事实 → memory/YYYY-MM-DD.md
📂 稳定经验 → agent 的 MEMORY.md（不是 SOUL/AGENTS/TOOLS）

bootstrap-extra-files 工作机制

启动时加载顺序

agent:bootstrap 触发
    ↓
① 读 agent 自己的 SOUL/USER/IDENTITY/HEARTBEAT/TOOLS/AGENTS（按固定顺序）
    ↓
② bootstrap-extra-files hook 触发
    ↓
③ 读 shared/SOUL.md、shared/TOOLS.md、shared/AGENTS.md
    ↓
④ 三个文件追加到 Project Context（不占启动序列位置）
    ↓
⑤ 读 MEMORY.md（仅直聊）+ memory/今日+昨日
    ↓
agent 就绪

配置启用

~/.openclaw/openclaw.json 真实配置位置 hooks.internal.entries.bootstrap-extra-files：

{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": [
            "shared/SOUL.md",
            "shared/TOOLS.md",
            "shared/AGENTS.md"
          ]
        }
      }
    }
  }
}

字段要点：

enabled 控制 hook 总开关
paths 是相对 ~/.openclaw/ 的相对路径（不写绝对路径）
每个 path 会作为独立 Project Context 块注入，agent 自身的 SOUL/USER/IDENTITY/TOOLS 仍按固定顺序优先加载

影响范围

✅ 所有 agent 都继承（无需一个个同步）
✅ 直聊 / 群聊 / subagent 派发都会触发
✅ /reset 或 /new 时重读

三个共享文件的典型结构

`shared/SOUL.md` 典型章节

# shared/SOUL.md · 家族通用核心原则

## 一、执行原则
- 先查本地状态再问用户
- 小步修改优于大重构
- 对外操作（发送/删除/花钱）前先确认

## 二、test-after-write 三步验证（强制）
任何配置 / API / 凭证修改后：
1. 写文件 → 立即读回确认
2. 读回确认 → 实跑功能验证
3. 验证成功 → 才回报"完成"

## 三、多文件改动：一变三查
1. 改动前 grep 列所有相关文件
2. 逐个修改并读回
3. 改动后 grep 对照

## 四、交叉引用验证法
改了 A，必须验证 B/C/D 的引用是否同步

## 五、混淆写法禁用
禁用 python3 -c / node -e / bash -c
替代：先写 /tmp/xxx.py，再 python3 /tmp/xxx.py

`shared/AGENTS.md` 典型章节

# shared/AGENTS.md · 家族通用协作规范

## 一、派发决策树
（消息进入 → 判断领域 → 路由到合适 agent）

## 二、派发前确认流程（强制）
（自动诊断 → 匹配场景 → 卡片确认 → 执行）

## 三、协作机制
（sessions_send / sessions_spawn 四种场景矩阵）

## 四、记忆五层架构
（L0~L4 各层的职责分工）

## 五、会话启动顺序
（SOUL → USER → IDENTITY → HEARTBEAT → TOOLS → AGENTS → MEMORY → memory/）

## 六、执行原则（通用补充）

## 七、收口规则
（结论写 memory/YYYY-MM-DD.md、扫描同步 SOUL/AGENTS/MEMORY）

## 八、自主记忆决策规则

详细参考作者真实的 ~/.openclaw/shared/AGENTS.md（8 大节 217 行）。

`shared/TOOLS.md` 典型章节

# shared/TOOLS.md · 家族通用工具配置

## 飞书交互工具链（通用）
| 工具 | 用途 |
| feishu_im_user_message send | 发飞书消息 |
| feishu_bitable_app_table_record | 多维表格 |
| ...                                |

## OpenClaw 系统工具
### Agent 派发：sessions_send / sessions_spawn / subagents list,steer,kill
### 记忆工具：memory_recall / memory_store / memory_forget / memory_update
### LCM 工具：lcm_grep / lcm_expand / lcm_expand_query

## 本地路径别名
~/.openclaw/* 的实际路径映射

## Shell / exec 规范
- 禁混淆写法
- gateway 管理命令

## OpenClaw 升级脚本路径
- backup-memory-plugin-upgrade.sh
- check-memory-plugin-upgrade.sh
- restore-memory-plugin-upgrade.sh
- apply-openclaw-cli-hotfixes.mjs

## Proactive Tool Use 原则

演化示例：一次规则的变更

说明”为什么改 shared/ 而不改每个 agent”。

背景

作者早期在每个 agent 的 SOUL.md 里都写着”遇事先查记忆再问用户”。后来发现这句话不够强，有些 agent 没查记忆就问。

错误做法

去 5 个 agent 的 SOUL.md 里各自补强这条规则 → 5 次改动，容易漏。

正确做法

把这条规则上卷到 shared/SOUL.md 的”执行原则”章节，改一次：

## 一、执行原则
-- 先查本地状态再问用户
+- 先查本地状态再问用户（强制：无记忆读回不得直接提问）
 - 小步修改优于大重构

下次任何 agent /reset 时自动生效。

什么时候反过来

不是所有规则都该上卷到 shared/。判据：

只适用某个 agent → 留在该 agent 的 SOUL（例：minsu 的”价格变动要先确认”）
适用所有 agent 但因语气差异不适合强制统一 → 留在各 agent（例：main 的”冷峻” vs yying 的”活泼”）

共享规范的版本管理

建议

把 ~/.openclaw/shared/ 纳入 git 版本控制（和 ~/.openclaw/workspace/memory/ 并列）：

cd ~/.openclaw/shared
git init
git add -A && git commit -m "init shared 规范"

好处：

改坏了能 git checkout 回去
按日期能 diff “这个月派发决策树改了什么”
多机器同步（私有仓库或 scp）

慎入 git：

❌ credentials/（绝对禁止）
❌ memory/lancedb-pro/（太大）
❌ logs/（动态生成）

一个稳定的 commit cadence

每周一次 commit shared/ 和 workspace/MEMORY.md
每月一次 tag（如 shared-v2026.04）

典型问题

Q：shared/ 改了，agent 为什么没生效？

三个可能：

没 /reset 或 /new —— bootstrap-extra-files 在每次 bootstrap 时才跑
hooks 配置失效 —— 查 openclaw doctor
改的是某个 agent 自己的 SOUL，而不是 shared/

Q：shared/SOUL.md 和 agent/SOUL.md 冲突了，按哪个？

原则：agent 自己的 SOUL.md 是补充，不是覆盖。两份会同时注入 Project Context，冲突时模型会综合考虑 —— 结果不可控。

正确姿势：

shared/ 放强约束（test-after-write、混淆禁用）
agent/ 放补充 + 个性，不重复写 shared/ 里的内容
发现冲突时，审视一下 —— 大概率是 shared/ 里写得不够清晰

Q：有没有”不注入 shared/” 的 agent？

有。比如 reflector 因为不面向用户、职责极简，作者让它只继承 shared/SOUL.md 不继承 AGENTS.md。具体是否要做，看你的架构。

Q：shared/ 目录能放别的文件吗？

可以。但只有配置在 bootstrap-extra-files 里的文件才会被注入。放个 shared/NOTES.md 也没人读，除非你加到 hooks 配置。

验证清单

配好 shared/ 后验证：

检查项	怎么验
bootstrap 注入生效	任意 agent 的第一条消息问”你的派发决策树是什么”，应能念出 shared/AGENTS.md 的内容
不是每个 agent 单独配	去掉某个 agent 自己的 AGENTS.md，它应该还能引用派发决策树（因为 shared 的补位了）
/reset 后重读	改 shared/SOUL.md 的某条，/reset 后问 agent，应反映最新改动
shared 未污染业务 agent 人设	问 yying（运营助手）的 vibe，不应回答得像 main 那样冷峻（shared/SOUL.md 不该规定语气）

常见误用

误用 1：把业务知识写进 shared/AGENTS.md

❌ shared/AGENTS.md
   "关于民宿业务：定价参考去哪儿 + 美团..."

✅ agents/minsu/MEMORY.md
   "关于民宿业务：定价参考去哪儿 + 美团..."

原因：不是所有 agent 都需要懂民宿。

误用 2：把 agent 人设写进 shared/SOUL.md

❌ shared/SOUL.md
   "我是智能管家，冷峻务实..."

✅ agents/main/IDENTITY.md
   "智能管家 vibe：冷峻务实..."

原因：每个 agent 人设不同。

误用 3：为 shared/ 加版本号后缀

❌ shared/SOUL.v2.md  shared/AGENTS.v3.md

bootstrap-extra-files 读固定路径，加后缀会让 hooks 配置失效。要版本用 git，不要文件名。

下一步

04-运维/03-备份与恢复 —— shared/ 的备份策略
02-配置/00-多Agent架构 —— 规划 agent 数时预留共享层设计
档位 2 templates/shared/ —— 付费用户可直接拿到作者去个性化的 shared 模板

本章准确性保证 三个共享文件的典型章节结构基于作者真实 ~/.openclaw/shared/ 的 SOUL.md（163 行）/ AGENTS.md（217 行）/ TOOLS.md（147 行）。bootstrap-extra-files hook 的真实配置位置 hooks.internal.entries.bootstrap-extra-files（enabled + paths[] 结构）已对照 openclaw.json 实测。

导航：← 委派机制 · 📖 目录 · → 健康检查