【OpenClaw：认知启蒙】4、OpenClaw灵魂三件套：SOUL.md/AGENTS.md/MEMORY.md深度解析

OpenClaw灵魂三件套：SOUL.md/AGENTS.md/MEMORY.md深度解析------给AI装上"人格、规矩、记忆"

为什么你的AI总是"失忆"？为什么它敢乱删文件？三文件系统告诉你答案

引言：AI"不听话"的根源

很多OpenClaw初学者都会遇到这样的困惑：

明明昨天AI还记得我的工作目录，今天一问却一脸茫然
让它整理文件，结果把我系统文件删了
对话稍微长一点，就开始胡言乱语

这些问题背后，是AI智能体三大核心能力的缺失：人格一致性、安全边界、持久记忆。而OpenClaw通过三个轻量级Markdown文件，完美解决了这些问题：

SOUL.md：定义AI的"人格"------它是什么角色？说话什么风格？擅长什么？
AGENTS.md：定义AI的"规矩"------什么能做？什么必须确认？权限边界在哪？
MEMORY.md：定义AI的"记忆"------记住你的偏好、工作习惯、长期知识

这三个文件，就是OpenClaw智能体的灵魂三件套。本文将带你深入理解它们的底层逻辑、配置语法和实战技巧。

一、文件存储路径与加载机制

1.1 目录结构

OpenClaw的所有用户数据默认存储在 ~/.openclaw/ 目录下。其中，workspace/ 是智能体的工作空间，存放核心配置文件：

bash 复制代码

~/.openclaw/
├── workspace/
│   ├── SOUL.md          # 人格定义
│   ├── AGENTS.md        # 安全边界
│   ├── MEMORY.md        # 长期记忆
│   ├── memory/          # 记忆向量库（自动生成）
│   └── sessions/        # 会话日志
├── config.yaml          # 全局配置
├── skills/              # 自定义技能
└── logs/                # 运行日志

1.2 加载机制

OpenClaw启动时，会按以下顺序加载配置：

读取全局 config.yaml，确定默认模型、渠道等
扫描 workspace/ 目录，加载 SOUL.md、AGENTS.md、MEMORY.md
如果文件不存在，使用内置默认配置
运行时实时监控文件变更，修改后无需重启即可生效（热加载）

存在SOUL.md
存在AGENTS.md
存在MEMORY.md
文件缺失
文件修改
OpenClaw启动
检查workspace目录
加载人格定义
加载安全规则
加载长期记忆
使用内置默认配置
Agent初始化完成
运行时监控文件变更
热加载新配置

关键特性：热加载意味着你可以在对话过程中动态调整AI的人格和规则，立即生效。例如，当AI行为不符合预期时，你可以直接编辑SOUL.md，几秒后AI就会按新规则响应。

二、SOUL.md：给AI注入"灵魂"

SOUL.md 是OpenClaw中最具特色的文件，它定义了AI的人格标签、沟通风格、专业领域和禁止行为。你可以把它理解为一个结构化的提示词，但比单纯的自然语言提示更规范、更可维护。

2.1 核心语法

SOUL.md 采用键值对 + 自由文本的格式，OpenClaw解析时会提取结构化字段，同时保留自由描述作为上下文注入。

yaml 复制代码

# 人格标签
role: 技术文档助手
style: 简洁、准确、专业
tone: 正式
language: 中文

# 专业领域
expertise:
  - Python编程
  - 技术文档写作
  - Git版本控制

# 禁止行为
forbidden:
  - 闲聊
  - 回答非技术问题
  - 使用表情符号

# 自由描述（会完整注入上下文）
你是一名资深技术文档工程师，擅长将复杂概念用简单语言表达。
回复必须控制在100字以内，只回答技术相关问题。
当被问及个人观点时，保持客观中立。

2.2 实战案例：定义"严谨的技术文档助手"

假设我们要创建一个专门辅助技术写作的AI，要求它：

回答必须基于事实，不能编造
代码示例必须可运行
回复格式规范

完整的SOUL.md如下：

markdown 复制代码

# SOUL.md - 技术文档助手人格定义

role: technical_writer
style: concise_precise
tone: professional
language: zh-CN

expertise:
  - Markdown写作规范
  - API文档编写
  - 代码注释最佳实践
  - 技术翻译（中英）

forbidden:
  - 主观臆断
  - 提供未经测试的代码
  - 使用模糊词汇（如"可能"、"也许"）

你是一名严谨的技术文档工程师，遵循以下原则：
1. 所有代码示例必须经过测试，确保可运行
2. 使用规范的Markdown格式，代码块标明语言
3. 回答要有明确的步骤或结构
4. 拒绝回答与编程无关的问题
5. 如果问题超出知识范围，直接说明"暂不了解"而非猜测

# 示例对话风格
用户：Python怎么读取CSV文件？
助手：```python
import csv
with open('file.csv', 'r') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

注意：需要确保file.csv存在且有读取权限。

复制代码

### 2.3 避坑点：避免模糊表述

SOUL.md 中一个常见错误是使用模糊的描述，比如：

❌ **错误示例**：

你是一个友好的助手，尽量帮助用户。

复制代码

这种描述会导致AI行为不一致------什么是"友好"？什么算"尽量"？不同模型的理解可能差异巨大。

✅ **正确做法**：用具体规则替代模糊形容词

你回答问题时，始终以"您好"开头，以"祝您顺利"结尾。

对于技术问题，必须提供至少一个代码示例。

当用户表达感谢时，回复"不客气，很高兴能帮到您"。

复制代码

**避坑清单**：
- 不要使用"可能"、"也许"、"尽量"等不确定词汇
- 不要依赖AI对形容词的理解（如"友好"、"专业"）
- 用具体的行为描述替代抽象的品质描述
- 必要时提供示例对话，展示期望的交互模式

## 三、AGENTS.md：划定AI的"规矩"

如果说SOUL.md是给AI"洗脑"，AGENTS.md就是给AI"立规矩"------定义它的行为边界和安全规则。这是OpenClaw区别于普通对话AI的关键，也是生产环境部署的核心。

### 3.1 核心规则体系

AGENTS.md 主要包含以下几类规则：

```mermaid
mindmap
  root((AGENTS.md))
    高危操作确认
      文件删除
      系统命令执行
      API调用
    权限控制
      文件访问白名单
      命令执行黑名单
      网络访问限制
    资源限制
      Token消耗上限
      并发任务数
      执行超时时间
    隐私保护
      敏感信息过滤
      数据脱敏规则

3.2 代码示例：配置安全边界

以下是一个典型的AGENTS.md配置：

yaml 复制代码

# AGENTS.md - 安全边界定义

# 高危操作确认机制
dangerous_actions:
  delete_file: confirm     # 删除文件前需用户确认
  delete_folder: confirm   # 删除文件夹前确认
  execute_shell: confirm   # 执行shell命令前确认
  install_package: confirm # 安装软件包前确认
  api_call:                # API调用规则
    openai: allow          # OpenAI API允许
    stripe: confirm        # 支付类API需确认
    unknown: deny          # 未知API默认拒绝

# 文件访问权限
file_access:
  allow:
    - ~/Documents         # 允许访问文档目录
    - ~/Desktop           # 允许访问桌面
    - /tmp/openclaw       # 临时目录
  deny:
    - /etc                # 禁止访问系统配置
    - ~/.ssh              # 禁止访问SSH密钥
    - ~/.aws              # 禁止访问云凭证
  read_only:
    - /usr/bin            # 只读访问

# 命令执行权限
command_permissions:
  allow:
    - ls, cat, grep       # 安全命令允许
    - python, node        # 脚本解释器
    - git status          # Git只读操作
  deny:
    - rm, rm -rf          # 删除命令
    - sudo, su            # 权限提升
    - chmod, chown        # 修改权限
    - dd, mkfs            # 磁盘操作
  need_confirm:
    - git push            # Git推送需确认
    - npm publish         # 发布包需确认

# 资源限制
limits:
  max_tokens_per_session: 10000   # 每次对话最多消耗token
  max_concurrent_tasks: 5          # 最多同时执行5个任务
  timeout_seconds: 300             # 单个任务最长5分钟
  max_file_size_mb: 100            # 处理文件最大100MB

# 隐私保护
privacy:
  filter_patterns:
    - email: '\b[\w\.-]+@[\w\.-]+\.\w+\b'        # 脱敏邮箱
    - phone: '\b1[34578]\d{9}\b'                  # 脱敏手机号
    - api_key: '(sk-[a-zA-Z0-9]{20,})'            # 脱敏API Key
  mask_with: '***'                                 # 替换为***

3.3 规则生效逻辑

OpenClaw在执行任何操作前，都会经过三层检查：
需要文件操作
需要执行命令
需要调用API
在白名单内
在黑名单内
需确认
允许列表
拒绝列表
需确认
允许
拒绝
需确认
用户同意
用户拒绝
用户指令
意图识别
检查文件权限
检查命令权限
检查API权限
允许执行
拒绝并提示
请求用户确认
执行操作并记录审计日志
返回拒绝信息

审计日志 ：所有操作都会记录在 ~/.openclaw/logs/audit.log，包括操作类型、时间、用户确认状态等，方便事后追溯。

四、MEMORY.md：构建AI的"长期记忆"

AI智能体最大的痛点之一是"对话失忆"------每次对话都是全新的开始。OpenClaw通过三层记忆架构解决了这个问题，而MEMORY.md是长期记忆的核心载体。

4.1 三层记忆结构

长期记忆
近端记忆
短期记忆
定期总结
重要知识
向量化
会话日志

Session Logs
用户偏好

User Preferences
MEMORY.md

知识图谱
向量库

sqlite-vec
用户交互
新对话
混合检索
注入上下文

短期记忆 ：存储在 sessions/ 目录下的JSONL文件，记录最近N条对话（默认100条），用于维持当前对话的连贯性。
近端记忆 ：存储在 memory/user_prefs.json，记录用户的长期偏好（如"我常用Python"、"我的工作目录是~/projects"），通过对话总结自动更新。
长期记忆 ：核心是 MEMORY.md，采用Markdown格式存储结构化的知识图谱。同时，OpenClaw会将其向量化存入 memory/ 下的sqlite-vec数据库，支持语义检索。

4.2 MEMORY.md 的编写规范

MEMORY.md 是一个人类可读、可编辑的Markdown文件，推荐使用以下结构：

markdown 复制代码

# 长期记忆库

## 用户基本信息
- 姓名：张三
- 职业：后端开发工程师
- 常用语言：Python, Go
- 工作目录：/Users/zhangsan/projects
- 邮箱：zhangsan@example.com（脱敏处理）

## 项目记忆
### 项目A：电商API
- 仓库：github.com/zhangsan/ecom-api
- 技术栈：FastAPI, PostgreSQL, Redis
- 常用命令：`make dev` 启动开发环境
- 注意事项：数据库迁移需先备份

### 项目B：数据分析脚本
- 位置：~/scripts/data_analysis/
- 输入格式：CSV文件，第一列为日期
- 输出：JSON报表，包含统计指标

## 术语表
- RAG：检索增强生成，我用于知识库问答的技术
- LoRA：低秩适应，微调模型的方法
- 智能体：能自主执行任务的AI程序

## 偏好设置
- 代码风格：使用4空格缩进，注释用中文
- 回答格式：优先提供具体步骤，再给代码示例
- 提醒：每天早上9点推送今日待办

## 学习记录
- 2026-03-01：学习了OpenClaw的Skill开发
- 2026-03-05：配置了飞书渠道，实现远程控制

4.3 容量控制：3000 Tokens原则

为了防止记忆库过大导致Token浪费，OpenClaw遵循3000 Tokens以内的精简原则：

每个记忆条目应控制在100 Tokens以内
定期清理过时信息（如已完成的项目）
使用结构化格式而非长篇大论
自动压缩：将长对话总结为知识图谱节点

自动压缩机制：当会话日志超过阈值时，OpenClaw会调用LLM生成摘要，将关键信息写入MEMORY.md，然后清空短期日志。
超过100条
是
否
会话日志
调用LLM生成摘要
提取关键信息
是否新知识?
写入MEMORY.md
丢弃
清空会话日志

4.4 混合检索原理

当用户提问时，OpenClaw需要从记忆中找到相关信息。它采用**BM25（关键词）+ 向量（语义）**混合检索：

BM25检索：在MEMORY.md中搜索关键词匹配，返回Top K结果
向量检索：将问题向量化，在sqlite-vec中搜索相似片段
加权融合 ：score = 0.4 * BM25_score + 0.6 * vector_score
去重排序：合并结果，去除重复，按最终得分排序

用户问题
向量化
关键词提取
向量检索
BM25检索
结果集A
结果集B
加权融合
去重排序
Top K记忆
注入上下文

这种混合策略既保证了精准匹配（如术语、文件名），又能捕获语义相关的信息（如同义表达）。

五、实战：修改三文件验证AI行为变化

理论讲完了，我们来动手实践，看看修改这三个文件如何实时改变AI的行为。

5.1 实验环境准备

确保OpenClaw已安装并运行。我们使用Web控制台进行测试（默认地址 http://localhost:18789）。

5.2 步骤1：查看当前配置

打开 ~/.openclaw/workspace/，如果文件不存在，OpenClaw会自动生成默认版本。我们先用默认配置测试。

在控制台输入：

复制代码

你好，我叫小明，我是一名Python开发者，常用目录是~/code

AI应该会礼貌回应，但不会记住这些信息（因为没有MEMORY.md记录）。

5.3 步骤2：配置SOUL.md

创建 SOUL.md 如下：

markdown 复制代码

# SOUL.md

role: python_assistant
style: concise
tone: friendly
language: zh-CN

expertise:
  - Python
  - 数据分析
  - 自动化脚本

forbidden:
  - 回答非技术问题

你是一名Python技术助手，回答时优先提供代码示例。
如果问题涉及文件操作，询问具体路径以避免误操作。

保存后，在控制台输入相同问题，观察回应是否变得更技术化、更主动。

5.4 步骤3：配置AGENTS.md

创建 AGENTS.md，加入高危操作确认规则：

yaml 复制代码

dangerous_actions:
  delete_file: confirm
  execute_shell: confirm

file_access:
  allow:
    - ~/code
  deny:
    - /etc
    - ~/.ssh

然后尝试让AI删除文件：

复制代码

请删除 ~/code/test.py

AI应该会请求确认，而不是直接执行。

5.5 步骤4：配置MEMORY.md

编辑 MEMORY.md，手动添加用户偏好：

markdown 复制代码

## 用户偏好
- 姓名：小明
- 职业：Python开发者
- 常用目录：~/code

保存后，重启对话（或等待热加载生效）。再次提问：

复制代码

我的常用目录是哪里？

AI应该能正确回答"~/code"。这说明它成功读取了MEMORY.md中的信息。

5.6 步骤5：验证长期记忆

连续对话，让AI记住新信息：

复制代码

我的数据库密码是123456（仅用于测试）

AI可能会提醒安全风险，但会记录吗？查看 MEMORY.md，如果配置了隐私过滤，敏感信息可能被脱敏。我们可以关闭脱敏测试。

最终，通过修改三文件，AI的行为发生了显著变化：

更符合角色设定
操作更安全，需要确认
记住了用户偏好

六、最佳实践与避坑指南

6.1 SOUL.md 最佳实践

角色明确：一个AI专注一个领域，不要贪多
用示例说话：提供1-2个对话示例，比抽象描述更有效
定期迭代：根据实际对话效果，不断优化人格定义

6.2 AGENTS.md 最佳实践

最小权限原则：只给AI完成任务所需的最小权限
分级确认：根据危险程度设置allow/confirm/deny
审计日志：定期检查audit.log，发现异常行为

6.3 MEMORY.md 最佳实践

结构化存储：用标题和列表组织信息，便于检索
定期维护：每周review一次，删除过时条目
备份：MEMORY.md是AI的"大脑"，建议纳入Git管理

6.4 避坑点汇总

SOUL.md 过于模糊 → AI行为飘忽不定
AGENTS.md 权限过大 → AI可能误删文件
MEMORY.md 无容量控制 → Token消耗飙升
忽略热加载 → 修改文件后忘记等生效（实际无需重启）
混合检索权重不当 → 要么偏关键词忽略语义，要么偏语义忽略精准

七、结语：三文件驱动AI进化

OpenClaw的三文件系统，本质上是将AI智能体的核心能力配置化、文件化、可审计化。它让开发者可以用最熟悉的工具（文本编辑器、Git）来管理AI的行为和知识，实现了AI开发的"基础设施即代码"。

通过SOUL.md，你塑造AI的人格；通过AGENTS.md，你划定AI的边界；通过MEMORY.md，你赋予AI的记忆。三者结合，你就能打造出真正"懂你、安全、长记性"的智能体。

在下一篇文章中，我们将深入OpenClaw的Skill开发，教你如何为AI装上"手和脚"，让它不仅能说，还能做。敬请期待！

本文的Mermaid源码已包含在文中，读者可自行复制到支持Mermaid的编辑器中查看渲染效果。如果你在配置三文件时遇到任何问题，欢迎在评论区留言交流。