OpenClaw Agent System Prompt 架构详解报告
一、文章概述
本文详细拆解了OpenClaw Agent发送给LLM的完整System Prompt组成结构（版本v2.1，更新时间2026-03-05），将其分为9层架构，重点说明了用户可控的Layer 7（Workspace Files）和Layer 8（Bootstrap Hook System），其他层为框架自动生成。
二、核心架构分层详解
1. Layer 1: OpenClaw Framework Core（框架核心层）
- 比喻：操作手册的”使用说明”部分，告诉LLM身份、能力和回应规则
- 核心内容：定义Agent基础身份、工具调用规范、安全边界等
- 设计权衡：
- 权衡点：灵活性 vs 一致性
- 决策：框架层统一生成，保证所有Agent基础行为一致
- 好处：用户无需重复配置基础规则，框架升级自动同步新能力，降低配置错误风险
- 代价：用户无法修改核心规则，特殊行为需通过Layer 7/8间接实现
2. Layer 2: Tool Definitions（工具定义层）
- 比喻：瑞士军刀的工具清单，说明可用工具、功能和使用方法
- 核心内容：使用JSON Schema定义工具参数结构
- 设计权衡：
- 权衡点：灵活性 vs 类型安全
- 决策：采用严格JSON Schema定义工具参数
- 好处：LLM能准确理解工具用法，框架可提前验证参数，自动生成文档和类型定义
- 代价：添加新工具需编写完整Schema，无法支持完全动态参数结构
3. Layer 3: Skills Registry（技能注册表）
- 比喻：餐厅的”特色菜谱”，提供专业领域的”配方”调用
- 核心内容：自动扫描~/development/openclaw/skills/目录加载技能
- 设计权衡：
- 权衡点：灵活性 vs 维护成本
- 决策：自动扫描技能目录
- 好处：添加新技能只需放入目录，无需修改配置，所有Agent自动获得新技能
- 代价：无法精确控制每个Agent可用技能，所有技能都会注入System Prompt增加token消耗
4. Layer 4: Model Aliases（模型别名层）
- 比喻：快捷键，给复杂模型路径起简短别名
- 核心内容：为常用模型定义简短别名，支持多Provider切换
- 设计权衡：
- 权衡点：灵活性 vs 可读性
- 决策：允许用户定义模型别名
- 好处：简化模型调用，支持多Provider切换，便于A/B测试和模型迁移
- 代价：需要维护别名配置文件，可能造成不同Agent同一别名指向不同模型的混淆
5. Layer 5: Protocol Specifications（协议规范层）
- 比喻：交通规则，定义Agent与系统交互的标准协议
- 核心内容：标准化交互协议（Silent Replies、Heartbeats、Reply Tags等）
- 设计权衡：
- 权衡点：自由度 vs 一致性
- 决策：定义标准化交互协议
- 好处：保证所有Agent行为一致，支持自动化监控和健康检查，简化多Agent协作
- 代价：限制Agent自由表达，需要LLM严格遵守协议
6. Layer 6: Runtime Info（运行时信息层）
- 比喻：仪表盘，显示当前运行环境的实时状态
- 核心内容：每次请求注入最新运行时状态（时间、模型、环境等）
- 设计权衡：
- 权衡点：Token消耗 vs 上下文准确性
- 决策：每次请求注入最新运行时状态
- 好处：LLM知道当前时间、模型和环境，避免时间错乱、能力误判和路径错误
- 代价：每次请求消耗约2KB token，信息可能包含冗余
7. Layer 7: Workspace Files（工作区文件层）★ 用户可控
- 比喻：工作笔记，用户可直接编辑的静态配置文件
- 核心内容：包含IDENTITY.md、SOUL.md、TOOLS.md等核心配置文件
- 设计权衡：
- 权衡点：框架稳定性 vs 用户自由度
- 决策：分离”变”与”不变”，框架层保证一致性，用户层允许个性化
- 好处：用户可定义Agent身份、工作规范和记忆，框架升级不破坏用户配置，配置文件可版本管理
- 代价：用户无法修改框架核心行为，需要学习TELOS框架和文件结构
8. Layer 8: Bootstrap Hook System（动态注入层）★ 用户可控
- 比喻：可编程注射器，用户可写脚本在运行时动态注入内容到System Prompt
- 核心内容：四种Hook机制：
- agent:bootstrap Hook：完全控制bootstrapFiles数组，可增删改文件和内容
- bootstrap-extra-files Hook：通过配置文件追加额外文件，不修改现有文件
- before_prompt_build Hook：在系统提示词构建后、发送给LLM前修改最终prompt
- （文章内容被截断，第四种Hook未显示）
- 设计权衡：
- 权衡点：静态配置简单性 vs 动态注入灵活性
- 决策：提供动态Hook机制
- 好处：可根据上下文动态调整注入内容，执行shell命令并注入输出，读取外部文件注入，支持条件判断
- 代价：需要学习Hook系统语法和触发机制，Hook脚本错误可能导致System Prompt异常
三、关键要点总结
- 用户可控重点：Layer 7（静态配置文件）和Layer 8（动态注入Hook）是用户自定义Agent行为的核心入口
- 设计原则：框架层保证一致性和稳定性，用户层提供个性化和灵活性
- 常见需求实现路径：
- 定义Agent身份 → 编辑Layer 7的IDENTITY.md
- 添加项目文档 → 使用Layer 8的bootstrap-extra-files Hook
- 注入实时上下文 → 使用Layer 8的before_prompt_build Hook
- 控制文件大小 → 调整bootstrapMaxChars配置
四、价值与意义
该架构通过分层设计实现了”一致性”与”灵活性”的平衡：
- 对框架开发者：保证核心规则统一，便于维护和升级
- 对Agent使用者：提供丰富的自定义能力，满足不同场景需求
- 对LLM：提供清晰的边界和规则，提升Agent行为的可预测性和可靠性
这份架构详解为OpenClaw Agent的定制化开发提供了清晰的指南，帮助用户高效构建符合特定需求的AI Agent。