Version: 2026.5.7 | 基于源码 + 官方文档梳理
一句话理解
OpenClaw = 多通道 AI 网关 + 嵌入式 Agent 运行时。它不是"套壳聊天机器人"，而是一个能对接多种 IM 平台、运行多个 AI 模型、支持插件扩展的 agent 基础设施。
1. 顶层架构
┌──────────────────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ Channel │ │ Agent │ │ Plugin │ │
│ │ Layer │ │ Runtime │ │ System │ │
│ │ │ │ (Pi/Codex) │ │ │ │
│ │ WhatsApp ───┤ │ │ │ Provider Plugins ──────┤ │
│ │ Telegram ───┤ │ ┌────────┐ │ │ Channel Plugins ──────┤ │
│ │ Discord ────┤ │ │ Agent │ │ │ Context Engine ───────┤ │
│ │ Signal ─────┤ │ │ Loop │ │ │ Memory Plugins ───────┤ │
│ │ Slack ──────┤ │ └────────┘ │ │ Hook Plugins ─────────┤ │
│ │ ... ────────┤ │ ┌────────┐ │ └────────────────────────┘ │
│ │ │ │ │ Tools │ │ │
│ │ │ │ └────────┘ │ │
│ └─────────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ WebSocket Protocol (port 18789) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ▲ ▲ ▲ │
│ │ │ │ │
│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │
│ │ CLI │ │ macOS │ │ Nodes │ │
│ │ openclaw│ │ App │ │ (iOS, │ │
│ │ │ │ Web UI │ │ Android)│ │
│ └─────────┘ └─────────┘ └─────────┘ │
└──────────────────────────────────────────────────────────────────┘
核心设计原则
| 原则 | 说明 |
|---|---|
| 唯一 Gateway | 每台机器一个 Gateway 进程，管理所有消息通道 |
| 设备即节点 | 手机/电脑通过 WebSocket 连接 Gateway，有独立的 cap |
| 插件即能力边界 | 每个公司/功能一个插件，注册到中心 registry |
| 会话隔离 | 按 channel + peer 路由到独立 session，避免上下文污染 |
| 纯 HTTP/gRPC 无关 | 内部不走 HTTP，使用 WebSocket 双向流 + 嵌入调用 |
2. 核心概念分层
┌─────────────────────────────────────────────────────────────┐
│ CHANNEL LAYER（通道层） │
│ 负责消息收发，每个 channel 是一个 im 平台的对接实现 │
│ │
│ WhatsApp ── Baileys ── openclaw-weixin ── etc. │
│ │
├─────────────────────────────────────────────────────────────┤
│ SESSION LAYER（会话层） │
│ 会话路由、身份链接、channel docking、权限控制 │
│ session.key ──> agentId ──> session file (.jsonl) │
│ │
├─────────────────────────────────────────────────────────────┤
│ AGENT LAYER（Agent 层） │
│ 智能体运行时（Pi / Codex / Claude CLI） │
│ agent loop：context → model → tools → reply │
│ │
├─────────────────────────────────────────────────────────────┤
│ PLUGIN LAYER（插件层） │
│ 插件注册中心 + hook 系统 + provider 抽象 │
│ 扩展：模型、通道、记忆、工具、TTS、搜索... │
│ │
├─────────────────────────────────────────────────────────────┤
│ MODEL LAYER（模型层） │
│ 模型发现、provider 路由、failover、thinking 策略 │
│ openai / anthropic / deepseek / ollama / codex / ... │
└─────────────────────────────────────────────────────────────┘
3. Agent Loop（核心执行流程）
这是每次用户消息触发一次 agent 运行的完整流程：
Inbound Message
│
▼
┌─────────────────┐
│ Queue │ ← 会话队列（per-session serialized）
│ (steer/followup │
│ /collect) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Session │ ← 解析/创建 session 上下文
│ Resolution │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Context │ ← Context Engine 组装消息
│ Assembly │ memory 注入、token 预算裁剪
└────────┬────────┘
│
▼
┌─────────────────┐
│ System Prompt │ ← AGENTS.md + SOUL.md + 技能注入
│ Build │ 插件 hooks (before_prompt_build)
└────────┬────────┘
│
▼
┌─────────────────┐
│ Model │ ← provider 解析 → API 调用 → 流式输出
│ Inference │ (思考 / 工具调用 / 回答)
└────────┬────────┘
│
▼
┌─────────────────┐
│ Tool │ ← 执行工具(read/write/exec/...)
│ Execution │ 插件 hooks (before/after_tool_call)
└────────┬────────┘
│
(循环直到模型返回最终回答)
│
▼
┌─────────────────┐
│ Reply │ ← 构建最终回复、写入 session 文件
│ Delivery │ 通过 channel 返回给用户
└────────┬────────┘
│
▼
┌─────────────────┐
│ After Turn │ ← Context Engine afterTurn
│ Persist │ 可能触发 compaction
└─────────────────┘
关键设计
- 序列化执行：每个 session 同一时刻只有一个 run 在执行，通过 session key 做 lane-aware 队列
- 全局并发控制：
agents.defaults.maxConcurrent默认 4，防止 LLM 调用打满 - 队列模式：
steer：在当前 run 间隙注入新消息（默认）followup：排队等当前 run 结束后处理collect：静默窗口内合并多条为一次处理interrupt：终止当前 run 直接处理最新消息
- 超时体系：agent 级别超时（48h）、model 空闲超时（120s）、wait 超时（30s）
4. 插件系统架构
插件加载流程
启动阶段：
┌─────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐
│ 发现 │──▶│ 验证 │──▶│ 加载 │──▶│ 注册 │
│ (manifest│ │ (enable/ │ │ (require/ │ │ (register │
│ + path) │ │ deny) │ │ Jiti) │ │ API) │
└─────────┘ └───────────┘ └──────────┘ └───────────┘
│
▼
┌───────────────┐
│ Plugin │
│ Registry │
│ (中心注册表) │
└───────┬───────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌─────────┐ ┌───────────┐ ┌───────────┐
│ Provider │ │ Channel │ │ Hooks / │
│ Catalog │ │ Registry │ │ Tools │
└─────────┘ └───────────┘ └───────────┘
注册能力类型
| 注册方法 | 能力 | 示例插件 |
|---|---|---|
registerProvider() |
文本推理 | openai, anthropic |
registerCliBackend() |
CLI 推理后端 | claude-cli |
registerChannel() |
消息通道 | discord, telegram, signal |
registerSpeechProvider() |
TTS 语音合成 | elevenlabs, microsoft |
registerMediaUnderstandingProvider() |
图片/音频/视频理解 | openai, google, qwen |
registerImageGenerationProvider() |
图片生成 | openai, fal, minimax |
registerVideoGenerationProvider() |
视频生成 | qwen, runway |
registerWebSearchProvider() |
网络搜索 | google, tavily, exa |
registerWebFetchProvider() |
网页抓取 | firecrawl |
registerContextEngine() |
上下文引擎 | lossless-claw |
Hook 系统
Plugin 可以在 Agent Loop 的各个生命周期插入回调：
| Hook 点 | 时机 | 用途 |
|---|---|---|
before_model_resolve |
模型解析前 | 强制指定 provider/model |
before_prompt_build |
构建 prompt 前 | 注入 system context |
before_agent_reply |
LLM 调用前 | 拦截回复（silence 或合成回复） |
before_tool_call |
工具调用前 | 拦截/修改工具参数 |
after_tool_call |
工具调用后 | 检查/修改工具结果 |
tool_result_persist |
工具结果写入 session 前 | 转换/过滤工具输出 |
agent_end |
agent 运行结束 | 检查最终消息列表 |
message_received |
收到消息时 | 预处理器 |
message_sending |
发送消息前 | 取消/修改出站消息 |
session_start / session_end |
会话生命周期 | 初始化/清理 |
5. 多 Agent 架构
┌──────────────────────────────────────────────────────────┐
│ Gateway │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ Agent: main │ │ Agent: delegate │ │
│ │ │ │ │ │
│ │ workspace: ~/wksp │ │ workspace: ~/wksp- │ │
│ │ │ │ delegate │ │
│ │ auth-profiles.json │ │ auth-profiles.json │ │
│ │ sessions/ │ │ sessions/ │ │
│ └────────┬───────────┘ └────────┬───────────┘ │
│ │ │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌────────┴────────┐ │
│ │ Agent Routing │ │
│ │ (Bindings) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌──────────────────┼──────────────────┐ │
│ ▼ ▼ ▼ │
│ Discord Account WhatsApp Account Signal Account │
└──────────────────────────────────────────────────────────┘
每个 Agent 有自己的：
- workspace：prompt 文件（AGENTS.md / SOUL.md / USER.md）
- agentDir：auth profiles、模型注册
- sessions：会话历史
通过 bindings 规则将通道账号路由到对应 Agent。
6. 模型层架构
Agent Loop 决定模型后：
Model Ref: "openai/gpt-5.5"
│
▼
┌──────────────────────────────────────┐
│ Provider Resolution │
│ │
│ 1. normalizeModelId (别名归一化) │
│ 2. normalizeTransport (API/BaseURL) │
│ 3. normalizeConfig (配置归一化) │
│ 4. resolveDynamicModel (动态发现) │
│ 5. prepareRuntimeAuth (令牌交换) │
└──────────────┬───────────────────────┘
│
▼
┌──────────────────────────────────────┐
│ Inference Loop │
│ │
│ ┌─────────┐ ┌──────────┐ ┌──────┐ │
│ │ prepare │─▶│ stream │─▶│ wrap │ │
│ │ExtraParams│ │ Function│ │Stream│ │
│ └─────────┘ └──────────┘ └──────┘ │
│ │
│ Provider 可替换整条路径： │
│ - wrapStreamFn → 自定义流处理 │
│ - createStreamFn → 完全替换传输层 │
└──────────────────────────────────────┘
模型 failover
openai/gpt-5.5 ── 调用失败 ──▶ 自动重试 ──▶ 达到次数 ──▶ failover 到备用模型
│
▼
anthropic/claude-4
模型 failover 通过 models.failover 配置，可以指定备用模型列表。
7. Context Engine 架构（上下文引擎）
Session Messages (JSONL)
│
▼
┌──────────────────────────────────┐
│ Context Engine │
│ │
│ ingest(): 新消息进来时索引 │
│ │
│ assemble(): 每次 run 前组装上下文 │
│ ├── tokenBudget 裁剪 │
│ ├── memory 检索注入 │
│ └── systemPromptAddition │
│ │
│ compact(): 上下文超预算时压缩 │
│ afterTurn(): run 完成后的后处理 │
│ │
│ (可选) │
│ prepareSubagentSpawn() │
│ onSubagentEnded() │
└──────────────────────────────────┘
│
▼
Assembled Messages → Model Prompt
Context Engine 是可插拔的：内置 legacy 引擎 vs 插件引擎（如 lossless-claw）。
8. WebSocket 协议
Gateway 对外使用 WebSocket 做控制面通信（非 HTTP REST），所有客户端（CLI、mac 应用、Web UI、Node 设备）都通过 WS 连接。
连接生命周期:
Client Gateway
│ │
├── req: connect ──────────▶│ (携带 deviceId + challenge 签名)
│◀───────── res: hello-ok ─┤ (返回 session snapshot)
│ │
│ <--- 正常通信 ---> │
│ │
├── req: agent ────────────▶│ (触发 Agent Run)
│◀─── res: ack (runId) ────┤
│◀─── event: agent (stream)┤ (流式输出 assistant/tool 事件)
│◀─── res: agent (final) ──┤ (最终结果)
│ │
├── req: send ─────────────▶│ (发送消息)
│◀─── res: send ───────────┤
│ │
│◀─── event: heartbeat ────┤ (定时心跳)
│◀─── event: presence ─────┤ (在线状态变化)
│ │
├── req: health ───────────▶│
│◀─── res: health ─────────┤
协议帧格式
// 请求
{ type: "req", id: "<uuid>", method: "agent" | "send" | "health" | ..., params: {...} }
// 响应
{ type: "res", id: "<uuid>", ok: true, payload: {...} }
{ type: "res", id: "<uuid>", ok: false, error: {...} }
// 事件（服务端推送）
{ type: "event", event: "agent" | "presence" | "health" | "heartbeat", payload: {...}, seq: n }
9. 目录结构一览
/ (项目根)
├── openclaw.mjs # CLI 入口
├── package.json # 主包（仅 CLI + 基础依赖）
├── dist/ # 编译产物（67MB）
│ ├── openclaw-root-*.js # 核心运行时
│ ├── openclaw-runtime-*.js # 运行时层
│ ├── openclaw-tools-*.js # 工具系统
│ ├── openclaw.plugin-*.js # 插件系统
│ ├── openclaw-exec-*.js # 执行环境
│ └── ... (chunked bundler 产物)
├── extensions/ # 插件目录（140+ 插件）
│ ├── openai/ # OpenAI 全家桶（推理、TTS、图片、视频）
│ ├── anthropic/ # Anthropic 模型
│ ├── google/ # Google 全家桶
│ ├── discord/ # Discord 通道
│ ├── telegram/ # Telegram 通道
│ ├── whatsapp/ # WhatsApp 通道（Baileys）
│ ├── signal/ # Signal 通道
│ ├── feishu/ # 飞书通道
│ ├── voice-call/ # 语音通话
│ ├── memory-core/ # 记忆系统
│ ├── memory-lancedb/ # LanceDB 记忆
│ ├── context-engine/ # 上下文引擎（如 lossless-claw）
│ ├── video-generation-core/ # 视频生成能力契约
│ ├── speech-core/ # TTS 能力契约
│ ├── agent-tools/ # 自定义工具
│ ├── hooks/ # 各种 hook 插件
│ └── ... (140+ 子目录)
├── patches/ # npm 补丁
│ ├── @agentclientprotocol__claude-agent-acp@0.32.0.patch
│ └── @whiskeysockets__baileys@7.0.0-rc.9.patch
├── docs/ # 文档
│ ├── concepts/ # 核心概念
│ ├── gateway/ # Gateway 配置
│ ├── plugins/ # 插件文档
│ ├── channels/ # 通道文档
│ └── ...
└── skills/ # 内置技能（含 bot-harness 等）
10. 数据流全景（一次完整对话）
User ──▶ WhatsApp ──▶ Gateway (Channel Layer)
│
▼
┌───────────────────┐
│ Queue (steer mode) │ ← 队列调度
└───────────────────┘
│
▼
┌───────────────────┐
│ Session Resolution │ ← 路由到哪个 Agent
└───────────────────┘
│
▼
┌──────────────────────┐
│ Context Engine │
│ - ingest(session) │
│ - assemble(token limit)│
│ - memory retrieval │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ System Prompt Build │
│ - AGENTS.md + SOUL.md │
│ - Skills injection │
│ - Plugin hooks │
└──────────────────────┘
│
▼
┌──────────────────────┐
│ Model Provider │
│ - resolve provider │
│ - prepare auth │
│ - stream inference │
└──────────────────────┘
│ │
tool call text delta
│ │
▼ ▼
┌────────┐ ┌──────────┐
│ Tool │ │ Assistant│
│ Exec │ │ Stream │
└────────┘ └──────────┘
│ │
▼ ▼
┌──────────────────────┐
│ Reply Pipeline │
│ - build final reply │
│ - suppress duplicates │
│ - TTS if configured │
└──────────────────────┘
│
▼
Channel Layer → WhatsApp → User
11. 关键技术选择
| 技术 | 选择 | 理由 |
|---|---|---|
| 运行时 | Node.js | 生态丰富、插件开发门槛低 |
| 内部通信 | WebSocket | 双向流、比 HTTP REST 更适合 agent 场景 |
| 包管理 | esbuild (打包) | 将整个项目打包为 chunked bundle |
| 插件架构 | 进程中加载 | 低延迟、共享内存 |
| 消息队列 | 内存 FIFO | 无外部依赖、足够轻量 |
| 会话存储 | JSONL 文件 | 简单可靠、人类可读 |
| 模型推理 | 多 provider | 不绑定单一 API，支持 failover |
| 通道对接 | 全插件化 | 140+ 插件，覆盖主流 IM |
| AI Agent 运行时 | pi-agent-core | 自研嵌入式 agent loop |
| 代码生成 Agent | Codex 集成 | 支持 ChatGPT/Codex 作为运行时 |
12. 思维模型
把 OpenClaw 想象成：
📨 收件 🧠 思考 📤 发件
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
│ 信箱集群 │ │ 大脑（Agent） │ │ 发送器 │
│ │ │ │ │ │
│ WhatsApp ─────┤ │ ┌────────────┐ │ ├──── Telegram │
│ Telegram ──── │ ─────▶ │ │ AGENTS.md │ │ ─────▶ ├──── Discord │
│ Discord ──────┤ │ │ SOUL.md │ │ ├──── Signal │
│ ... ──────────┤ │ │ mem / 技能 │ │ └──────────────┘
└──────────────┘ │ └────────────┘ │
│ │
│ Plugin 插件 = 可 │
│ 拼装的工具箱 │
└──────────────────┘
关键洞察：
- Gateway 不是聊天机器人框架，而是 agent 基础设施：它解决的是"消息怎么进来、怎么路由、怎么执行、怎么出去"的问题
- 插件 = 能力边界：每个公司/服务一个插件，core 只定义契约
- Pi Agent Runtime = 自研 agent loop：不依赖任何外部服务做推理循环
- 进程内插件：插件和 core 共享进程空间（高性能但需要信任插件）
- WebSocket 控制面：不搞 HTTP/2 或 gRPC，WS 足够表达 agent 的双向流需求
这份文档基于 OpenClaw v2026.5.7 源码和官方文档梳理，对于学习架构是一个很好的起点。