OpenClaw — 开源个人 AI 助手架构分析

发表于 更新于 分类于

OpenClaw — 开源个人 AI 助手架构分析

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 配置、模型配置、渠道绑定和设备配对。