OpenClaw 系统架构分析

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

功能:

• 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

统一接口:

interface Channel {
  start(): Promise<void>
  stop(): Promise<void>
  sendMessage(target: string, content: string): Promise<void>
  onMessage(handler: MessageHandler): void
  getStatus(): 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/

插件接口:

interface Plugin {
  name: string
  version: string
  init(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 即可。