# OpenClaw 大模型应用分析报告
OpenClaw 大模型应用分析报告
1. 项目概述
- 项目名称: OpenClaw
- 项目描述: 个人 AI 助手网关，支持多通道消息集成 (WhatsApp, TG, Slack, Discord, Signal, iMessage, Microsoft Teams 等)
- 主要功能:
- 多渠道消息收发与管理
- AI Agent 运行时 (基于 Pi 框架)
- 技能系统 (Skills) 扩展
- 工具调用与浏览器控制
- 语音唤醒与对话模式
- Canvas 可视化工作区
- 多代理路由与会话管理
- 技术栈:
- TypeScript (ESM)
- Node.js 22+
- pnpm 包管理
- Vitest 测试框架
- Express WebSocket
- @mariozechner/pi-agent-core (AI Agent 核心)
- @mariozechner/pi-coding-agent (编码代理)
2. 项目逻辑或数据流分析
sequenceDiagram
participant User as 用户
participant Channel as 消息通道<br/>(WhatsApp/TG/Discord等)
participant Gateway as Gateway<br/>(WebSocket控制平面)
participant Session as Session管理器
participant Agent as Pi Agent运行时
participant LLM as 大模型API<br/>(Anthropic/OpenAI等)
participant Tools as 工具系统
participant Skills as 技能系统
User->>Channel: 发送消息
Channel->>Gateway: 路由到Gateway
Gateway->>Session: 获取/创建会话
Session->>Agent: 构建系统提示词
Note over Agent: 1. 加载SOUL.md/AGENTS.md
Note over Agent: 2. 加载技能提示词
Note over Agent: 3. 注入工具定义
Note over Agent: 4. 构建Runtime信息
Agent->>LLM: 发送请求(含工具定义)
LLM->>Agent: 返回响应/工具调用
alt 工具调用
Agent->>Tools: 执行工具
Tools-->>Agent: 返回结果
Agent->>LLM: 继续对话
end
Agent-->>Gateway: 返回回复
Gateway->>Channel: 路由回原通道
Channel->>User: 交付消息
3. 提示词分类统计
| 类别 | 数量 | 用途说明 |
|---|---|---|
| 系统提示词 | 1 | 核心系统提示词，定义 Agent 身份、工具、安全规则 |
| 身份模板 | 3 | AGENTS.md, SOUL.md, TOOLS.md - 定义 Agent 个性与工作空间 |
| 技能提示词 | 55+ | 各类技能的 SKILL.md 文件，提供领域专业知识 |
| 上下文提示词 | 多个 | 群聊上下文、子代理上下文、心跳提示词 |
| 安全提示词 | 内置 | 安全规则、授权发送者验证 |
| 扩展提示词 | 2+ | OpenProse VM、语音响应生成等 |
4. 大模型应用场景分析
场景 1: 主会话系统提示词构建
- 触发条件: 用户通过任意通道发送消息
- 使用的提示词: system-prompt.md
- 代码位置:
src/agents/system-prompt.ts:189 - 输入输出:
- 输入: 工作空间目录、工具列表、技能提示词、运行时信息
- 输出: 完整的系统提示词字符串
- 作用: 构建 Agent 的"身份认知"，包括工具说明、安全规则、工作空间指引
场景 2: 技能动态加载与选择
- 触发条件: Agent 需要使用特定领域功能
- 使用的提示词: 各技能目录下的 SKILL.md
- 代码位置:
src/agents/skills/workspace.ts:446 - 输入输出:
- 输入: 工作空间目录、配置、技能过滤器
- 输出: 格式化的技能提示词块
- 作用: 根据任务需求动态加载相关技能，指导 Agent 正确使用
场景 3: 群聊上下文注入
- 触发条件: 群聊消息触发 Agent
- 使用的提示词: 群聊系统提示词
- 代码位置:
src/auto-reply/reply/get-reply-run.ts:257 - 输入输出:
- 输入: 群组配置、群介绍、群系统提示词
- 输出: 额外系统提示词块
- 作用: 为群聊场景添加上下文，指导 Agent 在多人群组中的行为
场景 4: 子代理创建与通信
- 触发条件: 主 Agent 需要派生子任务
- 使用的提示词: subagent-system-prompt.md
- 代码位置:
src/agents/subagent-spawn.ts:382 - 输入输出:
- 输入: 子任务描述、父会话上下文
- 输出: 子代理专属系统提示词
- 作用: 创建隔离的子代理实例，继承必要上下文但保持独立性
场景 5: 心跳轮询与主动工作
- 触发条件: 定时心跳触发
- 使用的提示词: 心跳提示词 + HEARTBEAT.md
- 代码位置:
src/agents/system-prompt.ts:630 - 输入输出:
- 输入: 心跳配置、工作空间状态
- 输出: HEARTBEAT_OK 或主动提醒
- 作用: Agent 主动检查任务、发送提醒、执行后台工作
5. 上下文工程
Agent 循环机制
OpenClaw 采用基于 Pi 框架的 Agent 运行时，实现了完整的 Agent 循环：
1. LLM Makes the Loop (启动循环)
↓
用户消息 → 构建系统提示词 → 调用 LLM API
2. LLM in the Loop (循环中)
↓
LLM 响应 → 解析工具调用 → 执行工具 → 返回结果 → 继续调用 LLM
3. LLM Ends the Loop (结束循环)
↓
LLM 返回最终回复 → 路由回消息通道 → 交付用户
工具定义 (Tools)
以下是 OpenClaw 提供给大模型的核心工具：
| 工具名称 | 功能描述 | 使用场景 |
|---|---|---|
| read | 读取文件内容 | 查看代码、配置、日志 |
| write | 创建或覆盖文件 | 生成新文件 |
| edit | 精确编辑文件 | 修改代码片段 |
| apply_patch | 应用多文件补丁 | 批量代码变更 |
| grep | 搜索文件内容 | 查找代码模式 |
| find | 按模式查找文件 | 定位文件 |
| ls | 列出目录内容 | 浏览项目结构 |
| exec | 运行 Shell 命令 | 执行构建、测试等 |
| process | 管理后台进程 | 长时间运行的任务 |
| web_search | 网络搜索 | 获取实时信息 |
| web_fetch | 获取网页内容 | 抓取网页 |
| browser | 控制浏览器 | 网页自动化 |
| canvas | Canvas 演示/评估 | 可视化工作区 |
| nodes | 节点设备操作 | 摄像头、屏幕录制 |
| cron | 管理定时任务 | 设置提醒 |
| message | 发送消息 | 主动通信 |
| gateway | 管理网关 | 重启、更新 |
| sessions_list | 列出会话 | 多会话管理 |
| sessions_history | 获取会话历史 | 查看对话记录 |
| sessions_send | 发送到其他会话 | 跨会话通信 |
| sessions_spawn | 创建子代理 | 任务委托 |
| subagents | 管理子代理 | 列出/控制/终止 |
| session_status | 显示会话状态 | 用量统计 |
| image | 图像分析 | 视觉理解 |
上下文提供方式
-
工作空间文件注入:
SOUL.md- Agent 个性与行为准则AGENTS.md- 工作空间规则与记忆指引TOOLS.md- 环境特定配置MEMORY.md- 长期记忆存储
-
技能系统:
- 自动发现并加载
skills/*/SKILL.md - 按需读取技能详情
- 支持技能过滤与优先级
- 自动发现并加载
-
运行时信息:
- Agent ID、主机名、操作系统
- 当前模型、默认模型
- 通道信息、能力列表
- 思考级别、沙箱状态
-
消息上下文:
- 群聊上下文与介绍
- 入站消息元数据
- 回复标签指引
安全与隔离
- DM 配对策略: 未知发送者需配对码验证
- 沙箱模式: 非 main 会话可运行在 Docker 沙箱中
- 工具策略: 按会话/群组/代理配置工具访问权限
- 提升权限: 可配置需要确认的提升执行
6. 提示词文件位置索引
核心系统提示词
src/agents/system-prompt.ts- 主系统提示词构建逻辑src/agents/pi-embedded-runner/system-prompt.ts- 嵌入式运行时提示词
模板文件
docs/reference/templates/AGENTS.md- AGENTS.md 模板docs/reference/templates/SOUL.md- SOUL.md 模板docs/reference/templates/TOOLS.md- TOOLS.md 模板
技能目录
skills/*/SKILL.md- 55+ 内置技能extensions/*/skills/*/SKILL.md- 扩展技能
上下文构建
src/auto-reply/reply/commands-system-prompt.ts- 命令系统提示词src/auto-reply/reply/get-reply-run.ts- 获取回复运行时src/agents/skills/workspace.ts- 技能工作空间管理src/agents/subagent-spawn.ts- 子代理创建
文档
docs/concepts/system-prompt.md- 系统提示词概念说明docs/concepts/agent-loop.md- Agent 循环说明
7. 关键设计模式
7.1 提示词组合模式
系统提示词采用模块化组合方式：
基础身份
+ 工具说明
+ 安全规则
+ 技能块 (可选)
+ 记忆指引 (可选)
+ 文档路径 (可选)
+ 工作空间信息
+ 授权发送者
+ 时间信息
+ 注入文件 (SOUL.md, AGENTS.md 等)
+ 回复标签
+ 消息指引
+ 语音提示 (可选)
+ 群聊上下文 (可选)
+ 推理格式 (可选)
+ 静默回复规则
+ 心跳规则
+ 运行时信息
7.2 三级提示词模式
- full: 完整提示词 - 用于主 Agent
- minimal: 最小提示词 - 用于子代理
- none: 仅身份行 - 用于极简场景
7.3 技能发现与过滤
- 扫描多个技能目录 (bundled, managed, workspace, extra)
- 解析 frontmatter 元数据
- 应用配置过滤和资格检查
- 格式化为
<available_skills>块 - 应用字符限制防止溢出
8. 总结
OpenClaw 是一个功能完善的个人 AI 助手平台，其提示词工程具有以下特点：
- 模块化设计: 系统提示词由多个独立模块组合而成，便于维护和扩展
- 动态加载: 技能系统支持按需加载，减少不必要的 token 消耗
- 多级隔离: 主会话、群聊、子代理有不同的提示词策略
- 安全优先: 内置安全规则、授权验证和沙箱机制
- 上下文感知: 根据运行时环境、通道能力动态调整提示词
- 可扩展性: 通过 Skills 和 Plugins 系统轻松扩展功能
浙公网安备 33010602011771号