Loading... # 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 进行通信。 ```mermaid 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. 激活模式 ```mermaid 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）仍可执行本地操作 ```mermaid 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 提供丰富的内置工具： | 工具类别 | 工具名称 | 功能描述 | |---------|---------|---------| | 浏览器 | browser | Chrome/Chromium CDP 控制 | | 可视化 | canvas | A2UI 推送/重置/评估 | | 节点 | nodes.* | 相机、屏幕、位置、通知 | | 会话 | sessions_* | Agent 间通信协调 | | 系统 | system.run | 命令执行（需权限） | | 调度 | cron | 定时任务和唤醒 | | Webhook | webhooks | 外部触发集成 | ## 2. 技能平台 支持三类技能： - Bundled Skills：内置技能 - Managed Skills：托管技能 - Workspace Skills：用户自定义技能（~/clawd/skills/） # 七、技术栈 ## 1. 后端技术 - 运行时：Node.js >= 22 - 包管理：npm/pnpm/bun - 语言：TypeScript - WebSocket：自定义协议 - 浏览器控制：Chrome DevTools Protocol ## 2. 平台适配 | 平台 | 技术栈 | |------|--------| | macOS | Electron（菜单栏应用） | | iOS | Swift原生 | | Android | Kotlin/Java | | Linux | Node.js 服务 | | Windows | WSL2 | ## 3. 通道实现 | 通道 | 技术选型 | |------|---------| | WhatsApp | Baileys | | Telegram | grammY | | Slack | Bolt | | Discord | discord.js | | Signal | signal-cli | | iMessage | AppleScript（macOS） | # 八、配置管理 ## 1. 最小配置 ```json { "agent": { "model": "anthropic/claude-opus-4-5" } } ``` ## 2. 通道配置示例 ### Telegram 配置 ```json { "channels": { "telegram": { "botToken": "123456:ABCDEF", "groups": { "*": { "requireMention": true } } } } } ``` ### 浏览器配置 ```json { "browser": { "enabled": true, "controlUrl": "http://127.0.0.1:18791", "color": "#FF4500" } } ``` # 九、开发工作流 ## 1. 从源码构建 ```bash git clone https://github.com/clawdbot/clawdbot.git cd clawdbot pnpm install pnpm ui:build pnpm build pnpm clawdbot onboard --install-daemon ``` ## 2. 开发循环 ```bash pnpm gateway:watch # 自动重载 ``` ## 3. 子模块初始化（如需构建应用） ```bash 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. 健康检查 ```bash 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 仓库](https://github.com/clawdbot/clawdbot) 2. [Clawdbot 官方文档](https://docs.clawd.bot) 最后修改：2026 年 01 月 25 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏