OpenClaw 系统架构分析

带你深入了解OpenClaw的架构和核心流程。

1. 架构概述

OpenClaw 采用插件化的 Gateway 控制平面架构，结合多渠道消息系统和跨平台客户端应用，构建了一个完整的个人 AI 助手生态系统。

核心架构特征

1. Gateway 控制平面: 单一 WebSocket 服务器管理所有会话、渠道和事件
2. 多渠道消息系统: 统一抽象层支持 15+ 消息平台
3. 插件化扩展: Monorepo 架构下的独立插件包
4. 跨平台客户端: CLI + macOS App + iOS/Android 节点
5. AI 代理引擎: 基于 Pi Agent 的 RPC 模式代理
6. 本地优先设计: 数据和会话本地存储，隐私可控

2. 整体架构模式

2.1 架构分类

OpenClaw 结合了多种架构模式：

2.2 架构层次

3. 核心组件

3.1 Gateway 控制平面

职责: 整个系统的核心控制器

功能:

• WebSocket 服务器 (ws://localhost:18789)
• JSON-RPC 2.0 方法调度 (70+ 方法，8 个命名空间)
• 多层认证系统 (off/local-only/token/tailscale/tailscale-local)
• 作用域授权 (admin/read/write/approvals/pairing)
• 会话生命周期管理
• 多代理路由和隔离
• 实时事件广播和去重
• Canvas 宿主服务
• Cron 定时任务调度
• 配置热重载

技术实现:

• 语言: TypeScript
• 框架: Fastify + ws
• 协议: JSON-RPC 2.0
• 位置: src/gateway/

关键文件:

• src/gateway/server.impl.ts - Gateway 主入口和 WebSocket 服务器
• src/gateway/server-methods.ts - 方法调度和授权系统
• src/gateway/server-chat.ts - Chat 会话管理
• src/gateway/server-broadcast.ts - 事件广播系统
• src/gateway/auth.ts - 多层认证系统
• src/gateway/server-methods/ - 32+ 方法处理器模块

3.2 渠道系统

职责: 连接各个消息平台，提供统一消息接口

核心渠道 (src/ 目录):

• src/channels/ - 渠道通用逻辑
• 内置频道 (9个): telegram, discord, slack, signal, whatsapp, imessage, web, line, acp

扩展渠道 (extensions/ 目录):

• extensions/telegram/ - Telegram 扩展
• extensions/discord/ - Discord 扩展
• extensions/slack/ - Slack 扩展
• extensions/whatsapp/ - WhatsApp 扩展
• extensions/msteams/ - Microsoft Teams
• extensions/matrix/ - Matrix
• extensions/googlechat/ - Google Chat
• extensions/bluebubbles/ - BlueBubbles
• extensions/zalo/ - Zalo
• extensions/zalouser/ - Zalo Personal
• extensions/line/ - LINE
• extensions/tlon/ - Tlon
• extensions/twitch/ - Twitch
• extensions/nostr/ - Nostr
• extensions/nextcloud-talk/ - Nextcloud Talk
• extensions/mattermost/ - Mattermost

统一接口:

interfaceChannel{start():Promise<void>stop():Promise<void>sendMessage(target:string, content:string):Promise<void>onMessage(handler: MessageHandler):voidgetStatus(): ChannelStatus }

3.3 消息路由系统

职责: 将收到的消息路由到正确的代理和会话

功能:

• 渠道识别 (WhatsApp/Telegram/etc.)
• 对等方识别 (用户 ID/群组 ID)
• 代理路由 (多代理隔离)
• 6 级路由优先级: peer > guild > team > account > channel > default
• 7 级配置匹配: 精确 > 空间 > 账户通配符 > 账户 > 频道通配符 > 频道 > 全局
• 会话激活 (peer/guild/team/account/channel/global)
• 多层访问控制:
  • Allowlist 白名单过滤
  • Mention Gating (群组提及门控)
  • Command Gating (控制命令授权)
• 群组逻辑 (提及门控/回复标签)

技术实现:

• 位置: src/routing/
• 关键文件:
  • src/routing/resolve-route.ts - 主路由器 (resolveAgentRoute)
  • src/channels/channel-config.ts - 7级配置匹配
  • src/channels/command-gating.ts - 控制命令授权
  • src/channels/mention-gating.ts - 群组消息过滤

3.4 安全与配对系统

职责: 保护系统免受未授权访问

功能:

• DM 配对模式 (默认拒绝)
• 配对码生成和验证
• 白名单管理
• 访问控制列表 (ACL)
• 配置安全检查 (Doctor 工具)

技术实现:

• 位置: src/pairing/, src/security/
• 存储: ~/.clawdbot/pairing/ (JSON 文件)

配对流程:

1. 未知用户发送消息 2. 系统生成短配对码 (例: ABC123) 3. 回复包含配对码 4. 管理员运行: openclaw pairing approve <channel> ABC123 5. 用户添加到白名单 6. 后续消息正常处理 

3.5 AI 代理引擎

职责: 处理用户消息，生成 AI 响应

功能:

• 多模型支持 (Anthropic/OpenAI/Bedrock/Ollama)
• 嵌入式运行模式 (runEmbeddedPiAgent)
• 双车道排队系统:
  • sessionLane: 单会话串行执行
  • globalLane: 全局并发控制
• Auth Profile 轮转: 30 分钟冷却，自动切换认证配置
• Thinking Level 降级: high → low → off 故障转移
• 上下文溢出处理: 自动压缩和修剪
• 工具调用 (browser/canvas/cron/etc.)
• 块流式输出
• 会话上下文管理
• 多重尝试和错误恢复

技术实现:

• 核心: @mariozechner/pi-agent-core
• 位置: src/agents/pi-embedded-runner/
• 关键文件:
  • run.ts - 核心编排逻辑 (runEmbeddedPiAgent)
  • run/attempt.ts - 单次执行尝试
  • pi-embedded-subscribe.ts - 流式事件订阅
  • pi-tools.ts - 工具创建 (createOpenClawCodingTools)

支持的工具:

• Browser (playwright)
• Canvas (A2UI)
• Cron (定时任务)
• System (macOS 命令)
• Media (图像/音频/视频)
• Memory (向量存储)

3.6 会话管理系统

职责: 管理多代理、多渠道的会话状态

功能:

• 会话创建和销毁
• 上下文持久化 (JSONL 格式)
• 会话隔离 (main/group/)
• 会话激活模式
• 会话队列模式

技术实现:

• 位置: src/sessions/
• 存储: ~/.clawdbot/sessions/ 或 ~/.clawdbot/agents/<id>/sessions/
• 格式: JSON (完整对象，包含 key + meta + history + version)
• 权限: 0o600 (仅所有者可读写)

会话作用域 (SessionScope):

• peer: 对等方会话 (1对1 直接对话)
• guild: 服务器/群组会话
• team: 团队会话
• account: 账户会话
• channel: 频道默认会话
• global: 全局会话
• custom: 自定义作用域 (任意字符串)

3.7 媒体处理管道

职责: 处理图像、音频、视频、文档

功能:

• 图像:
  • 压缩和转换 (Sharp)
  • 尺寸限制
  • 格式转换 (PNG/JPEG/WebP)
• 音频:
  • 转码
  • 语音转文字 (转录钩子)
  • TTS 合成
• 视频:
  • 转码
  • 时长和尺寸限制
• PDF:
  • 提取文本
  • 渲染页面
• 文档:
  • DOCX 预览
  • 文本提取

技术实现:

• 位置: src/media/, src/media-understanding/
• 依赖: sharp, pdfjs-dist, node-edge-tts

3.8 浏览器工具

职责: 提供无头浏览器自动化能力

功能:

• 网页导航
• 截图
• PDF 生成
• DOM 操作
• JavaScript 执行

技术实现:

• 引擎: Playwright (Chromium)
• 位置: src/browser/
• 沙箱: multi-agent-sandbox-tools

3.9 Canvas 系统

职责: 提供代理驱动的可视化界面

功能:

• A2UI 协议 (Agent-to-UI)
• 实时 WebSocket 更新
• 多平台支持 (macOS/iOS/Android)
• 组件渲染
• 代理控制

技术实现:

• 宿主: src/canvas-host/
• A2UI: src/canvas-host/a2ui/
• 打包: scripts/bundle-a2ui.sh

3.10 语音交互系统

职责: 支持语音输入和输出

功能:

• Voice Wake:
  • 语音唤醒 (macOS/iOS/Android)
  • 自定义唤醒词
  • 持续监听
• Talk Mode:
  • 语音对话
  • 推送通话 (PTT)
  • 覆盖层 UI
• TTS:
  • ElevenLabs 集成
  • 多语言支持

技术实现:

• TTS: src/tts/
• 依赖: node-edge-tts
• 客户端: apps/macos, apps/ios, apps/android

3.11 CLI 工具

职责: 提供命令行操作界面

命令:

• openclaw gateway - 启动/停止 Gateway
• openclaw agent - 与 AI 代理交互
• openclaw message send - 发送消息
• openclaw channels status - 渠道状态
• openclaw config - 配置管理
• openclaw onboard - 引导向导
• openclaw doctor - 诊断工具
• openclaw pairing - 配对管理

技术实现:

• 框架: Commander.js
• 位置: src/cli/, src/commands/
• 入口: openclaw.mjs

3.12 插件系统

职责: 支持渠道和功能的动态扩展

插件类型:

• 渠道插件: 扩展消息平台支持
• 工具插件: 扩展 AI 代理工具
• 内存插件: 扩展向量存储
• 诊断插件: 扩展监控能力

技术实现:

• SDK: src/plugin-sdk/
• 加载: src/plugins/
• 位置: extensions/

插件接口:

interfacePlugin{ name:string version:stringinit(context: PluginContext):Promise<void>destroy():Promise<void>}

3.13 配置管理

职责: 管理系统和用户配置

配置层级:

1. 默认配置 (内置)
2. 全局配置 (~/.clawdbot/config.yaml)
3. 项目配置 (openclaw.config.yaml)
4. 环境变量 (覆盖)

技术实现:

• 位置: src/config/
• 格式: JSON5 (支持注释和尾部逗号)
• 文件: ~/.openclaw/config.json
• 验证: Zod Schema
• 权限: 0o600 (仅所有者可读写)
• 工具: openclaw config

配置系统特性:

• $include 指令: 支持多文件合并
• 环境变量替换: ${VAR} 自动替换
• 原子性写入: 临时文件 + 重命名
• 备份轮转: 自动保留 3 个备份
• 遗留迁移: 自动迁移旧版配置
• 运行时覆盖: 临时修改不持久化
• 配置缓存: 可配置的内存缓存

关键配置:

{ "gateway": { "mode": "local", "port": 18789, "auth": { "mode": "token", "token": "${GATEWAY_TOKEN}" } }, "agents": { "defaults": { "model": "claude-sonnet-4-20250514", "thinking": "high", "maxConcurrent": 3 } }, "channels": { "defaults": { "dmPolicy": "allow", "groupPolicy": "allow-mentions" }, "telegram": { "botToken": "${TELEGRAM_BOT_TOKEN}" } } } 

3.14 跨平台应用

macOS 应用

职责: 菜单栏控制中心

功能:

• Gateway 启动/停止
• 渠道状态显示
• Voice Wake 控制
• Talk Mode 界面
• WebChat 嵌入
• Canvas 显示

技术:

• 语言: Swift
• 框架: SwiftUI
• 位置: apps/macos/

iOS 应用

职责: 移动节点和 Canvas 客户端

功能:

• Canvas 渲染
• Voice Wake
• Talk Mode
• 相机工具
• 屏幕录制
• Bonjour 配对

技术:

• 语言: Swift
• 框架: SwiftUI
• 位置: apps/ios/

Android 应用

职责: 移动节点和 Canvas 客户端

功能:

• Canvas 渲染
• Talk Mode
• 相机工具
• 屏幕录制
• 可选 SMS 集成

技术:

• 语言: Kotlin
• 框架: Jetpack Compose
• 位置: apps/android/

4. 数据流

4.1 消息接收流程

详细说明：

外部消息 → 渠道层 (WhatsApp/Telegram/etc.) → 频道元数据解析 (channelId, peerId, guildId) → 路由解析 (resolveAgentRoute) → 6 级路由优先级匹配 → 7 级配置匹配 → 多层访问控制检查 → Allowlist 白名单 → Mention Gating (群组) → Command Gating (控制命令) → 会话激活/创建 → SessionKey 解析 (agentId + scope + peerId) → 消息入队 (双车道) → sessionLane: 单会话串行 → globalLane: 全局并发控制 → Agent 执行 (runEmbeddedPiAgent) → Auth Profile 选择/轮转 → Thinking Level 应用 → 上下文溢出检查 → 工具调用 (如果需要) → 流式响应生成 → 响应处理 → 类型转换 (适配频道) → 分块发送 (长消息) → 重试机制 → 渠道发送 → 会话持久化 → 用户收到回复 

4.2 命令执行流程

CLI 命令 → Commander 解析 → 命令处理器 (commands/) → Gateway API (WebSocket/HTTP) → Gateway 处理 → 执行操作 → 返回结果 → CLI 显示 

4.3 Canvas 更新流程

AI 代理 → Canvas 工具调用 → Canvas 宿主 (gateway) → WebSocket 推送 → macOS/iOS/Android 客户端 → UI 渲染更新 

4.4 语音交互流程

用户语音 → Voice Wake 检测 (macOS/iOS/Android) → STT (语音转文字) → Gateway 消息 → AI 代理处理 → 响应生成 → TTS (文字转语音) → 用户听到回复 

5. 组件依赖关系

5.1 核心依赖

Gateway 控制平面 ├── WebSocket 服务器 (ws) ├── HTTP 服务器 (Fastify) ├── JSON-RPC 调度器 │ ├── 认证系统 (5种模式) │ ├── 授权系统 (5个作用域) │ └── 70+ 方法处理器 (8个命名空间) ├── 渠道系统 │ ├── 9 个内置频道 │ └── 15+ 扩展频道 ├── 路由系统 │ ├── 6 级路由优先级 │ ├── 7 级配置匹配 │ └── 多层访问控制 ├── Chat Run Registry ├── AI 代理引擎 │ ├── 双车道排队 (sessionLane + globalLane) │ ├── Pi Agent Core │ ├── Auth Profile 轮转 │ ├── 模型提供者 │ └── 工具注册表 ├── 广播管理器 ├── Canvas 宿主 └── Cron 调度 

5.2 客户端依赖

macOS/iOS/Android 应用 └── Gateway WebSocket ├── 连接管理 ├── 消息同步 ├── Canvas 更新 └── 状态订阅 

5.3 插件依赖

插件包 (extensions/) └── Plugin SDK ├── 插件接口 ├── 上下文访问 └── 生命周期钩子 

6. 外部集成

6.1 AI 模型提供者

• Anthropic: Claude (官方 API + OAuth)
• OpenAI: ChatGPT (官方 API + OAuth)
• AWS Bedrock: 多模型支持
• Ollama: 本地模型运行
• node-llama-cpp: 本地 LLM (可选)

6.2 消息平台

• WhatsApp: Baileys Web 协议
• Telegram: Bot API
• Slack: Bolt SDK
• Discord: Discord.js
• Google Chat: Chat API
• Signal: signal-cli
• iMessage: imsg/BlueBubbles
• Microsoft Teams: Bot Framework
• Matrix: Matrix SDK
• Zalo: Zalo API

6.3 语音服务

• ElevenLabs: TTS 合成 (node-edge-tts)
• 本地 STT: macOS/iOS/Android 系统 API

6.4 浏览器

• Chromium: Playwright 驱动
• BiDi: Chromium BiDi 协议

6.5 网络服务

• Bonjour: mDNS 服务发现 (@homebridge/ciao)
• Tailscale: (可选) 远程访问
• Fly.io: (可选) 远程部署

7. 部署架构

7.1 本地部署 (推荐)

┌─────────────────────────────────────┐ │ 用户设备 (macOS/Linux/Windows) │ │ │ │ ┌───────────────────────────────┐ │ │ │ Gateway 守护进程 │ │ │ │ (systemd/launchd) │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ macOS 菜单栏应用 (可选) │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Web 控制界面 │ │ │ │ http://localhost:18789 │ │ │ └───────────────────────────────┘ │ └─────────────────────────────────────┘ 

7.2 远程部署

┌─────────────────────────────────────┐ │ 云服务器 (VPS/Fly.io) │ │ │ │ ┌───────────────────────────────┐ │ │ │ Docker 容器 │ │ │ │ └── Gateway 服务 │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Nginx 反向代理 │ │ │ │ (HTTPS/WSS) │ │ │ └───────────────────────────────┘ │ └─────────────────────────────────────┘ ↓ WebSocket/HTTPS ┌─────────────────────────────────────┐ │ 用户设备 │ │ - iOS 节点 │ │ - Android 节点 │ │ - macOS 应用 │ └─────────────────────────────────────┘ 

7.3 Docker 部署

docker-compose.yml ├── gateway 服务 ├── 卷挂载 (配置/会话) └── 端口映射 (18789) 

8. 扩展性设计

8.1 水平扩展

• 插件系统: 独立 npm 包，按需安装
• 渠道扩展: 新渠道作为插件添加
• 工具扩展: 新工具通过 SDK 注册

8.2 垂直扩展

• 多代理: 每个代理独立进程
• 会话隔离: 多租户会话管理
• 资源限制: 可配置的并发和队列

8.3 未来扩展方向

• 分布式 Gateway (多节点)
• 集群会话同步
• 云端会话备份
• 企业级权限管理

9. 安全架构

9.1 认证和授权

• DM 配对: 默认拒绝未知 DM
• 白名单: 细粒度访问控制
• OAuth: AI 模型认证
• API Key: 备用认证方式

9.2 数据安全

• 本地存储: 会话和配置本地文件
• 加密传输: WebSocket + HTTPS
• 临时文件: 自动清理媒体缓存
• 隔离会话: 代理间完全隔离

9.3 风险防护

• 提示注入: 模型层防护
• 速率限制: 渠道节流 (throttler)
• Doctor 工具: 配置安全检查
• 沙箱隔离: 浏览器工具沙箱

10. 性能优化

10.1 缓存策略

• 媒体缓存: 临时文件系统
• 会话缓存: 内存 + 持久化
• 配置缓存: 热重载机制

10.2 并发控制

• 渠道节流: @grammyjs/transformer-throttler
• 队列模式: 会话级别排队
• 工具池: 浏览器实例复用

10.3 资源管理

• 自动清理: 临时文件生命周期
• 内存限制: 可配置的缓存大小
• 连接池: 数据库和 HTTP 连接

11. 监控和诊断

11.1 日志系统

• 分级日志: tslog (trace/debug/info/warn/error)
• 结构化日志: JSON 格式
• 日志轮转: 按日期归档

11.2 诊断工具

• Doctor 命令: openclaw doctor
  • 配置检查
  • 安全审计
  • 版本检查
  • 依赖验证
• 状态命令: openclaw channels status --deep
  • 渠道探测
  • 连接测试
  • API 可达性

11.3 可观测性 (可选)

• OpenTelemetry: diagnostics-otel 插件
• 指标收集: 自定义 metrics
• 追踪: 分布式追踪 (可选)

12. 总结

OpenClaw 的架构设计体现了以下核心理念：

1. 本地优先: 数据和隐私完全掌控
2. 插件化: 易于扩展和定制
3. 多渠道: 统一抽象，广泛兼容
4. 安全默认: 配对模式和白名单
5. 跨平台: CLI + 原生应用全覆盖
6. AI 驱动: 强大的代理引擎和工具生态

这种架构既保证了系统的灵活性和可扩展性，又确保了个人助手应有的隐私性和安全性，是一个成熟的、生产级的个人 AI 助手平台。

其他说明:
由于项目更新频繁，文中如提到clawbot/moltbot，更换成openclaw即可。