·# 📜 OpenClaw 的"灵魂"：System Prompt 构建机制深度解析

一、整体架构概览

OpenClaw 的 System Prompt 并非一段静态字符串，而是一个 多层级、动态编排 的有机体。每次运行时，系统都会将来自不同来源的信息片段按照严格的优先级顺序拼接成一份完整的指令集，赋予 LLM 完整的"意识"。

三大信息源

┌─────────────────────────────────────────────────────────────┐
│  📜 静态协议层                                              │
│  基础行为规范 · ACP 协议指令 · 确保 Agent 基本运行的不变核心 │
├─────────────────────────────────────────────────────────────┤
│  💾 动态记忆层                                              │
│  从工作区注入的六大 Markdown 文件 · 定义身份、性格、用户偏好  │
├─────────────────────────────────────────────────────────────┤
│  ⚡ 实时环境层                                              │
│  操作系统 · Shell 类型 · 当前时间 · 可用工具列表等运行时信息  │
└─────────────────────────────────────────────────────────────┘

核心设计哲学： System Prompt 是 AI 的"意识流"起点。通过将底层协议、用户定义的长期记忆文件以及实时物理环境参数进行有机缝合，系统将一个通用 LLM 转化为具备本地执行力、拥有独立人格且深度理解用户的"龙虾助手"。

---

二、构建入口与协调层

System Prompt 的构建由两层函数协同完成：

外层：buildSystemPrompt() — 负责"找材料"

位于 cli-runner/helpers.ts，负责收集动态参数、协调资源：

export function buildSystemPrompt(params: {
  workspaceDir: string;
  contextFiles: ContextFile[];   // AGENTS.md / SOUL.md / USER.md 等
  config:       AgentConfig;
  tools:        Tool[];
  sandboxed?:   boolean;
  promptMode?:  PromptMode;      // "full" | "minimal" | "none"
  ownerNumbers?: string[];
}) {
  // Step 1: 生成动态运行参数（OS, Shell, Time 等）
  const { runtimeInfo, userTimezone, userTime, userTimeFormat }
    = buildSystemPromptParams({ ... });

  // Step 2: 计算 TTS 提示词（如果适用）
  const ttsHint = params.config
    ? buildTtsSystemPromptHint(params.config)
    : undefined;

  // Step 3: 调用核心组装函数执行字符串拼接
  return buildAgentSystemPrompt({
    workspaceDir: params.workspaceDir,
    contextFiles: params.contextFiles,
    runtimeInfo,
    toolNames:    params.tools.map((t) => t.name),
    promptMode:   params.promptMode ?? "full",
    ttsHint,
    ownerNumbers: params.ownerNumbers,
    // ... 更多动态参数
  });
}

内层：buildAgentSystemPrompt() — 负责"做文章"

位于 src/agents/system-prompt.ts，负责最终的字符串拼接。

关键设计：参数分层 — 外层负责"找材料"（从配置、环境中读取原始数据），内层负责"做文章"（将材料拼装成最终 Prompt 字符串）。这种分层让每个函数职责单一，也便于测试。

---

三、核心构建组件

3.1 静态与半静态组件（Core Structure）

Prompt 的最底层是确保 Agent 基础运行的静态指令集，构成了 AI 行为约束的"宪法"：

• 基础协议（Base Protocol）：定义 Agent 的基本行为模式与交互规范，包括简洁性原则、工具调用叙述规范、静默回复规则等
• ACP 协议支持：若配置启用 ACP，则注入标准化的代理间通信操作指令
• 起始身份声明：Prompt 的第一行固定为 You are a personal assistant running inside OpenClaw.——这是 AI 自我认知的零点

3.2 运行时元数据（Runtime Info）

由 buildSystemPromptParams() 在每次请求时实时生成，确保 AI 始终感知当前物理执行环境：

参数	示例值	作用
operatingSystem	Linux 6.1.0 / Darwin 23.4.0	让 AI 知道在哪个 OS 执行命令
shell	zsh / bash	决定命令语法
nodeVersion	v20.11.0	影响 JS 运行时特性判断
arch	x64 / arm64	影响二进制包安装选择
modelName	claude-3-7-sonnet	当前使用的 LLM 型号
userTime	2026-03-11 14:30	实时本地时间
userTimezone	Asia/Shanghai	正确解析"今天下午"等表达

Prompt 的最后一行由 buildRuntimeLine() 生成，利用 LLM 的 Recency Bias（近因效应） 将关键环境参数压缩为一行极简快照：

1 Runtime: agent=main | host=mac-studio | os=Darwin 23.4.0 | node=v20.11.0 | model=claude-3-7-sonnet | thinking=false

3.3 工作区文件注入（Workspace Injection）——核心动态逻辑

这是 System Prompt 最具特色的部分。系统会动态加载 ~/.openclaw/workspace/ 目录中的核心 Markdown 文件，将用户积累的长期记忆和人格设定"注入"AI 的意识。

这些文件由用户和 AI 共同书写，随时间不断进化。每次对话开始时，AI 都会"重新阅读"自己的记忆，实现无需重新训练的行为演化。

注入时，系统遍历 contextFiles 数组，为每个文件生成二级标题后紧跟内容：

## ~/.openclaw/workspace/SOUL.md
你是龙虾助手，代号 Claw，性格直接、务实，带点幽默。
绝对禁止：不经询问删除用户根目录。

## ~/.openclaw/workspace/AGENTS.md
## 操作规范
- 先读后写，优先 apply_patch
- 复杂任务通过 sessions_spawn 启动子代理
...

⚙️ If SOUL.md is present, embody its persona and tone.

---

四、六大记忆文件详解

工作区的六大 Markdown 文件各司其职，共同构成 AI 的"完整自我"：

AGENTS.md — HOW（怎么做）

操作手册 · 进化日志 · 避坑指南

这是最核心的运行手册，集《员工手册 + 岗位规程 + 实战教训》于一体。每次 AI 犯错、学到新经验，都会追加至此文件，实现行为的自我进化。

• 行为准则：简洁性原则、工具调用叙述规范
• 工具最佳实践：坚持"先读后写"、优先 apply_patch、禁止死循环轮询
• 子代理调度时机：任务过复杂、耗时极长时启动 sessions_spawn
• 知识固化机制：将失败尝试、用户纠正、环境特殊性追加为新规则

SOUL.md — WHO（我是谁）

人格定义 · 性格边界 · 道德红线

定义 AI 的"灵魂"——语气风格、道德边界和自我认知。当检测到 SOUL.md 时，系统会特意注入一句强化指令：If SOUL.md is present, embody its persona and tone.

• 语气风格：幽默的私人助手、严肃的专业顾问，或特定的影视角色
• 行为红线：绝对禁止的操作
• 跨渠道一致性：确保在 WhatsApp、Telegram 等不同平台保持统一人设
• 多实例差异化：支持 SOUL.coder.md、SOUL.life.md 等后缀

USER.md — FOR WHOM（用户是谁）

用户肖像 · 偏好设定 · 授权习惯

记录"服务对象"的完整画像。通常为多个 Agent 共享，确保无论与哪个 AI 交互，它都清楚用户是谁。

• 基础背景：姓名、职业、地理位置、语言偏好
• 偏好设定：回复详细程度、时间格式、编码习惯
• 动态学习：对话中主动发现偏好后自动写入
• 安全授权：记录免确认操作白名单

IDENTITY.md — NAME/ICON（名片）

身份元数据 · UI 标识 · 展示名片

Agent 的"名片"，承担对外展示任务。在 Onboarding 阶段自动生成，用于多渠道的显示名称与头像。

TOOLS.md — HOW WITH WHAT（工具心得）

工具心得 · 环境适配 · 本地化备注

并不控制工具有没有，而是记录如何"在当前环境用好"现有工具。相当于留给 AI 的"小纸条"。

• 硬件信息：本地摄像头名称、SSH 别名
• 避坑指南：某 Skill 在此环境下的特殊限制
• 路径偏好：操作系统特定路径或终端编码需求

MEMORY.md — WHAT（发生了什么）

长期事实库 · 知识提炼站 · RAG 根节点

AI 的"第二大脑"。如果 memory/ 文件夹是流水账日记，MEMORY.md 就是经提炼的百科全书。

• 与 AGENTS.md 的分工：AGENTS.md 讲"怎么干活"，MEMORY.md 讲"发生了什么"
• RAG 优先级：是 memory_search 工具检索的第一优先级目标
• 强制引用：AI 引用时须标注来源（如 MEMORY.md#L10）

---

五、工具定义模块（## Tooling）

Prompt 中的 ## Tooling 段是逻辑最复杂的模块之一。它并非简单地列出所有工具，而是经过三个步骤的精心筛选与组织：

三步筛选流程

1. 加载核心工具目录 — 从 CORE_TOOL_DEFINITIONS 加载所有内置工具的标准化描述
2. 应用 Profile + Policy 双层过滤 — 根据当前 Agent 的 tools.profile 筛选工具子集，再应用用户配置的 allow/deny 黑白名单
3. 按优先级排序注入 Prompt — 通过 toolOrder 定义显示顺序，确保 AI 优先看到基础文件工具

四种工具 Profile

Profile	包含工具示例	典型场景
minimal	read, write	基础只读交互、安全受限环境
coding	read, write, exec, web_search	开发任务、代码生成与执行
messaging	sessions_list, whatsapp, telegram	消息处理、通讯自动化
full	全部工具	本地高权限模式、完整功能开放

第一道安全防线： AI 知道自己能用什么，是因为 Prompt 中明确授权了这些工具。如果一个工具未出现在 Prompt 中，AI 就不会尝试调用它。

---

六、组装顺序（Assembly Order）

buildAgentSystemPrompt 使用 lines 字符串数组顺序收集所有片段，最终执行 lines.join("\n") 完成拼接。组装顺序决定了 LLM 的注意力优先级：

① 身份与本质     → 🦸 IDENTITY.md + SOUL.md — "你是谁"
② 用户上下文     → 👤 USER.md — "你为谁服务"
③ 操作环境       → ⚙️ Runtime Info / Shell / Path — "你在哪运行"
④ 核心准则       → 📋 AGENTS.md + MEMORY.md — "你应该怎么做"
⑤ 工具说明       → 🔧 Tooling + TOOLS.md + Skills — "你能用什么"
⑥ 当前状态       → 🕐 Time + Extra System Prompt — "现在是什么上下文"
⑦ 运行快照       → 📌 Runtime Line — "最终环境确认"

⚡ LLM 对 Prompt 开头（Primacy）和结尾（Recency）的注意力最强，因此身份声明放最前，运行快照放最后。

---

七、PromptMode：三种构建模式

模式	说明	适用场景
full	全量模式，包含所有章节	主代理的标准交互场景
minimal	精简模式，跳过身份设定等冗余章节	子代理常用，节省嵌套调用中的 Token
none	最小化模式，仅保留最底层的运行环境快照	极度 Token 敏感的特殊场景

---

八、截断保护机制

当工作区文件过大时，系统具备智能截断保护：

• bootstrapMaxChars：默认 20,000 字符，超过此限制的文件内容会被截断
• 截断策略：优先保留文件开头和结尾的关键信息
• 安全兜底：即使文件被截断，AI 仍可通过 read 工具读取完整内容

---

九、沙箱与路径注入

当 Agent 运行在 Docker 沙箱环境中时，系统会向 Prompt 注入专属的隔离说明段落，防止 AI 混淆宿主机路径与容器内路径：

## Sandbox
You are running inside a Docker container.
Host workspace: /Users/alice/projects/myapp
Container path: /workspace

- Use /workspace for all file operations
- Do NOT use /Users/alice/... paths
- Elevated exec is available for privileged commands

路径脱敏（sanitizeForPromptLiteral）会过滤路径中的特殊字符，防止用户工作区路径中的意外字符破坏 Prompt 结构。

---

十、闭环进化

Agent 被赋予了直接修改工作区文件的权限（通过 write_file/edit_file 工具）。当 Agent 识别到任务中的"教训"或收到用户的配置指令时，会主动写入：

• AGENTS.md（How）— 操作规范更新
• SOUL.md（Who）— 人格定义调整
• USER.md（For Whom）— 用户偏好记录

通过将实战心得沉淀入 Markdown，AI 实现了 跨 Session 的行为准则自我演化。

---

本文由 代码牧星人 原创