核心定位：OpenClaw = 自动化运行时（Automation Runtime），一个给 AI 套上安全、可控、可审计缰绳的框架。
它不追求 AI 的"惊喜"，而是追求可预测性、可审计性和零故障。

---

一、设计哲学：网关优先，核心极小

OpenClaw 遵循两条底层信念：

信念	含义
网关优先（Gateway-First）	所有流量、控制流、策略执行都经过中央 Gateway，确定性编排，强调控制与可预测
核心极小（Minimal Core）	Pi 引擎只保留最少的底层原语（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 软件当作唯一 UI，Agent 就像通讯录里的一个联系人。

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-Spoke）

WhatsApp / 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 引擎的会话生命周期、事件流、权限边界、工具注入的全面控制
存在感知（Presence）	Agent 在线状态管理
配置热更新	无需重启即可更新配置
Cron 定时任务	调度心跳任务
Webhook 触发	外部事件驱动的任务启动
设备配对认证	新设备接入时的安全认证

基于通道（Channel）的命令队列

关键设计：每个会话都有专属执行通道，保证操作有序进行。

传统问题：async/await 异步嵌套 → 状态冲突、调试困难
OpenClaw 方案：Channel-based 命令队列，默认序列化执行

  Channel A（WhatsApp 私聊）→ 串行队列 → Agent 1
  Channel B（Discord 群组） → 串行队列 → Agent 2
  Channel C（CLI 命令行）   → 串行队列 → Agent 1

  低风险、可并行的任务可显式声明并行运行 → 兼顾有序性和效率

---

3.3 核心引擎层——Pi Engine

Pi 是 OpenClaw 的"心脏"——提供模型抽象、流式推理、Agent Loop、工具执行等底层机制。

Pi 提供的是"通用引擎"——让系统能跑起来；
OpenClaw 负责的是"车身和交通规则"——让系统跑得久、跑得稳。

Pi 的极简主义

核心能力收敛到极少原语：
  Read    → 读取文件
  Write   → 写入文件
  Edit    → 编辑文件
  Bash    → 执行命令

少而硬、可控、可复用。

嵌入式 SDK 集成（非 RPC/子进程）

// ❌ 不会这样做（子进程）
import { spawn } from "child_process";
spawn("pi", ["run", ...]);

// ❌ 也不会这样做（RPC）
fetch("http://localhost:3000/rpc", { method: "POST", ... });

// ✅ 实际做法：直接导入并实例化
import { createAgentSession } from "@earendil-works/pi-coding-agent";
const { session } = await createAgentSession({ ... });

工具注入机制（关键）

OpenClaw 不会沿用 Pi 自带工具再加点料，而是：

Step 1: 清空 Pi 的 built-in tools
Step 2: 用 customTools 注入 OpenClaw 的整套工具链

// 伪代码示例
pi_session = createAgentSession();
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    → 高级 SDK：createAgentSession、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 A（Claude Sonnet，友好版主风格，开放社区工具）
Telegram 私聊 → Agent B（GPT-4，正式客服语气，限制文件访问）
CLI 命令行    → Agent A（共享工作空间，完整工具权限）

每个 Agent 实例拥有：
  ├── 独立工作空间
  ├── 独立会话历史
  ├── 独立模型配置
  └── 独立行为设定

混合架构路由 & 成本优化

简单任务（闲聊/查询）→ 轻量模型（DeepSeek/Haiku）→ 低成本
复杂任务（编码/分析）→ 旗舰模型（Claude/GPT-4）   → 高质量

高流量场景自动启动备用模型，保证服务稳定性

---

3.5 能力层——Skills System

OpenClaw 最核心的竞争力：用 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、浏览器控制
Managed	ClawHub 社区技能，搜索安装	GitHub 管理、邮件助手、智能家居
Workspace	用户自定义技能	针对特定业务流程的自动化

agentskills.io 标准

agentskills.io 是 OpenClaw 和 Hermes 共同遵循的技能标准

技能包结构：
  my-skill/
  ├── SKILL.md          ← 技能说明（入口）
  ├── manifest.json     ← 元数据（版本、依赖、权限）
  └── scripts/          ← 可执行脚本
      └── main.sh

条件激活策略

用户消息 → 意图匹配 → 检查 SKILL.md 激活条件 → 环境可用性检查 → 注入工具

  例：用户说"帮我查服务器状态"
      → 匹配 "服务器监控" Skill
      → 检查 SSH 连接是否可用
      → 可用 → 注入工具，Agent 执行
      → 不可用 → 提示用户配置 SSH

---

3.6 个性化层——SOUL.md

SOUL.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-32046	CVSS 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.md	Agent 的操作手册	行为规范、会话流程、内存管理策略、安全规则、群聊参与原则、工具使用说明、心跳机制配置
BOOTSTRAP.md	首次启动引导	与用户对话确定 Agent 身份（名称、性格、风格、表情符号），更新 IDENTITY.md 和 USER.md，完成后可删
HEARTBEAT.md	定时任务清单	每 N 小时检查服务器、每天早上推送天气、每周一汇报日志等 Cron 式任务
IDENTITY.md	Agent 身份证	名称、类型、风格、表情符号、头像路径——定义 Agent 的外在标识
SOUL.md	灵魂内核	核心价值观、行为准则、语气风格、边界定义、隐私保护——拒绝"讨好型 AI"
TOOLS.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) => {
    await sendToChannel(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:渠道:账号）
sessionFile	JSONL 持久化文件路径
workspaceDir	Agent 工作空间目录
config	OpenClaw 配置对象
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.md	soul_md	Agent 人设、语气、行为规则
MEMORY.md	memory_md	持久化事实与决策
AGENTS.md	agents_md	工具执行偏好与模式
USER.md	user_md	用户档案
SKILL.md	Skill 系统（use_skill）	技能加载与执行
HEARTBEAT.md	—（暂无对应）	定时任务
IDENTITY.md	—（集成在 soul_md）	Agent 身份
Channel Adapters	多端客户端（PC/Web/小程序）	消息交互
Gateway	ima 后端服务	会话路由与编排
Pi Engine	混元大模型 + 工具执行循环	推理与执行
.jsonl transcript	qa 层（会话上下文）	会话持久化
memory/YYYY-MM-DD.md	daily 层（日摘要）	短期记忆

---

九、与 Hermes 的定位对比

维度	OpenClaw	Hermes 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 状态变成人可读、可编辑的配置
• 会话树 + 两层持久化 + 压缩前落盘 + 护栏扩展
• 把"长期运行"从玄学变成机制