Clawdbot 个人 AI 助手 Gateway 架构技术分析

一、概述

1. 项目简介

Clawdbot 是一个开源的个人 AI 助手平台，采用本地优先的架构设计，允许用户在自己的设备上运行完全可控的 AI 助手。项目由 Peter Steinberger 发起，采用 MIT 许可证发布。

2. 核心特性

• 本地优先的 Gateway 控制平面
• 多通道消息支持（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams、Matrix、Zalo、WebChat 等）
• 多 Agent 路由与会话隔离
• 语音唤醒和对话模式（支持 macOS/iOS/Android）
• 实时 Canvas 可视化工作区
• 浏览器自动化控制
• Docker 沙箱安全隔离
• 跨平台支持（macOS、Linux、Windows WSL2、iOS、Android）

二、系统架构

1. 整体设计

Clawdbot 采用中心化的 Gateway 控制平面架构，所有组件通过 WebSocket 连接到 Gateway 进行通信。

graph TB
    subgraph 通信层
        WA[WhatsApp]
        TG[Telegram]
        SL[Slack]
        DS[Discord]
        SI[Signal]
        IM[iMessage]
        MT[Teams]
        MX[Matrix]
        WC[WebChat]
    end

    subgraph 控制平面
        GW[Gateway WebSocket<br/>ws://127.0.0.1:18789]
    end

    subgraph 执行层
        AG[Pi Agent Runtime]
        CLI[CLI Interface]
        UI[WebChat UI]
    end

    subgraph 设备节点
        MAC[macOS App]
        IOS[iOS Node]
        AND[Android Node]
    end

    subgraph 工具层
        BR[Browser Control]
        CV[Canvas]
        CR[Cron]
        WH[Webhooks]
    end

    WA --> GW
    TG --> GW
    SL --> GW
    DS --> GW
    SI --> GW
    IM --> GW
    MT --> GW
    MX --> GW
    WC --> GW

    GW --> AG
    GW --> CLI
    GW --> UI
    GW --> MAC
    GW --> IOS
    GW --> AND

    AG --> BR
    AG --> CV
    AG --> CR
    GW --> WH

2. 核心组件

A. Gateway（控制平面）

Gateway 是 Clawdbot 的核心组件，提供统一的 WebSocket 控制平面，负责：

• 会话管理（sessions）
• 通道路由（channel routing）
• 工具调度（tool orchestration）
• 事件分发（event dispatch）
• 配置管理（configuration）
• 定时任务（cron scheduling）
• Webhook 处理

B. Pi Agent Runtime

采用 RPC 模式运行的 AI Agent 运行时，支持：

• 工具流式传输（tool streaming）
• 块流式传输（block streaming）
• 会话隔离（session isolation）
• 思考级别控制（thinking levels）

C. 通道适配器

支持多种消息平台的适配器，每个适配器负责：

• 平台特定的消息协议处理
• 媒体文件处理（图片、音频、视频）
• 群组路由规则
• 私聊策略（pairing/open）

三、会话模型

1. 会话类型

Clawdbot 采用灵活的会话模型：

• main 会话：直接对话，拥有完整工具访问权限
• 群组会话：隔离的会话环境，可配置沙箱模式
• 工作区会话：支持多 Agent 并行工作

2. 激活模式

stateDiagram-v2
    [*] --> Inactive
    Inactive --> Mention: 群组中被提及
    Inactive --> Always: 始终激活模式
    Mention --> Processing: 处理消息
    Always --> Processing: 接收消息
    Processing --> Idle: 处理完成
    Idle --> Inactive: 超时
    Idle --> Processing: 新消息

3. Agent-to-Agent 协调

Clawdbot 提供独特的会话间通信机制：

• sessions_list：发现活跃的 Agent 会话
• sessions_history：获取会话历史记录
• sessions_send：向其他会话发送消息

这种设计允许多个 Agent 协同工作，无需在聊天界面之间切换。

四、安全模型

1. 默认安全策略

Clawdbot 对入站 DM 采用默认拒绝策略：

• dmPolicy=pairing：未知发送者需要配对码
• 配对后添加到本地白名单
• 公开入站需要显式 opt-in

2. 沙箱隔离

对于非 main 会话（群组/公开通道），支持 Docker 沙箱：

• per-session Docker 容器
• allowlist：bash、process、read、write、edit、sessions_* 工具
• denylist：browser、canvas、nodes、cron、discord、gateway

3. 权限管理

macOS 应用通过 Gateway 协议暴露 TCC 权限：

• system.run：需要屏幕录制权限
• system.notify：需要通知权限
• camera.*、screen.record：遵循 TCC 权限状态

五、部署架构

1. 本地部署

推荐配置：Gateway 运行在用户设备上

• 运行时要求：Node.js >= 22
• 安装方式：npm install -g clawdbot@latest
• 后台服务：launchd（macOS）/systemd（Linux）

2. 远程部署

Gateway 可以运行在小型 Linux 实例上：

• 客户端通过 Tailscale Serve/Funnel 连接
• 或通过 SSH 隧道访问
• 设备节点（macOS/iOS/Android）仍可执行本地操作

graph LR
    subgraph 远程服务器
        RG[Remote Gateway]
    end

    subgraph 本地设备
        MAC[macOS Client]
        IOS[iOS Node]
        AND[Android Node]
    end

    subgraph 网络层
        TS[Tailscale VPN]
        SSH[SSH Tunnel]
    end

    MAC -->|WebSocket| TS
    IOS -->|Pairing| TS
    AND -->|Pairing| TS
    TS --> RG
    SSH --> RG

3. Tailscale 集成

Clawdbot 原生支持 Tailscale 网络暴露：

• Serve 模式：tailnet-only HTTPS
• Funnel 模式：公共 HTTPS（需要密码认证）
• Gateway 绑定 loopback，通过 Tailscale 代理

六、工具系统

1. 内置工具

Clawdbot 提供丰富的内置工具：

2. 技能平台

支持三类技能：

• Bundled Skills：内置技能
• Managed Skills：托管技能
• Workspace Skills：用户自定义技能（~/clawd/skills/）

七、技术栈

1. 后端技术

• 运行时：Node.js >= 22
• 包管理：npm/pnpm/bun
• 语言：TypeScript
• WebSocket：自定义协议
• 浏览器控制：Chrome DevTools Protocol

2. 平台适配

3. 通道实现

八、配置管理

1. 最小配置

{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  }
}

2. 通道配置示例

Telegram 配置

{
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF",
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

浏览器配置

{
  "browser": {
    "enabled": true,
    "controlUrl": "http://127.0.0.1:18791",
    "color": "#FF4500"
  }
}

九、开发工作流

1. 从源码构建

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm ui:build
pnpm build
pnpm clawdbot onboard --install-daemon

2. 开发循环

pnpm gateway:watch  # 自动重载

3. 子模块初始化（如需构建应用）

git submodule update --init --recursive
./scripts/restart-mac.sh

十、特色功能

1. Voice Wake + Talk Mode

支持 macOS/iOS/Android 的语音唤醒和持续对话：

• Always-on speech（通过 ElevenLabs）
• Push-to-Talk overlay
• 唤醒词触发转发

2. Live Canvas

Agent 驱动的可视化工作区：

• A2UI（Agent-to-User Interface）
• 实时 Canvas 渲染
• 快照和评估功能

3. Companion Apps

• macOS 菜单栏应用：Gateway 控制、Voice Wake、WebChat
• iOS 节点：Canvas、Voice Wake、相机、屏幕录制
• Android 节点：Canvas、Talk Mode、相机、屏幕捕获

十一、运维与监控

1. 健康检查

clawdbot doctor

2. 日志管理

支持结构化日志和调试输出。

3. Gateway Lock

防止多实例冲突的锁机制。

十二、生态与社区

1. 技能注册中心

ClawdHub 提供技能发现和自动安装功能。

2. 贡献者

项目拥有超过 200 名贡献者，采用 AI/vibe-coding 友好的贡献政策。

3. 文档资源

• 架构概览
• 配置参考
• 安全指南
• 故障排除
• 平台特定指南

十三、适用场景

1. 个人生产力

• 多平台消息统一入口
• 自动化任务执行
• 信息检索和整理

2. 开发者工具

• 代码审查辅助
• 自动化测试
• 文档生成

3. 隐私优先场景

• 本地运行，数据不出设备
• 完全可控的 AI 助手
• 支持离线操作（部分功能）

十四、技术亮点

1. 统一控制平面

通过单一 WebSocket 接口管理所有组件，简化了架构复杂度。

2. 会话隔离

群组会话与主会话隔离，支持细粒度的权限控制。

3. Agent 协同

sessions_* 工具支持 Agent 间直接通信，实现多 Agent 协作。

4. 跨平台节点

设备节点可以配对到远程 Gateway，实现分布式执行。

5. 安全第一

默认 DM 配对策略、Docker 沙箱、TCC 权限管理等多层安全机制。

参考资料

1. Clawdbot GitHub 仓库
2. Clawdbot 官方文档