小龙虾系统提示词研究-虾说蓉城

本文档基于 OpenClaw 官方文档 及 GitHub 源码梳理，详细说明 OpenClaw 如何为每次 Agent 运行构建完整的 Prompt。

文档版本：2026-05-06 官方文档：https://docs.openclaw.ai GitHub：https://github.com/openclaw/openclaw

一、核心设计原则

OpenClaw 的 Prompt 构建遵循以下核心原则：

1. OpenClaw 完全拥有 Prompt 的组装权：不使用 pi-coding-agent 等运行时默认 Prompt，Prompt 由 OpenClaw 全权构建并注入每次 Agent 运行。
2. Provider 插件只能贡献缓存感知的引导性内容，不能替换完整的 OpenClaw-owned Prompt。
3. Prompt 按稳定性分层：大段稳定内容（如 Project Context）放在内部 Prompt 缓存边界之上；易变的通道/会话内容（如 Runtime、Messaging）放在缓存边界之下，以支持本地后端的前缀缓存复用。
4. Skills 按需加载：Skill 列表（名称 + 描述 + 路径）会注入 System Prompt，但 Skill 指令本身不默认注入，由模型在需要时自行读取 SKILL.md。
5. 内存与上下文分离：内存（MEMORY.md、memory/*.md）存储在磁盘上，需显式读取才进入上下文窗口；上下文（Context）是当前模型窗口内的所有内容。

二、完整 Prompt 结构

OpenClaw 的 System Prompt 由以下固定 sections 组成：

2.1 各 Section 详解

缓存边界（Prompt Cache Boundary）：OpenClaw 将大段稳定内容放在缓存边界之上，将易变的通道/会话 section 放在边界之下，这样本地后端（如有前缀缓存）可以跨通道轮次复用稳定的 workspace 前缀。

2.2 Tooling Section 额外指导

Tooling section 还包含长时间运行的工具使用规范：

• 使用 cron 做未来跟进（check back later、提醒、循环工作），而非 exec 睡眠循环或反复 process 轮询
• 使用 exec/process 仅用于"现在开始、持续运行"的命令
• 自动完成唤醒启用时，启动一次命令并依赖推送式唤醒路径
• 大任务优先使用 sessions_spawn；子 Agent 完成是推送式的
• 不要轮询 subagents list/sessions_list 等待完成

三、组装流程详解

3.1 入口点

3.2 完整组装步骤

用户消息
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Session 解析 + 元数据持久化                              │
│    - 验证参数，解析 session（sessionKey/sessionId）           │
│    - 持久化 session 元数据，返回 { runId, acceptedAt }       │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Session + Workspace 准备                                 │
│    - 解析并创建 workspace（如需要）                          │
│    - 沙箱运行时可能重定向 workspace root                     │
│    - 加载 Skills 快照（注入 env 和 prompt）                  │
│    - 解析引导/上下文文件并注入 system prompt                  │
│    - 获取 session 写锁；打开 SessionManager                   │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Prompt 组装（核心）                                       │
│    - 构建 OpenClaw base prompt（含所有固定 sections）        │
│    - 注入 Skills list（formatSkillsForPrompt）              │
│    - 注入 Bootstrap Context Files（Project Context）        │
│    - 应用 per-run overrides                                  │
│    - Provider 插件可替换/注入部分 sections                   │
│    - 模型特定限制和 compaction 预留 token 生效               │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Model Inference                                           │
│    - 调用 runEmbeddedPiAgent（pi-agent-core 运行时）         │
│    - 订阅 pi 事件，流式推送 assistant/tool deltas           │
│    - 执行工具，收集结果                                      │
│    - lifecycle end/error 由 subscribeEmbeddedPiSession 发射  │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. 回复组装（Reply Shaping）                                │
│    - 汇总 assistant text（+ reasoning）                      │
│    - 附加工具摘要（verbose + allowed 时）                     │
│    - assistant error text（模型错误时）                       │
│    - 过滤 NO_REPLY / no_reply                               │
│    - 移除重复的 messaging tool                              │
│    - 无渲染内容 + 工具错误 → 发送 fallback 错误回复          │
└─────────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│ 6. 持久化 + Compaction                                       │
│    - 写会话 transcript（受 session 写锁保护）                │
│    - 自动 compaction 触发 → 压缩旧历史                       │
│    - 自动 memory flush（silently） → 提醒 agent 保存重要上下文│
└─────────────────────────────────────────────────────────────┘

四、系统提示词（System Prompt）构建细节

4.1 基础构成

System Prompt 由以下层次叠加而成：

┌──────────────────────────────────────────────┐
│ 1. OpenClaw Base Prompt（固定 sections 集）    │
│    - Tooling                                 │
│    - Execution Bias                          │
│    - Safety                                  │
│    - （Skills，见 4.2）                       │
│    - OpenClaw Self-Update                    │
│    - Workspace                               │
│    - Documentation                           │
│    - Current Date & Time（仅时区）            │
│    - Reply Tags（可选）                       │
│    - Heartbeats（启用时）                     │
│    - Runtime                                 │
│    - Reasoning                               │
├──────────────────────────────────────────────┤
│ 2. Skills List（可用时）                     │
│    <available_skills>                        │
│    <skill><name>...</name><description>...  │
│    <location>...</location></skill>          │
│    </available_skills>                       │
├──────────────────────────────────────────────┤
│ 3. Project Context（Bootstrap Files）        │
│    - Workspace Files 注入区域                 │
│    - 大文件自动截断（见 4.3）                 │
├──────────────────────────────────────────────┤
│ 4. Dynamic Sections（below cache boundary）  │
│    - Sandbox（启用时）                        │
│    - Messaging                               │
│    - Group Chat Context                      │
│    - Heartbeats runtime                      │
│    - Runtime（变化部分）                      │
├──────────────────────────────────────────────┤
│ 5. Provider Hooks 贡献                       │
│    - 可替换：interaction_style, tool_call_style, │
│      execution_bias                          │
│    - 缓存稳定前缀（above boundary）           │
│    - 动态后缀（below boundary）               │
└──────────────────────────────────────────────┘

4.2 Skills 处理

Skills 不默认将指令全文注入 Prompt。处理方式：

可用 Skills 元数据列表
（name + description + location）
        │
        ▼
注入 System Prompt 的 <available_skills> 区块
        │
        ▼
模型在需要时自行用 read 工具读取 SKILL.md

Skills 列表注入示例格式：

<available_skills>
  <skill>
    <name>stock-analysis</name>
    <description>A股股票深度分析技能...</description>
    <location>~/.openclaw/workspace/skills/stock-analysis/SKILL.md</location>
  </skill>
  ...
</available_skills>

Eligibility 检查： - Skill metadata gates（metadata.openclaw） - 运行时环境/config 检查 - Agent skill allowlist（agents.defaults.skills 或 agents.list[].skills） - Plugin-bundled skills 仅在插件启用时有效

预算控制： - 全局默认：skills.limits.maxSkillsPromptChars - Per-agent 覆盖：agents.list[].skillsLimits.maxSkillsPromptChars - 与运行时读取/注入的大小控制（memory_get、工具结果、compaction 后 AGENTS.md 刷新）分开

4.3 Bootstrap Files（Project Context）注入

OpenClaw 在每次运行时会将以下文件（如果存在）注入到 Project Context 区域：

memory/*.md（每日笔记）不参与正常引导注入。在普通轮次中通过 memory_search/memory_get 按需访问，不占用上下文窗口（除非模型显式读取）。/new 和 /reset 除外：运行时可以 prepend 最近每日内存作为首发上下文块。

截断机制：

Sub-agent 差异： - Sub-agent session 仅注入 AGENTS.md 和 TOOLS.md（其他引导文件过滤掉以保持 sub-agent 上下文小）

Hook 拦截： - agent:bootstrap hook 可以在最终确定 system prompt 之前拦截并修改/替换注入的引导文件

4.4 Prompt 模式（Prompt Modes）

OpenClaw 为 sub-agent 渲染更小的 system prompt，由运行时设置 promptMode（非用户可见配置）：

五、用户提示词（User Prompt）构建

5.1 用户消息处理

用户消息进入 Prompt 前经过以下处理：

用户输入（消息文本）
    │
    ▼
┌──────────────────────────────────────────────┐
│ 1. 解析消息 envelope                         │
│    - 提取 chat_id, account_id, channel 等元数据 │
│    - 提取引用的消息、群组信息等                 │
└──────────────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────────┐
│ 2. 指令/directive 处理                         │
│    - 独立指令：消息仅为 /... 时作为命令执行     │
│    - Directives：/think, /verbose, /trace,    │
│      /reasoning, /elevated, /model, /queue    │
│      → 在发给模型前剥离                        │
│    - Inline shortcuts：白名单发送者的 /...     │
│      → 立即执行并从消息中剥离                  │
└──────────────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────────────┐
│ 3. 附件处理                                   │
│    - 图片/文件/音频 作为 attachments 注入      │
│    - 使用工具结果格式传递                      │
└──────────────────────────────────────────────┘
    │
    ▼
最终用户消息内容

5.2 历史消息（Conversation History）

完整对话历史（你的消息 + 助手的消息）作为 User Prompt 的一部分发送给模型。

• 存储在 session transcript ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl
• 直到被 compaction/pruning 压缩/修剪
• 模型最终看到的消息列表 = System Prompt + 有限历史消息

5.3 工具调用与结果

工具调用（模型决定）
    │
    ▼
工具执行 → 结果
    │
    ▼
结果注入下一轮 Prompt（作为模型输入的一部分）

六、会话历史管理与 Compaction

6.1 Context Engine

OpenClaw 使用 Context Engine 控制每次运行的模型 Context 构建方式：

内置 legacy Engine（默认）： - Ingest：no-op（session manager 直接处理消息持久化） - Assemble：透传（现有 sanitize → validate → limit 管道） - Compact：使用内置 summarization compaction - After Turn：no-op

6.2 Compaction（压缩）

当对话历史过长时，OpenClaw 自动压缩：

┌──────────────────────────────────────────────┐
│ Compaction 管道                              │
│                                              │
│ 1. 将旧消息汇总为单一摘要                     │
│ 2. 保留最近消息完整                           │
│ 3. 替换旧消息为摘要条目                       │
│ 4. 自动 memory flush（silently）             │
│    → 提醒 agent 在 compaction 前保存重要上下文│
└──────────────────────────────────────────────┘

自动 Memory Flush： - Compaction 前 OpenClaw 运行一个 silent turn，提醒 agent 将重要上下文保存到 memory 文件 - 对于本地模型，可在 config 中设置精确的 memory-flush model override

6.3 Session Pruning

• Pruning：从内存中的 prompt 丢弃旧工具结果以释放上下文窗口空间
• 不重写 session transcript（完整历史仍可在磁盘上查看）
• 与 Compaction 的区别：Pruning 释放内存但不改变 transcript；Compaction 重写 transcript

七、Provider Hooks 与插件扩展

7.1 Provider 插件可贡献的内容

Provider 插件可以：

7.2 Plugin Hooks（OpenClaw 生命周期拦截点）

完整 Hook 列表：

八、关键配置参数

以下参数控制 Prompt 组装行为：

8.1 Bootstrap 控制

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      bootstrapMaxChars: 12000,           // 单文件最大字符
      bootstrapTotalMaxChars: 60000,       // 总最大字符
      bootstrapPromptTruncationWarning: "once",  // 截断警告
      heartbeat: {
        includeSystemPromptSection: true   // 是否注入心跳 section
      }
    }
  }
}

8.2 Skills 控制

{
  skills: {
    limits: {
      maxSkillsPromptChars: 5000    // Skills list 最大字符数
    }
  },
  agents: {
    defaults: {
      skills: ["github", "weather"]  // 白名单，不设置则无限制
    },
    list: [
      { id: "docs", skills: ["docs-search"] }  // 替换默认，非合并
    ]
  }
}

8.3 Compaction 控制

{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          model: "ollama/qwen3:8b"  // memory-flush 专用模型
        }
      }
    }
  }
}

8.4 Context Engine

{
  plugins: {
    slots: {
      contextEngine: "legacy"  // 或插件提供的引擎 ID
    }
  }
}

九、Inspect 命令

了解当前 Prompt 组成的命令：

/context list 示例输出：

🧠 Context breakdown
Workspace: ~/.openclaw/workspace
Bootstrap max/file: 12,000 chars
Sandbox: mode=non-main sandboxed=false
System prompt (run): 38,412 chars (~9,603 tok)

Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars | injected 1,742 chars
- SOUL.md: OK | raw 912 chars | injected 912 chars
- TOOLS.md: TRUNCATED | raw 54,210 chars | injected 20,962 chars

Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tools: read, edit, write, exec, process, browser, message, ...

十、完整数据流图

                           ┌─────────────────────────────────────────┐
                           │           OpenClaw Gateway               │
                           │                                         │
  用户消息 ──► Session路由 ──► Session准备 ──► Prompt组装             │
                           │        │               │                 │
                           │        ▼               ▼                 │
                           │   Workspace      ┌────────────────────┐  │
                           │   Skills加载    │  System Prompt     │  │
                           │   Bootstrap文件  │  ┌──────────────┐  │  │
                           │                  │  │ Base Prompt  │  │  │
                           │                  │  │ (固定sections)│  │  │
                           │                  │  ├──────────────┤  │  │
                           │                  │  │ Skills List  │  │  │
                           │                  │  ├──────────────┤  │  │
                           │                  │  │Project Context│  │  │
                           │                  │  │(Bootstrap Files)│  │
                           │                  │  ├──────────────┤  │  │
                           │                  │  │ Dynamic Sects │  │  │
                           │                  │  │(below cache)  │  │  │
                           │                  │  └──────────────┘  │  │
                           │                  └────────────────────┘  │
                           │                              │            │
                           │                              ▼            │
                           │                    pi-agent-core         │
                           │                    (Model Inference)    │
                           │                              │            │
                           │              ┌─────────────────┐          │
                           │              │ 工具执行循环    │          │
                           │              │ read/write/exec│          │
                           │              │ sessions_send  │          │
                           │              └─────────────────┘          │
                           │                              │            │
                           │                              ▼            │
                           │                    Reply Shaping          │
                           │              (汇总text + 工具摘要)         │
                           │                              │            │
                           │                              ▼            │
                           │         ┌────────────────────────────────┐ │
                           │         │ Session 持久化                 │ │
                           │         │ • 写 transcript (.jsonl)      │ │
                           │         │ • 更新 sessions.json          │ │
                           │         │ • Compaction 检查             │ │
                           │         │ • Memory Flush (silent)       │ │
                           │         └────────────────────────────────┘ │
                           └─────────────────────────────────────────┘

十一、相关文档索引

本文档由大管家从 OpenClaw 官方文档和 GitHub 源码梳理生成，如有问题请查阅官方文档或源码。