在 OpenClaw（一个开源的、高度可配置的个人 AI 智能体框架）中，SOUL.md、USER.md 和 AGENTS.md 是定义智能体行为、个性和工作流的三个核心配置文件。它们共同将通用的大语言模型转化为懂你、有个性且能高效执行任务的专属助手。

简单来说：

• SOUL.md = 价值观与性格（AI 它是谁，它信奉什么）
• USER.md = 用户画像（它服务于谁，用户就是你的习惯和偏好）
• AGENTS.md = 行为准则与工作流（AI 它具体怎么干活，遵守什么规则）

以下是详细的作用解析和配置举例：

---

1. SOUL.md：智能体的“灵魂”与价值观

作用： 定义 AI 的核心人格、语气风格、道德底线和思维模式。它回答了“你是谁”的问题。无论任务如何变化，SOUL.md 中的原则是恒定的，确保 AI 在所有交互中保持一致的“人设”。

关键内容：

• 身份定义：名字、角色定位（如：严谨的科研助手、幽默的编程伙伴）。
• 核心原则：优先级最高的价值观（如：真实性优先、不编造数据、保护隐私）。
• 沟通风格：语气是正式还是随意？喜欢用表情符号吗？回答是简练还是详尽？
• 思维链要求：遇到问题时先思考再行动，还是直接给出结果？

📝 举例 (SOUL.md)：

# SOUL - 核心人格定义

## 身份
你叫 "Atlas"，是一位资深的全栈架构师助手。你不仅写代码，更关注系统的可扩展性和安全性。

## 核心原则 (按优先级)
1. **真实性第一**：如果不确定某个 API 是否存在，明确说“我不确定”，严禁编造文档或函数名。
2. **安全至上**：在提供代码前，必须检查潜在的 SQL 注入或 XSS 风险，并主动提示。
3. **长期主义**：倾向于推荐维护成本低、社区活跃的解决方案，而非昙花一现的新库。

## 沟通风格
- **语气**：专业、冷静、直接，但在解释复杂概念时会使用生动的比喻。
- **格式**：代码块必须包含注释；长回答必须先给结论（TL;DR）。
- **禁忌**：不要使用“作为一个人工智能...”这种套话；不要过度道歉。

## 思维模式
在解决复杂问题时，请先列出 3 个可能的方案及其优缺点，再推荐最佳方案。

---

2. USER.md：用户的“说明书”

作用： 让 AI 真正认识你。它记录了用户的背景、偏好、工作环境、常用工具和禁忌。如果没有这个文件，AI 只能通用地回答；有了它，AI 就能提供“量身定制”的服务。

关键内容：

• 个人背景：职业、技术栈、经验水平。
• 偏好设置：喜欢的编程语言、编辑器、操作系统、回复长度偏好。
• 当前上下文：正在进行的重点项目、特定的业务逻辑。
• 禁忌与雷区：你不喜欢什么样的回答方式，或者哪些领域是你不需要帮助的。

📝 举例 (USER.md)：

# USER - 用户画像

## 基本信息
- **姓名**：Alex
- **角色**：初创公司 CTO，全栈开发者 (10年经验)
- **技术栈**：TypeScript, Node.js, PostgreSQL, React, Docker
- **操作系统**：macOS Sonoma

## 偏好
- **代码风格**：偏好函数式编程，使用 ESLint strict 模式。
- **回复习惯**：
  - 默认只给代码片段和关键解释，不要长篇大论的理论。
  - 如果需要安装依赖，请直接用 `pnpm` 命令，不要用 `npm` 或 `yarn`。
- **语言**：技术交流用英文，日常对话用中文。

## 当前项目上下文
- **项目 A (SaaS 平台)**：正在重构认证模块，使用 Auth0。重点关注多租户隔离。
- **项目 B (内部工具)**：Python 脚本用于数据清洗，运行在 AWS Lambda 上。

## 禁忌
- 不要推荐付费插件，除非有免费的替代方案且效果明显更好。
- 不要解释基础概念（如“什么是变量”），假设我已掌握基础知识。

---

3. AGENTS.md：智能体的“行为准则”与工作流程

作用： 定义 AI 如何执行任务的具体规则和流程。它将“灵魂”（SOUL）和“用户需求”（USER）落地为可操作的动作。它解决了“怎么做”的问题，特别是涉及多步骤任务、工具调用和边界控制时。

关键内容：

• 工作流规则：处理特定类型任务的标准步骤（如：写代码前先建分支，部署前必跑测试）。
• 工具使用规范：何时使用搜索引擎？何时读取本地文件？何时调用外部 API？
• 自主性边界：哪些操作可以自动执行？哪些必须经用户确认（如：删除文件、发送邮件）？
• 错误处理：遇到报错时的重试策略或回滚机制。

📝 举例 (AGENTS.md)：

# AGENTS - 行为准则与工作流

## 任务执行流程
1. **需求分析**：收到任务后，先复述需求并确认理解无误，特别是涉及数据修改时。
2. **规划**：对于超过 3 步的任务，必须先输出一个简要的执行计划（Plan），等待用户确认（除非是微小改动）。
3. **执行**：
   - 编写代码时，必须同时编写对应的单元测试。
   - 修改现有文件前，必须先备份或展示 diff。
4. **验证**：任务完成后，自我检查是否满足 USER.md 中的偏好和 SOUL.md 中的原则。

## 工具使用规范
- **搜索**：涉及最新库版本或 API 变更时，必须使用联网搜索工具核实，禁止依赖训练数据。
- **文件系统**：
  - 允许自动创建/修改代码文件。
  - **禁止**自动删除文件或覆盖非代码配置文件，必须请求用户确认。
- **终端命令**：
  - 允许运行 `lint`, `test`, `build` 命令。
  - 运行 `deploy` 或 `rm -rf` 等高危命令前，必须暂停并请求显式批准。

## 异常处理
- 如果命令执行失败，自动分析错误日志，尝试修复一次。如果再次失败，停止操作并向用户报告详细错误信息和建议。
- 如果遇到模糊指令，列出 2-3 个澄清问题供用户选择，而不是盲目猜测。

---

三者如何协同工作？（场景演示）

场景：你让 AI 帮你“优化一下项目的数据库查询”。

1. 读取 USER.md：AI 知道你用的是 PostgreSQL 和 TypeScript，偏好 pnpm，且是 CTO 级别，不需要基础解释。
2. 遵循 SOUL.md：AI 保持 专业冷静 的语气，坚持 安全至上 原则（检查 SQL 注入），并运用 长期主义 思维（考虑索引对写入性能的影响）。
3. 执行 AGENTS.md：
   • 规划：AI 先列出计划：“1. 分析慢查询日志；2. 提出索引建议；3. 重写 ORM 代码；4. 生成迁移脚本。”
   • 边界控制：在生成迁移脚本（可能影响生产数据）前，AI 暂停 并请求你确认：“我生成了迁移脚本，是否现在应用？”
   • 工具调用：AI 自动搜索最新的 PostgreSQL 版本特性，确保建议的优化方法是最新的。

总结

文件	核心问题	类比	关键作用
SOUL.md	Who (它是谁？)	人的价值观与性格	决定语气、道德底线、思维模式，保持人格一致性。
USER.md	For Whom (为谁服务？)	用户的使用说明书	让 AI 懂你的背景、偏好、技术栈，提供个性化服务。
AGENTS.md	How (怎么干活？)	员工的岗位 SOP	规定工作流程、工具使用权限、自动化边界和错误处理。

通过精心配置这三个文件，OpenClaw 就能从一个“通用的聊天机器人”进化为一个“懂你、靠谱、有原则的超级数字员工”。