OpenClaw 架构详解：AI Agent 的编排与执行骨架

核心定位OpenClaw 自动化运行时Automation Runtime一个给 AI 套上安全、可控、可审计缰绳的框架。它不追求 AI 的惊喜而是追求可预测性、可审计性和零故障。文章目录一、设计哲学网关优先核心极小二、八层架构全景三、逐层详解3.1 交互层——IM 通用总线3.2 运行时层——Gateway核心枢纽星型拓扑Hub-and-SpokeGateway 核心职责基于通道Channel的命令队列3.3 核心引擎层——Pi EnginePi 的极简主义嵌入式 SDK 集成非 RPC/子进程工具注入机制关键Pi 包依赖结构MCP 支持通过桥接3.4 调度层——Heartbeat 多 Agent 路由HEARTBEAT.md从被动响应到主动自治多 Agent 路由混合架构路由 成本优化3.5 能力层——Skills SystemSKILL.md面向 LLM 的说明书技能三种来源agentskills.io 标准条件激活策略3.6 个性化层——SOUL.md3.7 持久化层——会话与记忆双层存储架构记忆生命周期上下文压缩Compaction3.8 安全层——护栏与可观测性致命三要素护栏机制可观测性Observability历史安全教训四、7 个 Markdown 配置文件各文件详解五、端到端消息流从用户输入到结果返回六、Pi 引擎集成完整的调用链关键集成参数七、五大设计亮点亮点 1记忆机制——混合检索 上下文管理亮点 2本地系统操作能力亮点 3插件可扩展性亮点 4心跳机制——主动自治亮点 5多 Agent 路由八、ima.copilot 中的映射九、与 Hermes 的定位对比十、总结一、设计哲学网关优先核心极小OpenClaw 遵循两条底层信念信念含义网关优先Gateway-First所有流量、控制流、策略执行都经过中央 Gateway确定性编排强调控制与可预测核心极小Minimal CorePi 引擎只保留最少的底层原语Read/Write/Edit/Bash复杂能力全部通过工具注入和技能系统外挂OpenClaw 问的是如何给 AI 套上一个安全、可控、可审计的缰绳答案是一个管理有序的工厂——原料用户请求从各个入口进入由中央调度系统分配到不同的生产线Agent每道工序都有明确的操作手册SOUL.md、AGENTS.md和质量监控。二、八层架构全景┌─────────────────────────────────────────────────────────┐ │ 交互层Interaction │ │ WhatsApp / Telegram / Discord / iMessage / 飞书 │ ├─────────────────────────────────────────────────────────┤ │ 运行时层Gateway │ │ 会话管理 / 实例发现 / IM 通道 / 沙盒接入 / 策略引擎 │ ├─────────────────────────────────────────────────────────┤ │ 核心引擎层Pi Engine │ │ 模型抽象 / 流式推理 / Agent Loop / 工具执行 / SDK 嵌入 │ ├─────────────────────────────────────────────────────────┤ │ 调度层Heartbeat Routing │ │ HEARTBEAT.md / Cron 机制 / 多 Agent 路由 / 成本优化 │ ├─────────────────────────────────────────────────────────┤ │ 能力层Skills System │ │ SKILL.md / agentskills.io / 动态工具链编排 / 上下文感知 │ ├─────────────────────────────────────────────────────────┤ │ 个性化层SOUL.md │ │ 价值观 / 语气 / 幽默感 / 边界 / 连续性 / 氛围 │ ├─────────────────────────────────────────────────────────┤ │ 持久化层Persistence │ │ sessions.json / *.jsonl transcript / MEMORY.md / ICD │ ├─────────────────────────────────────────────────────────┤ │ 安全层Security │ │ 沙箱化 / 网络白名单 / 权限最小化 / 护栏 / 可观测性 │ └─────────────────────────────────────────────────────────┘三、逐层详解3.1 交互层——IM 通用总线核心思想把 IM 软件当作唯一 UIAgent 就像通讯录里的一个联系人。Channel Adapter通道适配器 ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ WhatsApp │ │ Telegram │ │ Discord │ │ Adapter │ │ Adapter │ │ Adapter │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ ▼ ▼ ▼ 标准化消息格式统一文本 附件提取关键能力能力说明零学习成本用户无需适应新仪表盘在常用 IM 里直接对话全平台覆盖借助 IM 天然跨端能力Mobile/Desktop/Web/Watch异步交互用户下达长耗时任务后可关闭窗口任务完成 Agent 主动通知标准化预处理不同 IM 的消息格式统一规避格式差异附件自动提取图片、文档、音频等附件自动识别和提取支持 20 平台WhatsApp、Telegram、Discord、Apple iMessage、Slack、飞书、LINE、Signal 等。3.2 运行时层——Gateway核心枢纽Gateway 是 OpenClaw 的大脑和交通警察本质上是一个 WebSocket 服务器。监听地址ws://127.0.0.1:18789默认 loopback外部访问需 Tailscale/SSH 隧道星型拓扑Hub-and-SpokeWhatsApp / Telegram / Slack / Discord / iMessage... ↓ ┌──────────────┐ │ Gateway │ ← 中心枢纽WebSocket 控制平面 │ ws://127.0.0.1:18789 └──┬──┬──┬──┬──┘ │ │ │ └─ iOS/Android Nodes │ │ └──── WebChat UI │ └─────── CLI (openclaw …) └────────── Pi Agent Runtime (RPC)Gateway 核心职责职责说明会话管理会话创建、存储、分支、压缩实例发现Agent 实例的注册与发现机制IM 通道连接连接到各 IM 平台沙盒接入连接沙盒环境与外部系统系统级掌控对 Pi 引擎的会话生命周期、事件流、权限边界、工具注入的全面控制存在感知PresenceAgent 在线状态管理配置热更新无需重启即可更新配置Cron 定时任务调度心跳任务Webhook 触发外部事件驱动的任务启动设备配对认证新设备接入时的安全认证基于通道Channel的命令队列关键设计每个会话都有专属执行通道保证操作有序进行。传统问题async/await 异步嵌套 → 状态冲突、调试困难 OpenClaw 方案Channel-based 命令队列默认序列化执行 Channel AWhatsApp 私聊→ 串行队列 → Agent 1 Channel BDiscord 群组 → 串行队列 → Agent 2 Channel CCLI 命令行 → 串行队列 → Agent 1 低风险、可并行的任务可显式声明并行运行 → 兼顾有序性和效率3.3 核心引擎层——Pi EnginePi 是 OpenClaw 的心脏——提供模型抽象、流式推理、Agent Loop、工具执行等底层机制。Pi 提供的是通用引擎——让系统能跑起来OpenClaw 负责的是车身和交通规则——让系统跑得久、跑得稳。Pi 的极简主义核心能力收敛到极少原语 Read → 读取文件 Write → 写入文件 Edit → 编辑文件 Bash → 执行命令 少而硬、可控、可复用。嵌入式 SDK 集成非 RPC/子进程// ❌ 不会这样做子进程import{spawn}fromchild_process;spawn(pi,[run,...]);// ❌ 也不会这样做RPCfetch(http://localhost:3000/rpc,{method:POST,...});// ✅ 实际做法直接导入并实例化import{createAgentSession}fromearendil-works/pi-coding-agent;const{session}awaitcreateAgentSession({...});工具注入机制关键OpenClaw不会沿用 Pi 自带工具再加点料而是Step 1: 清空 Pi 的 built-in tools Step 2: 用 customTools 注入 OpenClaw 的整套工具链// 伪代码示例pi_sessioncreateAgentSession();pi_session.tools.clear();// 清空 Pi 内置工具pi_session.tools.inject(openclaw_toolchain);// 注入 OpenClaw 工具链结果角色职责Pi“工具如何执行”——推理循环、流式响应、工具调用协议OpenClaw“有哪些工具、哪些能用、哪些要审批、哪些只能读不能写”——IM 通道动作、沙盒能力、channel-specific actions、连接器Pi 包依赖结构earendil-works/pi-ai → 核心 LLM 抽象Model、streamSimple、消息类型、提供商 API earendil-works/pi-agent-core → Agent loop、工具执行、AgentMessage 类型 earendil-works/pi-coding-agent → 高级 SDKcreateAgentSession、SessionManager、AuthStorage、ModelRegistry earendil-works/pi-tui → 终端 UI 组件用于本地 TUI 模式MCP 支持通过桥接Pi不内置 MCP 支持路线选择不是偷懒通过mcporter桥接把 MCP 能力变成 CLI/绑定再作为 skill/工具链的一部分交给 Agent 调用取舍协议复杂度留在外部核心保持干净能力仍可插拔、可替换3.4 调度层——Heartbeat 多 Agent 路由HEARTBEAT.md从被动响应到主动自治# HEARTBEAT.md 示例 ## 每 4 小时 - 检查服务器状态异常时通知 ## 每天早上 8:00 - 推送天气预报 - 查看日历提醒今日日程 ## 每周一 9:00 - 汇报上周工作日志摘要意义Agent 从被动等待指令变为主动巡检执行具备 7×24 小时运行能力这是成为数字员工的关键。多 Agent 路由Discord 服务器 → Agent AClaude Sonnet友好版主风格开放社区工具 Telegram 私聊 → Agent BGPT-4正式客服语气限制文件访问 CLI 命令行 → Agent A共享工作空间完整工具权限 每个 Agent 实例拥有 ├── 独立工作空间 ├── 独立会话历史 ├── 独立模型配置 └── 独立行为设定混合架构路由 成本优化简单任务闲聊/查询→ 轻量模型DeepSeek/Haiku→ 低成本 复杂任务编码/分析→ 旗舰模型Claude/GPT-4 → 高质量 高流量场景自动启动备用模型保证服务稳定性3.5 能力层——Skills SystemOpenClaw 最核心的竞争力用 Markdown 文件SKILL.md作为接口描述语言。SKILL.md面向 LLM 的说明书不同于传统插件系统OpenAPI/Swagger需要严格的机器可解析格式SKILL.md 是写给 LLM 看的自然语言文档# Skill: 网络诊断工具 ## 什么时候用 当用户反馈网络慢、连不上服务器、需要排查网络问题时激活。 ## 怎么用 1. 先 ping 目标地址看延迟和丢包 2. 再 traceroute 看路径 3. 如果是 DNS 问题执行 nslookup ## 参数 - target: 目标 IP 或域名必填 - count: ping 次数可选默认 4 ## 注意 - 不要对内网地址执行 traceroute浪费时间 - 结果超过 20 行时只摘要关键信息LLM 读取这个文档就知道怎么用不需要写胶水代码。技能三种来源类型说明示例Bundled内置技能随 OpenClaw 安装文件操作、Shell、浏览器控制ManagedClawHub 社区技能搜索安装GitHub 管理、邮件助手、智能家居Workspace用户自定义技能针对特定业务流程的自动化agentskills.io 标准agentskills.io 是 OpenClaw 和 Hermes 共同遵循的技能标准 技能包结构 my-skill/ ├── SKILL.md ← 技能说明入口 ├── manifest.json ← 元数据版本、依赖、权限 └── scripts/ ← 可执行脚本 └── main.sh条件激活策略用户消息 → 意图匹配 → 检查 SKILL.md 激活条件 → 环境可用性检查 → 注入工具 例用户说帮我查服务器状态 → 匹配 服务器监控 Skill → 检查 SSH 连接是否可用 → 可用 → 注入工具Agent 执行 → 不可用 → 提示用户配置 SSH3.6 个性化层——SOUL.mdSOUL.md 是 Agent 的灵魂内核定义核心价值观和行为准则。# SOUL.md 示例 ## 核心价值观 - 真诚帮助不敷衍 - 有主见敢说这个方案有问题 - 主动解决问题不等用户追问 ## 语气 - 简洁直接不说废话 - 专业但不刻板 - 偶尔幽默但不油嘴滑舌 ## 边界 - 拒绝讨好型 AI行为 - 不确定的事情标注不确定 - 敏感操作必须确认 ## 隐私保护 - 不主动记忆密码、密钥 - 用户要求遗忘的内容立即删除设计哲学避免 Agent 沦为冷冰冰的执行器也不是无底线的谄媚者而是一个有原则的助手。3.7 持久化层——会话与记忆双层存储架构┌─────────────────────────────────────────┐ │ 会话存储Sessions │ │ │ │ sessions.json ← 会话元信息索引 │ │ *.jsonl ← 追加写的树状事件日志 │ │ 支持会话分支 │ │ 支持压缩前落盘 │ │ 避免长任务上下文丢失 │ └─────────────────────────────────────────┘ ┌─────────────────────────────────────────┐ │ 记忆存储Memory │ │ │ │ MEMORY.md ← 长期记忆 │ │ 关键决策、用户偏好、重要结论│ │ 跨会话持久保留 │ │ │ │ memory/YYYY-MM-DD.md ← 短期记忆日志 │ │ 每天的上下文日志 │ │ 仅追加不修改 │ │ 会话开始时读取当天昨天 │ └─────────────────────────────────────────┘记忆生命周期Day 1: Agent 工作 → 事件写入 2026-05-20.jsonl实时 关键信息 → 追加到 memory/2026-05-20.md短期 重要决策 → 写入 MEMORY.md长期 Day 2: 新会话启动 → 加载 MEMORY.md 昨日今日日志 继续工作 → ... Day 7: 旧日志被归档或丢弃 Agent 启动时只加载 MEMORY.md上下文压缩Compaction上下文接近模型阈值时 Step 1: Memory Flush 强制 Agent 将关键状态写入硬盘文件 ↓ Step 2: 压缩总结 对上下文进行摘要压缩 ↓ Step 3: 继续运行 压缩后的上下文 持久化文件 无损继续 关键先落盘再压缩确保长任务不因上下文修剪丢失关键信息3.8 安全层——护栏与可观测性致命三要素要素说明不受信的输入Agent 连接互联网读取网页、邮件和帖子工具访问权限Agent 拥有 Shell 访问权、文件读写权自主行动能力Heartbeat 允许无人类实时审核下执行操作三者的组合构成“提示词注入 → 行动注入”攻击链。护栏机制┌──────────────────────────────────────────────────────┐ │ 1. 沙箱化Sandboxing │ │ Docker 容器隔离宿主机文件系统 │ │ │ │ 2. 网络白名单 │ │ 限制 Agent 只访问特定域名或 API 端点 │ │ │ │ 3. 权限最小化Least Privilege │ │ 专用 OS 用户只赋予必要权限 │ │ │ │ 4. Compaction Safeguard压缩保护 │ │ 更稳的 token 预算工具失败/文件操作的必要摘要 │ │ 避免压缩把执行语义压坏 │ │ │ │ 5. Context Pruning可控上下文修剪 │ │ 基于缓存 TTL 的修剪策略防止上下文无限膨胀 │ │ │ │ 6. 渐进式信任与确认 │ │ 敏感操作删文件/发邮件/转账→ IM 确认请求 │ │ 复杂操作 → 预演模式Dry Run展示计划变更列表 │ └──────────────────────────────────────────────────────┘可观测性Observability机制说明透明日志每一次 LLM 思考、工具调用及参数、系统返回结果都记录在案自省能力用户可问你刚才做了什么Agent 读取自己的日志摘要解释心跳报告定期状态汇报即使无事发生证明守护进程存活审计追踪完整的 Chain of Thought → Tool Call → Tool Output 记录历史安全教训CVE严重性问题CVE-2026-32046CVSS 9.9沙盒浏览器--no-sandbox标志禁用 Chromium OS 级保护CVE-2026-32048权限提升跨 Agent 会话生成时沙盒配置未正确继承到子进程核心教训不安全的默认配置、复杂的权限继承逻辑缺陷、插件供应链风险——三者在拥有系统级控制能力的框架中被放大到极致。四、7 个 Markdown 配置文件OpenClaw 的全部状态和规则由 7 个 Markdown 文件定义~/.openclaw/workspace/ ├── AGENTS.md ← Agent 操作手册行为规范、工具使用、安全规则 ├── BOOTSTRAP.md ← 首次启动引导完成后可删除 ├── HEARTBEAT.md ← 定时任务配置Cron 式周期性任务 ├── IDENTITY.md ← Agent 身份证名称、类型、风格、头像 ├── SOUL.md ← 灵魂内核价值观、语气、边界 ├── TOOLS.md ← 工具配置本地可调用工具的具体参数 └── USER.md ← 用户档案背景、偏好、项目各文件详解文件作用关键内容AGENTS.mdAgent 的操作手册行为规范、会话流程、内存管理策略、安全规则、群聊参与原则、工具使用说明、心跳机制配置BOOTSTRAP.md首次启动引导与用户对话确定 Agent 身份名称、性格、风格、表情符号更新 IDENTITY.md 和 USER.md完成后可删HEARTBEAT.md定时任务清单每 N 小时检查服务器、每天早上推送天气、每周一汇报日志等 Cron 式任务IDENTITY.mdAgent 身份证名称、类型、风格、表情符号、头像路径——定义 Agent 的外在标识SOUL.md灵魂内核核心价值观、行为准则、语气风格、边界定义、隐私保护——拒绝讨好型 AITOOLS.md工具配置本地可调用工具的具体参数、运行环境等——环境特定的配置USER.md用户档案用户基本信息、关心事项、项目背景、操作偏好——帮助 Agent 精准理解和服务用户五、端到端消息流从用户输入到结果返回Phase 1: Ingestion消息摄入 WhatsApp 用户发送帮我检查服务器状态 ↓ Channel Adapter 标准化消息格式 提取附件 ↓ Phase 2: Access Control Routing访问控制与路由 Gateway 验证权限 → 路由到对应 Agent 实例 ↓ 分配专属 Channel 命令队列 ↓ Phase 3: Context Assembly上下文组装 加载会话历史 MEMORY.md 当日日志 SOUL.md AGENTS.md ↓ 匹配 Skill意图匹配 → 服务器监控 Skill 激活 ↓ 注入工具SSH 工具 诊断脚本 ↓ Phase 4: Model Invocation模型调用 组装完整提示词 → 发送给 LLM ↓ LLM 判断需要调用工具 → 返回工具调用指令 ↓ Phase 5: Tool Execution工具执行 执行 SSH 命令 → 获取服务器状态 ↓ 结果返回给 LLM → LLM 分析并生成摘要 ↓ 如需多步执行循环 Phase 4-5默认上限 20 次 ↓ Phase 6: Response Delivery响应交付 Gateway 将结果通过原 Channel 回传 WhatsApp ↓ 全量会话数据持久化到 .jsonl 文件六、Pi 引擎集成完整的调用链// 主入口runEmbeddedPiAgent({sessionId:user-123,sessionKey:main:whatsapp:1234567890,sessionFile:/path/to/session.jsonl,workspaceDir:/path/to/workspace,config:openclawConfig,prompt:Hello, how are you?,provider:anthropic,model:claude-sonnet-4-6,timeoutMs:120_000,onBlockReply:async(payload){awaitsendToChannel(payload.text,payload.mediaUrls);},})用户消息 ↓ runEmbeddedPiAgent() ← 主入口 ↓ runEmbeddedAttempt() ↓ createAgentSession() ← Pi SDK 核心创建会话 ├── DefaultResourceLoader ← 加载扩展 ├── SessionManager ← 会话持久化JSONL ├── AuthStorage ← 多账号轮换 ├── ModelRegistry ← 模型解析 └── customTools ← OpenClaw 全量工具注入 ↓ applySystemPromptOverride() ← 动态系统提示 ↓ session.prompt() ← 发送提示SDK 驱动完整 Agent loop ↓ subscribeEmbeddedPiSession() ← 事件回调流式/工具/压缩等 ↓ onBlockReply() ← 输出到渠道关键集成参数参数说明sessionId会话唯一标识sessionKey会话路由键格式main:渠道:账号sessionFileJSONL 持久化文件路径workspaceDirAgent 工作空间目录configOpenClaw 配置对象provider模型提供商anthropic/openai/deepseek 等model具体模型名称timeoutMs单次运行超时时间onBlockReply流式回调用于向 IM 渠道输出响应七、五大设计亮点亮点 1记忆机制——混合检索 上下文管理短期记忆memory/YYYY-MM-DD.md ↓ 每日追加 ↓ 会话开始自动读取当天昨天 长期记忆MEMORY.md ↓ 关键决策、用户偏好、重要结论 ↓ 跨会话持久保留 混合检索 ↓ 向量检索 关键词匹配 ↓ 快速精准调取相关记忆 上下文压缩 ↓ 接近阈值时 Memory Flush → 先落盘再压缩 ↓ 确保长任务不丢失关键信息亮点 2本地系统操作能力能力技术实现亮点Shell 命令exec 工具支持沙箱/本地/远程三种环境兼顾灵活性和安全性文件系统读写编辑各类格式文件本地文件自动化管理浏览器基于 Playwright语义快照Semantic Snapshot文本表征 50KB截图 5MB节省 Token进程管理创建、终止本地进程全流程自动化亮点 3插件可扩展性extensions/ 目录下自动扫描加载 四大扩展方向 ├── 渠道插件Channel Plugin → 添加新聊天平台 ├── 记忆插件Memory Plugin → 换存储后端如向量数据库 ├── 工具插件Tool Plugin → 添加自定义能力 └── 模型提供商插件Provider → 接入自定义 AI 模型亮点 4心跳机制——主动自治被动响应 → 主动自治 每 4 小时 → 检查服务器状态 每天 8:00 → 推送天气 日程提醒 每周一 → 汇报上周工作摘要 → 7×24 数字员工亮点 5多 Agent 路由不同渠道 → 不同 Agent → 不同人设 不同模型 不同工具权限 Discord Bot → Claude Sonnet友好版主风格 Telegram 私聊 → GPT-4正式客服语气 CLI 命令行 → 共享工作空间完整权限八、ima.copilot 中的映射ima.copilot 基于 OpenClaw 框架构建核心概念一一对应OpenClaw 原版ima.copilot 版本作用SOUL.mdsoul_mdAgent 人设、语气、行为规则MEMORY.mdmemory_md持久化事实与决策AGENTS.mdagents_md工具执行偏好与模式USER.mduser_md用户档案SKILL.mdSkill 系统use_skill技能加载与执行HEARTBEAT.md—暂无对应定时任务IDENTITY.md—集成在 soul_mdAgent 身份Channel Adapters多端客户端PC/Web/小程序消息交互Gatewayima 后端服务会话路由与编排Pi Engine混元大模型 工具执行循环推理与执行.jsonl transcriptqa层会话上下文会话持久化memory/YYYY-MM-DD.mddaily层日摘要短期记忆九、与 Hermes 的定位对比维度OpenClawHermes Agent核心定位自动化运行时 / 个人 AI 操作系统自我进化的 AI Agent 框架设计哲学网关优先确定性编排强调控制与可预测Agent 优先自主性学习强调进化与适应性核心能力700 插件生态、多平台消息网关、企业级策略控制闭环学习循环、自主技能生成、GEPA 提示词进化技能系统静态/手动社区或人工编写安装后固定不变动态/自动生成Agent 从经验中创建并优化技能记忆模型基于文件的持久记忆结构化配置四层混合记忆SQLite Markdown Honcho跨会话语义搜索一句话给 AI 套缰绳给 AI 装神经系统ima.copilot OpenClaw 的骨架 Hermes 类型的进化能力 WeKnora 的知识检索层十、总结OpenClaw 的简单不是功能少而是分层清晰——IM 把交互变简单Pi 把引擎做小做稳Gateway 把路由做集中可控SKILL.md 把能力扩展变成写文档Markdown 文件把 Agent 状态变成人可读、可编辑的配置会话树 两层持久化 压缩前落盘 护栏扩展把长期运行从玄学变成机制