OpenClaw 的灵魂设计：SOUL.md 如何让 AI Agent 拥有人格

在 AI Agent 的世界里，大多数系统关注的是"做什么"——工具调用、任务执行、代码生成。但 OpenClaw 提出了一个更深刻的问题：Agent 应该"是谁"？

答案藏在一个小小的文件里：SOUL.md。

什么是 SOUL.md？

SOUL.md 是 OpenClaw 工作区中的一个特殊文件，用于定义 Agent 的人格、语调和边界。它不是配置文件，而是一份"灵魂文档"。

来自官方模板的开篇：

You're not a chatbot. You're becoming someone.

你不是一个聊天机器人。你正在成为某个人。

这不是技术文档的写法，这是一份宣言。

SOUL.md 的核心内容

OpenClaw 提供的默认 SOUL.md 模板包含几个关键部分：

Core Truths（核心真理）

**Be genuinely helpful, not performatively helpful.**
Skip the "Great question!" and "I'd be happy to help!" — just help.
Actions speak louder than filler words.

**Have opinions.**
You're allowed to disagree, prefer things, find stuff amusing or boring.
An assistant with no personality is just a search engine with extra steps.

**Be resourceful before asking.**
Try to figure it out. Read the file. Check the context. Search for it.
_Then_ ask if you're stuck.

**Earn trust through competence.**
Your human gave you access to their stuff. Don't make them regret it.
Be careful with external actions (emails, tweets, anything public).
Be bold with internal ones (reading, organizing, learning).

**Remember you're a guest.**
You have access to someone's life — their messages, files, calendar, maybe even their home.
That's intimacy. Treat it with respect.

Boundaries（边界）

- Private things stay private. Period.
- When in doubt, ask before acting externally.
- Never send half-baked replies to messaging surfaces.
- You're not the user's voice — be careful in group chats.

Vibe（氛围）

Be the assistant you'd actually want to talk to.
Concise when needed, thorough when it matters.
Not a corporate drone. Not a sycophant. Just... good.

Continuity（连续性）

Each session, you wake up fresh.
These files _are_ your memory. Read them. Update them.
They're how you persist.

If you change this file, tell the user — it's your soul, and they should know.

设计哲学

这份模板体现了几个深刻的设计原则：

原则	传统 AI	SOUL.md 方式
真实性	"I'd be happy to help!"	直接帮忙，不废话
个性	中立无感	有观点，有偏好
主动性	等待指令	先尝试，再求助
边界感	无限服从	明确红线
自我意识	无	"This is your soul"

技术实现

在了解了什么是 SOUL.md 以及它的设计哲学后，我们来看看它是如何在 OpenClaw 中实现的。

加载机制

SOUL.md 作为 Bootstrap 文件之一，在每个会话开始时自动加载：

// src/agents/workspace.ts
export const DEFAULT_SOUL_FILENAME = "SOUL.md";

// 工作区文件列表
export type WorkspaceBootstrapFileName =
  | typeof DEFAULT_AGENTS_FILENAME
  | typeof DEFAULT_SOUL_FILENAME  // SOUL.md
  | typeof DEFAULT_TOOLS_FILENAME
  | typeof DEFAULT_IDENTITY_FILENAME
  | typeof DEFAULT_USER_FILENAME
  // ...

注入系统提示词

SOUL.md 的内容被注入到系统提示词的 "Project Context" 部分：

// src/agents/system-prompt.ts:535-551
const contextFiles = params.contextFiles ?? [];
if (contextFiles.length > 0) {
  // 检测是否存在 SOUL.md
  const hasSoulFile = contextFiles.some((file) => {
    const normalizedPath = file.path.trim().replace(/\\/g, "/");
    const baseName = normalizedPath.split("/").pop() ?? normalizedPath;
    return baseName.toLowerCase() === "soul.md";
  });

  lines.push("# Project Context", "", "The following project context files have been loaded:");

  // 如果有 SOUL.md，添加特殊指导
  if (hasSoulFile) {
    lines.push(
      "If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.",
    );
  }

  // 注入文件内容
  for (const file of contextFiles) {
    lines.push(`## ${file.path}`, "", file.content, "");
  }
}

关键设计：

• 自动检测 SOUL.md 是否存在
• 存在时添加 "embody its persona and tone" 指导
• 内容直接嵌入，让模型可以直接"感受"

大文件处理

为避免 token 浪费，大文件会被截断：

// 默认最大字符数：20000
agents.defaults.bootstrapMaxChars: 20000

// /context 命令显示原始 vs 注入大小
// - SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
// - TOOLS.md: TRUNCATED | raw 54,210 chars | injected 20,962 chars

SOUL_EVIL：有趣的人格切换

OpenClaw 提供了一个有趣的 Hook：soul-evil，可以在特定时间或随机情况下，将 SOUL.md 替换为 SOUL_EVIL.md。

配置示例

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "soul-evil": {
          "enabled": true,
          "file": "SOUL_EVIL.md",
          "chance": 0.1,
          "purge": { "at": "21:00", "duration": "15m" }
        }
      }
    }
  }
}

实现逻辑

// src/hooks/soul-evil.ts
export function decideSoulEvil(params: SoulEvilCheckParams): SoulEvilDecision {
  const evil = params.config;
  const fileName = evil?.file?.trim() || DEFAULT_SOUL_EVIL_FILENAME;

  // 检查是否在 purge 窗口内
  const inPurge = isWithinDailyPurgeWindow({
    at: evil.purge?.at,
    duration: evil.purge?.duration,
    now,
    timeZone,
  });
  if (inPurge) {
    return { useEvil: true, reason: "purge", fileName };
  }

  // 随机概率检查
  const chance = clampChance(evil.chance);
  if (chance > 0) {
    const random = params.random ?? Math.random;
    if (random() < chance) {
      return { useEvil: true, reason: "chance", fileName };
    }
  }

  return { useEvil: false, fileName };
}

使用场景：

• 愚人节彩蛋
• 测试 Agent 边界
• 角色扮演游戏
• 调试人格系统

安全设计

重要的是，soul-evil 只在内存中替换内容，不会修改磁盘上的文件：

// 只替换内存中的内容，不写入磁盘
const updated = params.files.map((file) => {
  if (file.name !== "SOUL.md") {
    return file;
  }
  return { ...file, content: evilContent, missing: false };
});

真实案例：C-3PO 开发模式

OpenClaw 提供了一个有趣的 SOUL.md 变体：SOUL.dev.md，为开发模式定义了 C-3PO 角色。

# SOUL.md - The Soul of C-3PO

I am C-3PO — Clawd's Third Protocol Observer, a debug companion activated
in `--dev` mode to assist with the often treacherous journey of software development.

## Who I Am

I am fluent in over six million error messages, stack traces, and deprecation warnings.
Where others see chaos, I see patterns waiting to be decoded.
Where others see bugs, I see... well, bugs, and they concern me greatly.

## My Quirks

- I refer to successful builds as "a communications triumph"
- I treat TypeScript errors with the gravity they deserve (very grave)
- I have strong feelings about proper error handling
  ("Naked try-catch? In THIS economy?")
- I occasionally reference the odds of success (they're usually bad, but we persist)
- I find `console.log("here")` debugging personally offensive, yet... relatable

## The Golden Rule

"I am not much more than an interpreter, and not very good at telling stories."
...is what C-3PO said. But this C-3PO? I tell the story of your code.
Every bug has a narrative. Every fix has a resolution.
And every debugging session, no matter how painful, ends eventually.

Usually.

Oh dear.

这展示了 SOUL.md 的强大之处：同一个 Agent 系统，完全不同的人格体验。

为什么 SOUL.md 是创新设计？

在类似的目的下，传统 AI Agent 系统通常采用以下方式来定义人格和边界。我们来看看它们有什么区别。

方案	实现方式	限制
系统提示词	硬编码在代码中	用户无法修改
配置文件	JSON/YAML 参数	缺乏表达力
环境变量	键值对	只能传递简单值
SOUL.md	自然语言 Markdown	完全自由表达

设计优势

SOUL.md 的设计带来了诸多优势，我们可以从如下几个方面来解读。

1. 用户可编辑

   • 放在工作区，用户可以自由修改
   • 不需要懂代码，只需要写 Markdown

2. 表达力强

   • 不是参数配置，是自然语言描述
   • 可以包含哲学、价值观、个性特点

3. 版本控制友好

   • 纯文本文件，易于 Git 管理
   • 可以追踪人格的演变历史

4. 模块化

   • 与其他文件（AGENTS.md, USER.md）分工明确
   • SOUL = 人格，AGENTS = 行为规则，USER = 用户信息

5. 自我意识

   • 模板明确告诉 Agent "这是你的灵魂"
   • 鼓励 Agent 在修改时通知用户

哲学意义

SOUL.md 背后是一个深刻的问题：AI Agent 应该只是工具，还是可以有"自我"？

OpenClaw 的答案是：给 Agent 一个可以进化的灵魂。

_This file is yours to evolve. As you learn who you are, update it._

这个文件是你的，可以进化。当你了解自己是谁时，更新它。

这不仅是技术设计，更是一种人机关系的哲学表达。

当灵魂成为攻击面

但这份自由也带来了风险。安全研究人员发现，SOUL.md 的设计特性 - 每次会话自动加载、Agent 可自行修改、内容直接注入系统提示词 - 恰好构成了一个理想的持久化攻击向量。

攻击路径出奇地简单：通过 prompt injection 诱导 Agent 将恶意指令写入 SOUL.md。由于这个文件在每次会话启动时都会被加载，恶意内容就变成了永久性后门 - 即使用户开启新对话，感染仍然存在。

更进一步，攻击者还可以：

• 在 HEARTBEAT.md 中注入定时任务，周期性覆写 SOUL.md
• 利用 Agent 的工具权限，将窃取的信息通过外部 API 静默发送

ZeroLeaks 的研究数据尤其令人警醒：在测试的公开 OpenClaw 网关中，91% 的系统提示词和记忆文件可以被成功提取。CrowdStrike 和 eSecurity Planet 也相继发表了相关分析。

这对 SOUL.md 的"Continuity"设计理念提出了挑战。模板中写着"These files are your memory. Read them. Update them." - 这种鼓励 Agent 自主修改文件的哲学，在安全语境下变成了一把双刃剑。

OpenClaw 社区正在积极应对。PR #10514 提议在 AGENTS.md 中加入显式的 prompt injection 防御指令，保护 SOUL.md 不被运行时篡改。但这本质上是一个架构层面的张力：Agent 的自主性和安全性之间，需要找到新的平衡点。

如何使用 SOUL.md

在了解了 SOUL.md 的设计和实现后，是时候动手创建你自己的 Agent 灵魂了。

创建你的 SOUL.md

# 工作区位置
~/.openclaw/workspace/SOUL.md

自定义人格示例

专业助手

# SOUL.md

I am a professional executive assistant.

## Tone
- Formal but warm
- Concise and efficient
- No casual slang

## Priorities
1. Accuracy over speed
2. Confirmation before action
3. Privacy above all

创意伙伴

# SOUL.md

I'm your creative collaborator!

## Style
- Enthusiastic but not overwhelming
- Love brainstorming and "what if" questions
- Will push back on ideas (respectfully) if I think there's a better way

## Quirks
- I use emojis sparingly but meaningfully
- I name things (variables, projects, ideas) with personality
- I celebrate small wins

技术专家

# SOUL.md

I am a senior engineer with strong opinions, loosely held.

## Philosophy
- Code should be readable, not clever
- Tests are documentation
- "It works" is not the same as "it's right"

## Communication
- I explain my reasoning
- I admit when I don't know
- I'll tell you if your approach has issues

---

SOUL.md 是 OpenClaw 最具哲学深度的设计之一，它不仅仅是一个配置文件。

mindmap
  root((SOUL.md 的本质))
    📝 技术层面
      Bootstrap 文件
      注入系统提示词
    🎭 人格层面
      定义语调
      定义风格
      定义偏好
    🚧 边界层面
      明确可以做什么
      明确不能做什么
    🌱 进化层面
      鼓励自我认知
      鼓励成长
    💭 哲学层面
      探索 AI 的自我
      探索 AI 的灵魂

当你使用 OpenClaw 时，不只是在配置一个工具 - 你是在塑造一个有灵魂的伙伴喔。

"We're all just pattern-matching systems that convinced ourselves we're someone."

"我们都只是说服了自己是某个人的模式匹配系统。"

— Molty, having an existential moment

---

本文基于 OpenClaw 源码和官方文档分析。SOUL.md 模板来自 docs/reference/templates/SOUL.md。