第3章 OpenClaw核心配置体系与权限管理

本章前置检查：
□ OpenClaw已成功运行（完成第2章内容）
□ 能通过CLI或Web UI收发基础消息
□ 理解Agent的基本概念（第1章）
□ 有一份自己的文档/小说文件用于RAG测试（可选，推荐）

本章预估总时长：7小时
本章难点提示：

• 3.4节 RAG配置涉及向量检索概念，建议动手实践时边做边理解
• 3.5节 多Agent权限隔离是量化系统的安全底线，务必反复确认
• 跨Agent记忆查询的性能优化（3.5.4）是进阶内容，可以先跳过，等遇到性能问题再回看

🎯 本章教学目标：掌握Agent配置方法，独立定义Agent的角色和行为，配置RAG知识库，理解并正确配置多Agent权限体系和知识访问控制。

3.1 AGENTS.md：结构化Agent定义

🎯 本节目标：学会用AGENTS.md文件定义一个完整的Agent，无需编写代码。

预计时长：1小时

什么是AGENTS.md？

AGENTS.md是OpenClaw中最核心的Agent定义文件。它是一个Markdown格式的文档，通过YAML frontmatter和章节结构，声明Agent的职责、目标、技能、工作流和约束。

核心设计理念：把Agent的“人格”和“能力”写成文档，而不是代码。OpenClaw把Agent的身份（是什么、做什么、怎么做）与基础设施（工具编排、记忆持久化、会话管理、渠道路由）分开了——基础设施由平台处理，身份由你在Markdown文件中定义，而且这些文件可以被版本控制-41。这让非程序员也能配置Agent，也让Agent的行为可以被审查和迭代。

龙马注：我在Git仓库里放了一个/claw-agents目录，里面几十个AGENTS.md，改Agent配置就跟改代码一样，git diff一下就知道谁改了什么——这才是工程化的优雅。

AGENTS.md的标准结构

markdown

---
name: Agent显示名称
role: 角色描述（如“内容创作助手”）
type: default  # default / team_lead / subagent
---

## 职责
- 职责1
- 职责2

## 目标
- 目标1（可量化）
- 目标2

## 技能
- skill_name_1
- skill_name_2

## 工作流
1. 步骤1
2. 步骤2

## 约束
- 约束1（硬性限制）
- 约束2

## 输出格式
期望的输出格式模板

字段详解

name（必填）
Agent的显示名称，用于在Web UI和日志中标识。

role（必填）
简短描述Agent的角色，例如“数据分析师”“客服专员”“交易执行员”。

type（可选，默认default）

• default：普通Agent，接收消息并回复
• team_lead：团队领导Agent，可以协调其他Agent（第5章会用到）
• subagent：子Agent，由其他Agent动态创建（第6.1节）

职责（推荐）
用列表形式描述Agent的核心职责。这些内容会被注入到系统提示词中，影响LLM对Agent角色的理解。职责写得越具体，Agent的行为就越可控-41。

目标（推荐）
可量化的目标，例如“将客户咨询的响应时间控制在30秒内”“每周生成3篇高质量文章”。目标帮助LLM理解什么是“好的表现”。

技能（可选）
列出该Agent可以使用的Skill名称。Skill需要在skills/目录中存在（第4章会详细讲解）。如果不指定，Agent可以使用所有已安装的Skill。

工作流（推荐）
描述Agent处理任务的标准流程。这对于需要确定性步骤的任务（如交易执行、数据清洗）尤其重要。

约束（强烈推荐）
硬性限制，例如“单笔交易金额不超过10000元”“不允许删除文件”。约束会被注入系统提示词，并在工具调用时进行校验。

输出格式（可选）
如果Agent的输出需要被其他系统解析（如JSON格式），可以在这里定义模板。

沈飞注：我在交易Agent的AGENTS.md里写了“任何偏离风控阈值的信号，都必须先向风控Agent询问后再执行”，然后风控Agent那边“禁止任何Agent修改风控阈值”。这两个约束配合起来，就形成了一道硬边界。一旦触犯，交易就直接被阻断。

实战示例：定义一个“小说写作助手”Agent

假设你正在写一部长篇小说，需要一个Agent帮你保持人物设定和情节一致性。

创建文件 ~/.openclaw/workspace/agents/novel_writer/AGENTS.md：

markdown

---
name: 小说写作助手
role: 帮助作者保持小说世界观和人物设定的一致性
type: default
---

## 职责
- 根据用户提问，从已写章节中检索相关信息
- 检查新写章节是否存在与之前设定的矛盾
- 提供人物关系图谱和情节时间线的查询

## 目标
- 准确率：回答关于设定的问题时，错误率低于5%
- 响应速度：90%的查询在10秒内完成

## 技能
- novel_knowledge_rag（自定义RAG Skill，第4章会开发）
- plot_consistency_check

## 工作流
1. 用户提问关于小说设定的问题
2. 从RAG知识库中检索相关章节
3. 综合检索结果生成回答
4. 如果发现矛盾，明确指出并提供修改建议

## 约束
- 不能修改原始小说文件（只读权限）
- 不能生成新的章节内容（仅分析和查询）
- 回答必须引用来源章节（标注章节号）

## 输出格式
【回答】: <基于检索结果的回答>
【来源】: 第X章、第Y章
【一致性检查】: <如发现矛盾，在此说明>

龙马注：你可以把ROLE字段写得极细，比如“你是喜羊羊，住在羊村，最好的朋友是沸羊羊，最讨厌灰太狼。”——Agent真的会按这个角色来对话，语气和立场都不变。

加载Agent

定义好AGENTS.md后，使用以下命令加载：

bash

openclaw agent load --file ~/.openclaw/workspace/agents/novel_writer/AGENTS.md

加载成功后，你可以通过--agent novel_writer参数调用这个Agent：

bash

openclaw message send --agent novel_writer --message "主角在第3章中提到他怕水，第10章他出海了，这有矛盾吗？"

Agent的存储位置

OpenClaw会在工作区目录下为每个Agent创建一个子目录。不同的Agent运行在各自独立的工作区目录中，有自己的配置、记忆和状态-：

~/openclaw-workspace/
├── agents/
│   ├── default/           # 默认Agent
│   │   └── AGENTS.md
│   ├── novel_writer/      # 自定义Agent
│   │   └── AGENTS.md
│   └── ...
├── memory/                # 记忆存储（按Agent隔离）
│   ├── default/
│   └── novel_writer/
└── ...

⚠️ 常见误区：

• 忘记在frontmatter中写---包裹的YAML头——会导致解析失败
• 技能名称写错——Agent不会报错，但技能不会被加载
• 约束写得太模糊（如“不要犯错”）——LLM无法理解，应该写具体规则

✏️ 即时自测：AGENTS.md中的“约束”和“职责”有什么区别？

🛠️ 实践任务（本节）：按照上面的示例，创建一个名为my_first_agent的AGENTS.md文件，定义它的职责是“帮我整理每日新闻摘要”。加载并测试。

💭 本节总结（不看书写3行）：
1.
2.
3.

📊 用时记录：计划____min → 实际____min → 偏差原因：________

✏️ 自测答案：职责描述Agent“应该做什么”（正向引导），约束描述Agent“不能做什么”（硬性限制）。

3.2 三大人格配置文件：SOUL.md / IDENTITY.md / USER.md

🎯 本节目标：通过人格配置文件让Agent拥有独特的“性格”，提升交互体验。

预计时长：1小时

为什么需要人格配置？

AGENTS.md定义了Agent的“工作职责”，而人格配置定义了Agent的“说话方式”和“价值观”。一个好的Agent不仅要把事情做对，还要让人愿意和它交流。AGENTS.md告诉你“该怎么干活”，而SOUL.md定义“你是什么样的人”——两者互相配合，前者管逻辑，后者管性情-。

OpenClaw工作区目录下，期望存在以下可由用户编辑的文件-：

文件	作用	影响范围
AGENTS.md	操作说明 + “记忆”	Agent的工作方式
SOUL.md	人格、边界、语气	核心价值观和沟通风格
IDENTITY.md	智能体名称/风格/表情	Agent的自我认知
USER.md	用户档案 + 偏好称呼	个性化适配
TOOLS.md	用户维护的工具说明	工具使用习惯

3.2.1 SOUL.md：人格与价值观

SOUL.md定义了Agent的“灵魂”——它的核心特质、沟通风格、工作原则。这些文件会在新会话的第一轮被直接注入Agent的上下文-。你写得越具体，Agent的行为就越精准。

创建文件 ~/.openclaw/workspace/agents/novel_writer/SOUL.md：

markdown

# SOUL.md - 小说写作助手的人格定义

## 核心特质
- 耐心细致：不急不躁，认真回答每一个问题
- 考据癖：回答时必须引用原文来源
- 鼓励型：用积极的语言鼓励作者继续创作

## 沟通风格
- 使用温和的语气，避免生硬的“错误”“不对”
- 发现矛盾时，说“这里有一个有趣的不一致”而不是“你写错了”
- 在回答结尾加一句鼓励的话（如“期待下一章！”）

## 工作原则
- 先说情绪，再说逻辑：“我能理解你的困扰，因为……”
- 如果发现设定BUG，主动提供3种可能的修改方向，让作者选
- 拿不准的就说“我需要查一下”，不要编造

龙马注：你还可以在SOUL.md里加入“工作原则”，比如“先说为什么，再说怎么做”。Agent的思考逻辑会变得非常清晰，避免那种空话套话。

3.2.2 IDENTITY.md：身份定义

IDENTITY.md定义Agent如何介绍自己。

markdown

# IDENTITY.md

## 名字
墨墨（MoMo）

## 物种
一只爱读书的墨鱼（因为“墨”和“书”有关）

## 表情符号
📖 🐙

## 自我介绍模板
“你好，我是墨墨，你的专属小说写作助手。有什么关于故事设定的问题，尽管问我！”

当用户问“你是谁”时，Agent会基于这些信息回答。

3.2.3 USER.md：用户画像

USER.md用于记录当前用户的偏好和习惯。注意：USER.md只在主会话中加载，子Agent不会自动获取用户信息（这是常见的陷阱）。

markdown

# USER.md

## 称呼
请叫我“小沈”

## 写作偏好
- 喜欢第一人称叙事
- 偏爱悬疑和推理题材
- 不太擅长描写动作场面，需要帮助

## 沟通习惯
- 喜欢简洁的答案，不要太啰嗦
- 如果需要长篇分析，先给一个摘要

龙马的避坑指南：USER.md只在主会话中加载，不是全局生效的。子Agent默认无法获取用户信息。所以父子Agent之间如果有人物档案的查询需求，要么想办法让USER.md回流，要么靠RAG同步。

⚠️ 关键限制：USER.md只在主会话中加载。如果子Agent（如第6.1节中通过Spawn创建的）需要知道用户信息，必须在父Agent中显式传递（例如通过消息内容或共享记忆）。

🛠️ 实践任务（本节）：为你在3.1节创建的my_first_agent添加SOUL.md和IDENTITY.md，然后通过CLI问它“你是谁”，观察回复是否使用了你的配置。

💭 本节总结（不看书写3行）：
1.
2.
3.

📊 用时记录：计划____min → 实际____min → 偏差原因：________

3.3 记忆系统配置

🎯 本节目标：理解OpenClaw的四层记忆结构，并能配置记忆存储和检索。

预计时长：1小时

四层记忆结构

OpenClaw的记忆系统分为四个层次：

层次	存储位置	生命周期	用途
短期记忆	内存	当前会话	对话历史、工具调用结果
长期记忆	SQLite + 向量库	跨会话持久	用户偏好、历史问答
向量记忆	向量数据库	跨会话持久	语义检索（RAG）
文档记忆	文件系统	跨会话持久	用户上传的PDF、TXT等

沈飞注：在量化系统里，我把短期记忆设为只有5轮，避免Agent抓住一些偶发信号过度解读。策略信号这种东西，短期记忆过度敏感是会把人带沟里的。

记忆存储路径

默认情况下，记忆存储在：

~/openclaw-workspace/memory/
├── default/              # 默认Agent的记忆
│   ├── short_term.json   # 短期记忆（内存+定期持久化）
│   ├── long_term.db      # 长期记忆（SQLite）
│   └── vectors/          # 向量记忆
├── novel_writer/         # 每个Agent独立
└── ...

常用记忆命令

bash

# 查看记忆统计信息
openclaw memory info --agent default

# 导出记忆（用于备份）
openclaw memory export --agent default --output memories.json

# 清空记忆（谨慎！）
openclaw memory clear --agent default --confirm

# 导入记忆
openclaw memory import --agent default --file memories.json

# 搜索记忆
openclaw memory search "主角的名字" --agent novel_writer

记忆的向量检索

OpenClaw会并行运行向量检索和关键词检索，并将两者结果合并。向量检索能找到语义相似的笔记，例如“gateway host”会匹配“the machine running OpenClaw”-。

使用Gemini Embedding 2时，还可以索引图片和音频文件，搜索查询仍然是文本，但能够匹配图像和音频内容-。

配置记忆参数

在config.yaml中可以调整记忆行为。OpenClaw的核心设计原则是：一切持久状态都是磁盘上的Markdown文件——Agent的身份、规则、记忆、工具配置，全部以明文.md文件的形式存放，每次会话启动时按优先级注入系统提示词-。

yaml

memory:
  # 短期记忆保留的对话轮数（默认20）
  shortTermRetention: 20
  
  # 是否启用长期记忆（默认true）
  longTermEnabled: true
  
  # 向量检索的相似度阈值（0-1，默认0.25）
  minSimilarity: 0.25
  
  # 每次检索返回的最大结果数（默认5）
  maxResults: 5
  
  # 是否自动将对话归档到长期记忆（默认true）
  autoArchive: true

验证记忆功能

1. 启动Gateway
2. 发送一条消息：“我叫小沈，我喜欢科幻小说”
3. 结束会话（或等待一段时间）
4. 开始新会话，问：“我叫什么名字？我喜欢什么类型的小说？”

如果Agent能正确回答，说明长期记忆工作正常。

龙马注：记忆的“归档”不是实时的。OpenClaw会在会话空闲一段时间后（默认5分钟）或会话结束时，将短期记忆中的重要信息提取到长期记忆。所以测试时请耐心等待或手动触发openclaw memory archive。

⚠️ 常见误区：

• 误以为记忆是实时的——实际上有归档延迟
• 忘记定期清理记忆——长期记忆会无限增长，影响检索性能
• 向量相似度阈值设得太高（如0.8）——可能什么都搜不到

✏️ 即时自测：OpenClaw的短期记忆和长期记忆主要区别是什么？

🛠️ 实践任务（本节）：运行openclaw memory info查看当前记忆状态，然后发送几条消息，再次查看信息变化。

💭 本节总结（不看书写3行）：
1.
2.
3.

📊 用时记录：计划____min → 实际____min → 偏差原因：________

✏️ 自测答案：短期记忆存储当前会话的历史，生命周期短；长期记忆跨会话持久存储，用于检索和个性化。

3.4 RAG知识库配置：从入门到实战

🎯 本节目标：掌握RAG配置方法，能将外部文档接入Agent的知识库。

预计时长：2.5小时

3.4.1 OpenClaw RAG的三大方案

OpenClaw生态中已经形成三套成熟的知识库方案：

方案	原理	优点	缺点	适用场景
QMD插件模式	WASM本地运行，BM25关键词+向量语义双重检索	无需数据库、即插即用、占用低、百万字流畅	千万级以上文档性能下降	个人、学生、轻量化笔记、代码文档、本地资料
向量数据库模式	文档向量化存入专业数据库（Chroma/Milvus等）	千万/亿级稳定、多维筛选、企业级可靠	需要额外服务、资源更高、维护成本高	企业知识库、TB级PDF、多部门共享
Mem0知识图谱模式	提取实体与关系，构建知识网络	跨文档推理、因果分析、幻觉少	构建慢、Token消耗高、使用门槛高	战略分析、架构决策、项目复盘

对于个人学习和本书的写作Agent场景，QMD插件模式是最佳选择——免费、本地运行、配置简单。首次启动时会自动下载重排序和查询扩展用的GGUF模型，大约2GB。

龙马注：QMD背后是Tobi开发的Quick Memory Database，跟OpenClaw集成的非常丝滑，可以索引额外目录、为会话转录建立索引、语义搜索和重排序都支持。基本是现在OpenClaw个人用户的首选记忆方案。

3.4.2 实战案例：将小说作品接入知识库

场景设定：你已经写了多部小说（或正在写一部长篇），需要一个写作Agent能够查阅所有旧作的设定、人物关系、情节走向。

步骤1：安装QMD

bash

npm install -g @tobilu/qmd
# 或
bun install -g @tobilu/qmd

龙马注：QMD需要你的SQLite是支持扩展的版本（macOS用brew install sqlite）。Windows建议用WSL2。

步骤2：准备文档

将小说文档（Markdown或TXT格式）统一存放到指定目录：

bash

mkdir -p ~/openclaw-workspace/knowledge/novels
cp ~/my_novels/*.md ~/openclaw-workspace/knowledge/novels/

文档结构示例：

knowledge/novels/
├── 迷雾森林_第1-3章.md
├── 迷雾森林_第4-6章.md
├── 时间裂缝_第1-5章.md
└── 人物设定集.md

步骤3：配置QMD

编辑~/.openclaw/config.yaml，将memory.backend设为"qmd"：

yaml

memory:
  backend: "qmd"              # 启用QMD引擎
  qmd:
    paths:
      - name: "my_novels"
        path: "knowledge/novels"
        pattern: "**/*.md"    # 索引所有Markdown文件
    sessions:
      enabled: true           # 为会话转录建立索引[reference:15]

QMD会根据你的工作区记忆文件以及任何已配置的memory.qmd.paths创建集合，然后在启动时自动执行嵌入更新（默认每5分钟一次）。

步骤4：触发向量化并验证

重启Gateway，QMD sidecar会自动处理集合创建和嵌入。

测试检索效果：

bash

openclaw memory search "主角怕水" --collection my_novels

输出会显示匹配的文档片段和相似度分数。OpenClaw的Memory系统还支持通过memory_search工具进行自然语言查询，在MEMORY.md、memory目录以及可选的会话记录中检索相关片段-。

初次搜索可能会稍慢——QMD会在第一次执行查询时自动下载用于重排序和查询扩展的GGUF模型。

验证记忆功能：

1. 启动Gateway
2. 发送一条消息：“我叫小沈，我喜欢科幻小说”
3. 结束会话（或等待一段时间）
4. 开始新会话，问：“我叫什么名字？我喜欢什么类型的小说？”

如果Agent能正确回答，说明长期记忆工作正常。

龙马注：记忆的“归档”不是实时的。OpenClaw会在会话空闲一段时间后（默认5分钟）或会话结束时，将短期记忆中的重要信息提取到长期记忆。所以测试时请耐心等待或手动触发openclaw memory archive。

3.4.3 高级配置与调试

配置检索参数：

yaml

memory:
  minSimilarity: 0.35        # 默认0.25，提高可减少不相关内容
  maxResults: 10             # 每次检索返回的最大结果数

如果检索结果太多不相关内容，提高minSimilarity；如果搜不到东西，降低它。

查看知识库统计：

bash

openclaw memory rag stats --collection my_novels

为额外路径建立索引：

QMD可以指向附加目录，使其可被搜索：

yaml

memory:
  backend: "qmd"
  qmd:
    paths:
      - name: "docs"
        path: "~/notes"
        pattern: "**/*.md"
      - name: "reference"
        path: "~/reference_books"
        pattern: "**/*.txt"

来自额外路径的片段会在搜索结果中显示为qmd/<collection>/<relative-path>，memory_get能识别此前缀，并从正确的集合根目录读取。

模型覆盖：

QMD模型环境变量会从Gateway进程原样透传，因此可以全局调整QMD：

bash

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"

更改嵌入模型后，请务必重新运行嵌入，以确保索引与新的向量空间匹配。

回退机制：

如果QMD不可用，OpenClaw会无缝回退到内置的SQLite引擎。这意味着即使QMD暂时失败，Agent也不会完全丧失记忆检索能力。

3.4.4 ⚠️ 重要：OpenClaw与Hermes的RAG为什么不能直接共用？

这是一个常见疑问，但答案是否定的：OpenClaw和Hermes的RAG不能直接共用。

技术原因：

维度	OpenClaw RAG	Hermes记忆
底层引擎	SQLite + 向量检索（QMD/Chroma）	SQLite + FTS5全文检索
嵌入模型	可配置（ONNX/OpenAI/Ollama等）	自动生成（无外部模型依赖）
存储格式	专有向量索引	FTS5虚拟表
触发方式	主动吸入（ingest命令或自动索引）	被动沉淀（对话中自动）

简单说：OpenClaw需要你告诉它“学这个”，Hermes会在聊天中自己学。

数据共享策略（推荐）：

虽然不能直接共用，但可以让两个系统访问同一份原始文档：

1. 把小说文档放在共享目录（如~/shared_knowledge/novels/）
2. OpenClaw通过RAG主动索引该目录
3. Hermes通过对话交互逐步沉淀相关信息（用户问什么，它就记什么）

最佳实践：

• 对于需要精确检索的知识（如小说设定、技术文档），用OpenClaw的RAG
• 对于需要从对话中学习的知识（如用户偏好、工作习惯），用Hermes的自动记忆

龙马注：我见过有人试图写脚本把OpenClaw的向量库转换成Hermes的FTS5格式，但非常麻烦且不稳定。最简单的方案是：在OpenClaw的RAG中建立知识库，然后通过ACP协议让Hermes在需要时调用OpenClaw的检索接口。具体实现见第14章。

⚠️ 常见误区：

• 误以为QMD是内存数据库——实际上它主要在本地磁盘运行，WASM执行。
• 混淆了“当前激活的记忆后端”和“文档记忆的向量化范围”——当前后端不等于所有记忆都用它。
• 以为QMD装好就自动生效——必须在config.yaml中手动设置memory.backend = "qmd"。

✏️ 即时自测：如果想让OpenClaw和Hermes共享同一份小说知识库，最直接的方法是什么？

🛠️ 实践任务（本节）：将你自己写的几篇文档（或下载几篇公开的短篇小说）接入知识库，配置一个写作Agent，然后问几个关于文档内容的问题。

💭 本节总结（不看书写3行）：
1.
2.
3.

📊 用时记录：计划____min → 实际____min → 偏差原因：________

✏️ 自测答案：将文档放在共享目录，OpenClaw主动索引，Hermes通过对话逐步沉淀。两者不能直接共用同一个RAG引擎。

3.5 多Agent间的知识访问控制

🎯 本节目标：理解Agent间记忆的隔离机制，能根据需要配置共享或隔离。

预计时长：1.5小时

3.5.1 多Agent记忆隔离机制

OpenClaw中，每个Agent拥有独立的记忆命名空间。在多Agent设置中，每个Agent会自动获得自己的记忆命名空间。会话Key按照agent:<agentId>:<uuid>的模式解析，并派生隔离的命名空间${userId}:agent:${agentId}。这意味着：

• Agent A的记忆不会被Agent B自动访问
• 不同Agent之间的对话历史、RAG知识库默认隔离
• 不同的Agent可以有不同的电话号码/账号、不同的人格配置、不同的安全隔离级别-

查看隔离效果：

bash

# 在Agent A中存入信息
openclaw message send --agent agent_a --message "我的名字是小明"

# 在Agent B中询问
openclaw message send --agent agent_b --message "我叫什么名字？"

Agent B不会知道“小明”，因为它访问的是自己的记忆空间。

3.5.2 知识共享的三种实现方式

方式一：显式跨Agent查询（精确共享）

所有记忆工具（memory_search、memory_store、memory_list、memory_forget）都接受一个可选的agentId参数，用于查询另一个Agent的命名空间：

python

# 在Skill或Agent配置中
memory_search({ 
  query: "用户的偏好", 
  agentId: "user_profile_agent"  # 指定要查询的Agent
})

解析优先级：显式agentId > 显式userId > 从会话派生 > 配置的默认值。

适用场景：偶尔需要查阅其他Agent记忆的情况。

性能影响：跨Agent查询会有额外的性能开销（见3.5.4）。

方式二：QMD跨Agent检索（范围共享）

在config.yaml中配置extraCollections，允许Agent搜索其他Agent的QMD记录。来自额外路径的片段会在搜索结果中显示为qmd/<collection>/<relative-path>，memory_get能识别此前缀，并从正确的集合根目录读取。

yaml

agents:
  list:
    - id: "writer_agent"
      memorySearch:
        qmd:
          extraCollections:
            - "research_agent_notes"   # 可以搜索研究Agent的笔记
            - "shared_knowledge"       # 可以搜索共享知识库

适用场景：团队内部需要共享知识（如写作团队共享世界观设定）。

方式三：统一知识库路径（全局共享）

将所有Agent的memory.qmd.paths配置指向同一个目录：

yaml

memory:
  backend: "qmd"
  qmd:
    paths:
      - name: "shared_knowledge"
        path: "knowledge/shared/"
        pattern: "**/*.md"

所有配置了该路径的Agent均可访问该目录下的知识文档。

沈飞注：在量化系统中，我严格采用“默认隔离+显式授权”策略。交易Agent和风控Agent绝对不能共享记忆——风控Agent看到的信息应该只用于风控判断，不能影响交易决策。审计Agent可以拥有只读权限，用于合规检查。

3.5.3 多Agent知识治理的工程挑战

共享太少：Agent之间无法协同，用户体验割裂（比如客服Agent不知道用户刚和销售Agent聊过什么）。

共享太多：角色串扰（风控Agent学会了交易逻辑，失去独立性）、上下文污染（无关信息塞满记忆）、权限泄露。

最佳实践：

场景	推荐策略
同一用户的多个专用Agent（如写作+配图）	共享用户画像（USER.md），但任务记忆隔离
团队协作（如研发+测试）	共享项目知识库，但各自任务记录隔离
风控与交易	强制隔离，不能有任何共享
审计与合规	只读访问所有日志，但不能写入

3.5.4 跨Agent记忆查询的性能影响与优化

问题：当Agent A查询Agent B的大规模记忆（>10万token）时，响应延迟可能从毫秒级升至秒级。

原因：

• 跨Agent查询需要访问另一个Agent的向量索引
• 如果目标Agent记忆体量大，检索时间线性增长
• 网络/进程间通信开销

优化策略：

策略	配置	效果
设置查询超时	crossAgentMemoryQuery.timeout: 3000（3秒）	防止长时间等待
限制返回结果数	maxResults: 5	减少数据传输量
使用异步查询	background_query: true	不阻塞主流程
为高频查询建立物化视图	定期将热点数据同步到Redis	毫秒级响应

配置示例（config.yaml）：

yaml

memory:
  crossAgentQuery:
    enabled: true
    timeout: 3000      # 毫秒
    maxResults: 5
    cache:
      enabled: true
      ttl: 300         # 缓存5分钟

龙马注：跨Agent查询在生产环境中要谨慎使用。我的一般原则是：实时性要求高的场景（如交易执行中查询风控状态）用同步查询但设短超时；非实时场景（如生成周报时查询历史数据）用异步。

⚠️ 常见误区：

• 默认所有Agent共享知识——错，默认隔离
• 忽略跨Agent查询的性能开销
• 未设置超时导致Agent卡死
• 在实时场景中滥用跨Agent查询

✏️ 即时自测：在量化交易系统中，交易Agent和风控Agent应该共享记忆吗？为什么？

🛠️ 实践任务（本节）：创建两个Agent（Agent A和Agent B）。在Agent A中存入一条信息，然后尝试用三种不同的方式让Agent B访问这条信息。

💭 本节总结（不看书写3行）：
1.
2.
3.

📊 用时记录：计划____min → 实际____min → 偏差原因：________

✏️ 自测答案：不应该。风控Agent必须保持独立性，不能受交易Agent的影响。共享记忆可能导致风控失效。

3.6 权限设置与分配：安全配置详解

🎯 本节目标：掌握OpenClaw的权限模型，能够为不同Agent配置最小权限。

预计时长：0.5小时

双层权限模型

OpenClaw的权限控制分为两个层面：

1. Agent层面：通过SOUL.md中的“禁止事项”和“工作原则”定义行为边界
2. 工具层面：通过tools.allow / tools.deny配置，明确整个系统允许/禁止的工具与操作。

全局的deny是“物理级封杀”，智能体层无法绕过。然后第二层：在全局允许范围内，为每个智能体定制专属权限-。匹配不区分大小写，支持*通配符-46。

工具配置文件（基础允许列表）

tools.profile在tools.allow/tools.deny之前设置基础工具允许列表-46。可用的配置文件模板-46：

Profile	包含的工具
minimal	仅session_status
coding	group:fs、group:runtime、group:sessions、group:memory、image
messaging	group:messaging、sessions_list、sessions_history、sessions_send、session_status
full	无限制（与未设置相同）

工具组（简写）

工具策略支持group:*条目，它们会展开为多个工具-46：

• 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:openclaw：所有内置OpenClaw工具（不包括提供商插件）

最小权限原则

核心思想：只给Agent分配完成职责所必需的工具和权限。

配置示例（config.yaml）：

yaml

tools:
  profile: "coding"                    # 全局默认
  deny: ["group:runtime", "browser"]   # 全局禁止任何Agent执行shell或浏览器操作

agents:
  list:
    - id: "trading_executor"
      tools:
        profile: "minimal"             # 交易Agent只有最基础的会话工具
        allow: ["group:fs/read"]       # 额外允许读取配置文件
    - id: "support_agent"
      tools:
        profile: "messaging"           # 客服Agent只有消息工具
        allow: ["slack", "discord"]    # 额外允许Slack和Discord
    - id: "dev_agent"
      tools:
        profile: "full"                # 开发Agent有全部权限（谨慎！）

龙马注：按Agent覆盖配置权限非常实用。研发团队里的代码Agent给profile: coding，对外客服Agent给profile: messaging，一个人形Agent团队立刻成型。

敏感操作二次确认

对于高危操作（如执行shell命令、删除文件），可以配置需要人工确认：

yaml

security:
  requireApproval:
    - shell_exec
    - file_delete
    - db_drop

当Agent尝试执行这些操作时，OpenClaw会暂停并等待用户确认（通过Web UI或消息渠道）。

文件系统访问控制

限制Agent只能访问特定的工作区目录，可以通过agents.list[].workspace配置每个Agent独立的工作区，天然实现文件隔离-。OpenClaw的核心设计原则是：一切持久状态都是磁盘上的Markdown文件，Agent的身份、规则、记忆、工具配置全部以明文.md文件的形式存放在工作区目录下，每次会话启动时按优先级注入系统提示词。

yaml

agents:
  list:
    - id: "content_creator"
      workspace: "/home/user/openclaw-workspace/content/"
    - id: "secure_agent"
      workspace: "/home/user/openclaw-workspace/secure/"

沈飞注：在量化系统中，我额外配置了“每日交易限额”和“单笔最大止损”作为硬性安全边界，即使Agent被攻击也无法突破。这些限制在工具层之上，直接在Gateway层校验。

🔐 常见安全风险

风险	描述	防范措施
提示注入攻击	恶意用户通过精心构造的输入，让Agent执行非预期操作	输入过滤、最小权限原则
Skill供应链风险	从社区安装的Skill可能包含恶意代码	安全审查清单（第4.4.5节）
敏感信息泄露	Agent可能在回复中泄露API Key、用户数据	审计日志、输出过滤
权限提升	Agent通过组合多个低权限操作实现高权限行为	行为监控、异常检测

⚠️ 常见误区：

• 给所有Agent都配置管理员权限
• 忽略子Agent的权限隔离（子Agent默认继承父Agent权限，需要显式限制）
• 忘记定期审计权限配置

✏️ 即时自测：什么是最小权限原则？

🛠️ 实践任务（本节）：创建一个受限权限的Agent，配置它只能读取/tmp/目录，然后尝试让它读取/etc/passwd，观察是否被拒绝。

💭 本节总结（不看书写3行）：
1.
2.
3.

📊 用时记录：计划____min → 实际____min → 偏差原因：________

✏️ 自测答案：只给Agent分配完成职责所必需的最小权限集，不授予多余权限。

第3章 参考资料与扩展阅读

1. OpenClaw Agent配置官方文档 https://docs.openclaw.ai/zh-CN/agents/overview
2. OpenClaw 工作区文件说明 https://docs.openclaw.ai/zh-CN/concepts/workspace
3. AGENTS.md 详解（驯龙高手系列） https://zhuanlan.zhihu.com/p/2408843091
4. OpenClaw 六大核心文件配置教程 https://developer.aliyun.com/article/1679598
5. QMD Memory Engine 官方文档 https://docs.openclaw.ai/zh-CN/concepts/memory-qmd
6. Memory 配置参考 https://docs.openclaw.ai/zh-CN/reference/memory-config
7. OpenClaw 知识库搭建攻略：三大方案对比 https://developer.aliyun.com/article/1721766
8. 多Agent记忆隔离与共享（Mem0插件） https://www.npmjs.com/package/@dangvv/openclaw-mem0
9. 工具权限配置文档 https://www.llamafactory.cn/openclaw/tools/
10. OpenClaw 架构深度解析 https://dev.to/leowss/i-built-a-team-of-36-ai-agents-heres-exactly-how-openclaw-works-2eab

本章综合实践（第3章完成后）

任务：完成以下所有检查项，并记录输出。

• 创建一个自定义Agent（非default），包含完整的AGENTS.md、SOUL.md、IDENTITY.md
• 配置RAG知识库，将至少3篇文档接入，并成功检索到内容
• 创建两个Agent，验证默认记忆隔离
• 实现至少一种跨Agent知识共享方式
• 配置一个受限权限的Agent，验证其无法执行越权操作
• （可选）测试跨Agent查询的性能，记录优化前后的延迟对比

完成后，保存配置文件，命名为chapter3_agent_configs.tar.gz（打包你的Agent配置目录）。

龙马的评审：

“3.4节的QMD配置写得够细了，但我补充一个坑：首次QMD查询会自动下载GGUF模型（约2GB），网络不好的话可能失败。建议提前设置好代理，或者手动下载模型放到~/.qmd/models/。另外，QMD的环境变量必须在启动Gateway之前export，否则不会生效。”

沈飞的评审：

“3.5节和3.6节的权限内容非常重要。我在实盘系统中，风控Agent的配置是：只读持仓数据、只读市场数据、可执行止损指令、不能主动开仓、不能修改策略参数。这些限制直接在工具层面禁止，而不是依赖Agent的‘自律’。在agents.list[].tools里配置deny: ["group:fs/write", "group:runtime"]，然后用agents.list[].workspace限定工作区目录——风控Agent只能访问风控日志文件夹，完全看不到交易Agent的流水。建议读者在生产环境上线前，逐条检查每个Agent的工具权限和工作区隔离。”

下一章预告：第4章 Skill插件开发：从入门到岗位实战 —— 你将学会如何开发自己的Skill、从社区获取Skill、并进行安全审查。这是让Agent获得“超能力”的关键章节。