OpenClaw — 架构分析

发表于 更新于 分类于

OpenClaw — 架构分析

OpenClaw 是一个自托管的开源个人 AI 助手，核心定位是一个 Multi-Channel AI Gateway——将 LLM 能力通过统一的控制面分发到 WhatsApp、Telegram、Slack、Discord、iMessage 等 20+ 消息平台，并支持 macOS/iOS/Android 原生应用和 Web UI。

仓库: https://github.com/openclaw/openclaw · 版本: 2026.3.14 · 许可: MIT

项目演进路径: Warelay → Clawdbot → Moltbot → OpenClaw

一、架构概览

OpenClaw 采用 Gateway 中心化 + 插件化扩展 的架构模式。核心是一个 WebSocket/HTTP 控制面，周围挂载渠道连接器、Agent 运行时、插件系统和各种工具：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
消息接入层（WhatsApp / Telegram / Slack / Discord / iMessage / LINE / Feishu / 等 20+ 渠道）
         │
         ▼
┌──────────────────────────────────────────┐
│           Gateway 控制面                  │
│  · WebSocket 18789 端口                   │
│  · HTTP API（Hono + Express）             │
│  · ACP（Agent Client Protocol）            │
│  · 会话管理 / 消息路由                     │
│  · Cron 任务调度 / Webhook                 │
└──────────────────────────────────────────┘
         │
         ├── Pi Agent Runtime（多模型编排，工具调用，流式响应）
         ├── CLI + TUI（终端控制）
         ├── macOS / iOS / Android 原生应用
         └── Web UI（Lit 组件）

核心设计理念

  1. 多模型支撑 —— 支持 OpenAI、Gemini、Claude、Mistral、Ollama 等主流模型，Auth Profile 支持轮转和故障回退
  2. 渠道无关 —— 消息通过统一协议处理，渠道扩展通过插件 SDK 开发，无需改动核心
  3. 安全优先 —— DM 配对、可执行审批、敏感工具检测、内容扫描、SSRF 保护、Secrets 管理
  4. 可自托管 —— 单机部署，Docker 支持，macOS/Linux daemon 管理

二、分层架构详解

1. 接入层（Channels / Extensions）

每个消息平台作为一个独立 npm 包注册在 extensions/ 目录下，通过 Plugin SDK 接入。SDK 提供统一接口：消息收发、媒体处理、打字指示器、Presence 等。

当前支持的渠道覆盖了主流 IM（WhatsApp、Telegram、Discord、Slack、Signal、iMessage、LINE、Feishu、Teams、Matrix、IRC 等）和 WebChat。iOS/Android/macOS 原生 App 还提供语音唤醒（Voice Wake）、Canvas 画布、Screen Recording 等设备侧能力。

2. 网关层（Gateway）

Gateway 是系统的控制平面，基于 WebSocket 实现双向实时通信。主要职责：

  • 会话管理 —— 连接绑定、Session Key 路由、消息溯源
  • 协议层 —— ACP（Agent Client Protocol）定义了 Agent 间通信的标准
  • 认证与配对 —— DM 配对：Code-based 设备授权，无需暴露端口
  • 速率控制 —— Lane 管理，限制并发，防止滥用
  • 路由分发 —— 将消息路由到合适的 Agent Runtime 实例

3. 运行时层（Agent Runtime）

Pi Agent 是 OpenClaw 的核心推理引擎（@mariozechner/pi-agent-core 系包）。支持的功能：

  • 多模型编排 —— Auth Profile 级别的模型切换、失败自动回退
  • Tool Calling —— 通过 MCP（Model Context Protocol）调用浏览器、Sandbox、系统命令等
  • Streaming —— 流式 Token 输出和 Block Streaming
  • 记忆系统 —— Embedding Pipeline（支持 OpenAI / Gemini / Mistral / Voyage / Ollama 多种向量模型），SQLite Vector Store，MMR 检索，Query Expansion
  • Canvas 画布 —— Agent 驱动的可视化工作区
  • Browser Automation —— Chrome CDP 集成，Profile 管理，Sandbox 隔离

4. 插件系统（Plugin SDK）

OpenClaw 提供了完整的插件生命周期管理：

  • 插件生命周期：安装 → 启用 → 配置 → 启动 → 停止
  • 插件可以扩展：HTTP 路由、消息处理、技能、工具、Provider
  • 社区插件通过 ClawHub 分发（clawhub.ai）

5. 安全层

  • DM 配对 —— 设备间 Code-based 授权
  • Exec Approval —— 危险命令操作需要人工确认
  • Secrets 管理 —— 凭证审计、配置、计划、运行时收集
  • 内容扫描 —— 入站/出站内容安全过滤
  • SSRF 防护 —— 防止服务器端请求伪造

三、关键模块速览

模块 位置 行数规模 职责
Gateway src/gateway/ ~240 文件 WebSocket/HTTP 控制面、协议、路由
Agent 运行时 src/agents/ ~550 文件 Pi Agent 集成、模型路由、工具调用
配置系统 src/config/ ~210 文件 YAML/JSON 配置、Zod 校验、Env 替代
基础设施 src/infra/ ~390 文件 Dotenv、端口检测、重试/退避、设备配对
记忆系统 src/memory/ ~100 文件 Embedding Pipeline、向量检索、Session 文件
浏览器自动化 src/browser/ ~140 文件 CDP 控制、快照、Profile、MCP Bridge
Cron 调度 src/cron/ ~70 文件 定时任务、Session 清理、心跳通知
Plugin SDK src/plugin-sdk/ ~110 文件 扩展开发接口、渠道适配器
命令层 src/commands/ ~300 文件 80+ CLI 命令实现
TUI src/tui/ ~30 文件 终端用户界面
后台服务 src/daemon/ ~50 文件 systemd / launchd / schtasks 管理

四、技术栈

层次 技术
语言 TypeScript (ES2023, NodeNext)
Node 最低 ≥ 22
包管理 pnpm Workspace Monorepo
Web 框架 Hono + Express
通信 WebSocket (ws)、ACP 协议
数据库 / 向量 SQLite (+ sqlite-vec vector extension)
浏览器自动化 Playwright Core (CDP)
媒体处理 Sharp (图片)、pdfjs-dist (PDF)、node-edge-tts (TTS)
构建 tsdown、tsc
格式/检查 oxlint、oxfmt
测试 Vitest（单元/集成/E2E 多配置）
工具 MCP（Model Context Protocol）、mcporter Bridge

五、与业界方案对比

维度 OpenClaw LangChain Agent OpenAI Assistants API
定位 个人助手 Gateway 开发框架 托管 API
渠道接入 20+ 消息平台内置 无 无
部署方式 自托管 / Docker 需自己搭建 完全托管
多模型 原生支持 通过 Provider 支持 仅 OpenAI
插件机制 全生命周期插件 通过 LCEL 组合 无
安全 DM 配对 + 审批 + 审计 无内置 基础 IAM
设备端 macOS/iOS/Android 原生 无 无

六、适用场景与设计取舍

OpenClaw 最适合 个人或小团队 自建 AI 助手，统一管理多平台的 AI 交互。它的设计做了一个明确的取舍：

优势：

  • 一接入，所有渠道都能 AI 回复
  • 数据完全自控，隐私有保障
  • 配置灵活，Plugin 系统可定制性强

代价：

  • 单机架构，水平扩展能力有限
  • Agent 能力依赖于配置的模型
  • 社区驱动，某些渠道的稳定性依赖插件维护方

七、本地体验

OpenClaw 提供了非常完善的 Onboarding 流程：

1
2
3
npm install -g openclaw@latest
openclaw onboard --install-daemon
openclaw gateway --port 18789 --verbose

安装后可以通过 CLI、TUI、Web UI、原生 App 或任意已绑定的消息渠道与 AI 交互。Onboarding Wizard 会用交互式引导完成 Gateway 配置、模型配置、渠道绑定和设备配对。

八、事件系统

OpenClaw 没有使用通用的 EventBus 或 EventEmitter，而是设计了 5 种各自独立、最小化的事件机制，每种服务于不同的范围与用途：

事件系统 文件 范围 持久化 用途
System Events src/infra/system-events.ts 按 session 分桶 内存（最多20条） Agent 上下文注入 — 将通知/exec完成/凭证事件等前缀到下次 prompt
Diagnostic Events src/infra/diagnostic-events.ts 进程级单例 内存 监控与日志 — token 用量、webhook 生命周期、session 状态、工具循环检测
Agent Events src/infra/agent-events.ts 按 runId 内存 实时执行流 — lifecycle/tool/assistant/error 四类 stream，用于控制 UI 展示
Heartbeat Events src/infra/heartbeat-events.ts 进程级 内存存最新 心跳状态 — 发送状态/耗时/沉默标记，用于 UI 指示灯
Gateway Node Events src/gateway/server-node-events.ts Gateway↔节点 不持久 移动端/远端节点 — voice transcript/agent request/notification/exec 事件双向通信

Agent Events 广播为什么不撑爆内存

createAgentEventHandler() (src/gateway/server-chat.ts) 将 Agent Events 转换为 chat (delta/final) 广播给所有 WS 客户端和订阅节点，但有多层保护：

  1. dropIfSlow 背压 (src/gateway/server-broadcast.ts) — 客户端 bufferedAmount > 50MB 时跳过发送，持续慢速则断开连接
  2. 150ms delta 节流 — 每个 clientRunId 每150ms最多广播一次，防止 token 级高频推送
  3. run 结束时确定性清理 — lifecycle end/error 时立即 buffers.delete + deltaSentAt.delete，不累积
  4. 定时回收 — agentRunSeq 上限 10k 条，abortedRuns 1h TTL，维护定时器每分钟扫描
  5. 空订阅跳过 — 无节点订阅的 session 完全不序列化和发送

这些保护非一次性设计，而是在 2026年1月至6月间逐步演进 加入的（从最初的 bufferedAmount 断开，到 dropIfSlow 跳过、delta 节流、精确清理、慢客户端主动断开）。

九、队列与池机制

OpenClaw 没有通用连接池（channel 连接由各插件自管），但有 5 种职责明确的队列/池：

1. Command Lane（命令车道）

src/process/command-queue.ts — 最核心的任务执行池，控制 agent 并发度。每个 Lane 是 FIFO 队列 + 可配置并发上限。

Lane 用途 默认并发
Main 主 agent 执行 由 resolveAgentMaxConcurrent 决定
Cron 定时任务 由 cron.maxConcurrentRuns 决定
Subagent 子 agent 由 resolveSubagentMaxConcurrent 决定
Nested 嵌套执行 —

2. Followup Queue

src/auto-reply/reply/queue/ — session 忙时的消息缓存队列。

  • 模式: steer（默认排队）、followup、collect（合并）、interrupt（中断当前）
  • 丢弃策略: old（丢弃最旧）、new（丢弃最新）、summarize（丢弃并生成摘要给 agent）
  • 去重: 按 message-id 或 prompt 去重（5分钟窗口）

3. Delivery Queue（持久化投递）

src/infra/outbound/delivery-queue.ts — 出站消息的可靠投递，支持崩溃恢复。

  • 基于文件系统（~/.openclaw/state/delivery-queue/）
  • 指数退避: 5s → 25s → 2min → 10min，最多重试5次
  • 双阶段确认: {id}.json → rename {id}.delivered → unlink，崩溃不重复投递
  • 启动时扫描恢复未投递消息

4. Session Actor Queue

src/acp/control-plane/session-actor-queue.ts — ACP 控制平面的按 key 串行化队列，同一 session 的任务串行执行，不同 session 可并行。

5. 完整消息流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
Channel Webhook → Reply Dispatcher → [Session Busy?]
                                       │
                          ┌────────────┼────────────┐
                          ▼            ▼            ▼
                      Run Now    Followup Queue  Drop/Debounce
                          │
                          ▼
                    Command Lane (Main/Subagent)
                          │
                          ▼
                    Pi Agent Runtime (LLM loop)
                          │
                          ▼
                    Reply Dispatcher (tool/block/final)
                          │
                          ▼
                    Delivery Queue (持久化, 崩溃恢复, 指数退避)
                          │
                          ▼
                    Channel Send (Telegram/Discord/等)

十、并发控制

OpenClaw 的并发控制分为多个层面，通过配置文件（openclaw config / openclaw.yaml / openclaw.json）管理。

1. Agent 并发（最核心）

控制 主 Agent 和 子 Agent（subagent） 同时处理多少个消息/任务。

配置路径 说明 默认值
agents.defaults.maxConcurrent 主 Agent 同时处理的最大消息数 4
agents.defaults.subagents.maxConcurrent 子 Agent 同时运行的最大并发数 8

示例配置：

1
2
3
4
5
agents:
  defaults:
    maxConcurrent: 2          # 主 agent 最多同时处理 2 个消息
    subagents:
      maxConcurrent: 4        # 子 agent 最多同时跑 4 个

底层机制： src/process/command-queue.ts 中有一个 in-process 队列（lane 机制），分 main、subagent、cron、nested 四条 lane。每条 lane 独立控制并发数，超出的请求会排队等待，不会丢弃。Gateway 启动和配置热重载时（src/gateway/server-lanes.ts / src/gateway/server-reload-handlers.ts）会调用 setCommandLaneConcurrency 更新 lane 并发上限。

2. Cron 任务并发

配置路径 说明 默认值
cron.maxConcurrentRuns Cron 定时任务同时运行数 1 
1
2
cron:
  maxConcurrentRuns: 2   # 允许同时跑多个 cron 任务

3. ACP 会话并发

配置路径 说明
acp.maxConcurrentSessions 跨 gateway 的 ACP 会话最大并发数 
1
2
acp:
  maxConcurrentSessions: 8

4. 消息广播并发

当使用广播（Broadcast）功能同时向多个目标发送消息时，可以控制是并行还是串行：

1
2
broadcast:
  strategy: parallel   # "parallel"（并行，默认）或 "sequential"（串行）
  • parallel：同时发送给所有目标，速度更快
  • sequential：逐个发送，更严格的顺序和背压控制

5. 媒体处理并发

配置路径 说明 适用场景
tools.media.concurrency 每轮对话中图像/音频/视频理解的最大并发数 资源受限环境可调低，防止 CPU/网络过载 
1
2
3
tools:
  media:
    concurrency: 3

6. 通道级并发（Discord 等）

以 Discord 为例，可以在通道配置中单独控制事件队列的并发：

1
2
3
4
5
6
7
channels:
  discord:
    accounts:
      - id: "your-bot-id"
        eventQueue:
          maxConcurrency: 10   # Discord 事件处理并发
          maxQueueSize: 1000   # 队列容量

7. Gateway 认证速率限制

Gateway 开放端口对外服务时的暴力破解防护：

1
2
3
4
5
6
7
gateway:
  auth:
    rateLimit:
      maxAttempts: 10       # 窗口内最大尝试次数
      windowMs: 60000       # 时间窗口（毫秒）
      lockoutMs: 300000     # 锁定时间
      exemptLoopback: true  # 回环地址是否豁免

当 gateway.bind 不是 loopback 时，安全审计（src/security/audit.ts）会强制要求配置该限流否则发出警告。

8. 出站消息重试与背压

出站队列（Delivery Queue）有内置的指数退避重试机制：

  • 位于 src/infra/outbound/delivery-queue.ts
  • 退避序列: 5s → 25s → 2min → 10min → 10min
  • 最多重试 5 次，超限标记为 failed
  • 基于文件系统持久化，崩溃重启后扫描恢复未投递消息

9. 推荐策略

场景 建议
生产环境（多频道） 保持 maxConcurrent: 4，根据 LLM API 配额适当调低
资源有限（树莓派/低配 VPS） maxConcurrent: 1-2，tools.media.concurrency: 1
高吞吐场景 适当调高 subagents.maxConcurrent: 16，留意 provider 速率限制
Gateway 暴露公网 必须配置 gateway.auth.rateLimit

热加载： 运行中修改配置文件后，OpenClaw 会自动通过 server-reload-handlers.ts 重载 lane 并发数，无需重启进程。