Clawdbot：架构深度解析Clawdbot 不仅仅是一个问答机器人。它是一个AI 代理人，可以记住上下文，主动执行任

Clawdbot 不仅仅是一个问答机器人。它是一个AI 代理人，可以记住上下文，主动执行任务，像人类助理一样思考。它能阅读网页、控制你的电脑、自动化处理事务，从而真正代替你的双手与大脑

🌟 核心特性

🏠 私有化部署 · 彻底掌控

完全运行在你自己的设备上，无需依赖第三方服务，数据隐私得到保障。

💬 多通道统一

支持 15+ 主流消息平台，无需切换应用，在熟悉的聊天界面与 AI 对话。

🤖 强大能力

基于 Claude/GPT 等大模型，支持工具调用、代码执行、浏览器控制、设备操作，可通过WhatsApp、Telegram、Discord、Slack等你熟悉的聊天应用进行交互，让技术与日常生活无缝融合

🔐 企业级安全

配对机制、沙箱隔离、权限分层、DM 策略保护，适合团队使用。

🌐 灵活部署

支持本地/远程/混合部署模式，可通过 Tailscale/SSH 远程访问。

🔌 插件扩展

通道、工具、技能均可通过插件扩展，打造个性化的 AI 助手。

📊 项目统计

指标	数据
代码规模	~2500 TypeScript 文件，~70 Swift 文件
测试覆盖	70% (Vitest + V8 Coverage)
支持平台	macOS, Linux, Windows (WSL2), iOS, Android
支持通道	15+ 消息平台（核心 + 插件）
运行时要求	Node.js ≥22.12.0
开源协议	MIT License

🎬 适用场景

场景	描述	典型配置
个人助手	macOS/Linux 本地运行，通过 WhatsApp/Telegram 访问	单机部署 + 主会话
团队协作	远程服务器部署，多人通过群组访问	Linux Gateway + 沙箱隔离
开发调试	代码执行、浏览器控制、文件操作	全工具权限 + 本地 Canvas
移动办公	iOS/Android 设备作为 Node 暴露本地能力	设备配对 + Node 模式

💡 设计理念

单一 Gateway 原则: 一个主机只运行一个 Gateway 实例，拥有所有通道连接。
会话隔离: 主会话用于个人对话（信任），群组会话默认启用沙箱保护。
工具为中心: Agent 的能力完全由工具定义，内置工具 + 插件系统支持无限扩展。
流式优先: Agent 输出实时流式传输，工具执行也支持流式反馈。

1. 系统架构全景

Clawdbot 采用三层架构设计：通道层、控制层、执行层。各层职责清晰，通过标准接口通信。

整体架构图

图：展示 Clawdbot 的完整架构层次，从消息通道到 AI Agent 执行的全流程

架构说明：

消息通道层: 集成 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等平台
Gateway 控制平面: WebSocket Server、路由引擎、会话存储、安全认证、Canvas Host
Pi Agent 运行时: 队列管理、模型推理、工具执行、流式输出
工具执行层: 系统工具、浏览器控制、设备能力、通道操作

2. 组件架构图

核心组件关系

图：展示各核心组件之间的交互关系和数据流

组件说明：

Client 层: macOS App (SwiftUI)、Web UI (Lit.js)、iOS/Android 原生
Gateway 层: RPC Server、Session Manager、Router、Auth、Event Bus
Agent 层: Queue、LLM、Tools、Stream、Context
Storage 层: Sessions、Logs、Config、Credentials

3. Gateway 控制平面

Gateway 是 Clawdbot 的核心控制平面，负责通道管理、消息路由、会话存储和安全认证。

Gateway 架构

图：展示 Gateway 的内部架构和各模块职责

连接生命周期

图：从设备发现到建立连接的完整流程

连接步骤：

发现阶段: 客户端通过 mDNS/Bonjour 发现本地 Gateway
配对阶段: 生成配对 Token，扫描 QR 码完成配对
认证阶段: Token 验证，建立 WebSocket 连接
通信阶段: RPC 调用，双向消息传递

WebSocket RPC 协议

图：WebSocket RPC 请求-响应流程

RPC 特性：

基于 TypeBox 定义 Schema
JSON-RPC 2.0 风格
支持流式响应
自动重连机制

4. 消息流程图

端到端消息流

*图：从用户发送消息到 Agent 返回结果的完整流程*

流程步骤：

消息接收: 用户通过 WhatsApp/Telegram 等发送消息
通道解析: ChannelProvider 解析消息，提取文本/媒体
路由决策: Router 根据配置决定路由目标（主会话/群组/DM）
队列入队: 消息进入会话队列（主会话串行，群组并行）
Agent 执行: LLM 推理 + 工具调用
结果返回: 流式输出结果，回传到通道

5. Agent 执行循环

Pi Agent 是基于 @mariozechner/pi-agent-core 的智能代理运行时。

Agent 生命周期

图：Agent 的完整执行循环，包含上下文组装、LLM 推理、工具执行

循环步骤：

上下文组装: 系统提示 + 会话历史 + 工具定义
LLM 推理: 调用 Claude/GPT 等模型生成回复
工具调用: 解析工具调用请求，执行工具
结果反馈: 工具结果追加到上下文，继续推理
流式输出: 实时输出文本和工具事件

队列管理策略

图：主会话串行队列 vs 群组并行队列

队列策略：

主会话: 串行队列，保证对话连贯性
群组会话: 并行队列，每个群组独立
全局限流: 控制并发数，防止资源耗尽

6. 通道集成架构

Clawdbot 通过统一的 ChannelProvider 接口集成多个消息平台。

通道抽象层设计

🔌 抽象接口层

ChannelProvider 接口

interface ChannelProvider {
  // 通道名称
  name: string;
  
  // 启动通道连接
  start(): Promise<void>;
  
  // 停止通道连接
  stop(): Promise<void>;
  
  // 发送文本消息
  sendMessage(params: SendMessageParams): Promise<Result>;
  
  // 发送媒体文件
  sendMedia(params: SendMediaParams): Promise<Result>;
  
  // 订阅事件（消息、状态等）
  on(event: string, handler: Function): void;
  
  // 查询通道能力
  capabilities(): ChannelCapabilities;
}

ChannelCapabilities 接口

interface ChannelCapabilities {
  text: boolean;        // 📝 文本消息
  images: boolean;      // 🖼️ 图片
  videos: boolean;      // 🎥 视频
  audio: boolean;       // 🎵 音频
  documents: boolean;   // 📄 文档
  reactions: boolean;   // ❤️ 反应
  threads: boolean;     // 🧵 线程
  mentions: boolean;    // @ 提及
  formatting: boolean;  // 🎨 Markdown/富文本
}

🔧 具体实现层

WhatsAppProvider

库: Baileys
私有属性: sock: WASocket, authState: AuthState
公有方法: start(), sendMessage(), handleInbound()

TelegramProvider

库: grammY
私有属性: bot: Bot, handle: RunHandle
公有方法: start(), sendMessage(), handleUpdate()

DiscordProvider

库: discord.js
私有属性: client: Client
公有方法: start(), sendMessage(), handleMessage()

SlackProvider

库: Bolt.js
私有属性: app: App
公有方法: start(), sendMessage(), handleEvent()

设计模式说明

接口隔离原则: ChannelProvider 定义统一接口，各平台实现具体逻辑，确保代码的可维护性和可扩展性。
能力查询机制: 通过 ChannelCapabilities 动态查询通道支持的功能，避免硬编码判断。
事件驱动模式: 使用 on(event, handler) 订阅消息、媒体、在线状态等事件，解耦事件处理逻辑。
异步操作模式: 所有核心方法返回 Promise，支持异步操作，不阻塞主线程。
依赖注入: 各 Provider 依赖平台特定的库，通过构造函数注入。

WhatsApp 集成流程

图：详细展示 WhatsApp 通过 Baileys 的集成流程

集成步骤：

初始化: 创建 WASocket，生成 QR 码
配对: 用户扫描 QR 码，建立连接
接收消息: 监听 messages.upsert 事件
发送回复: 调用 sock.sendMessage()

通道能力矩阵

通道 / 功能	📝 文本	🖼️ 图片	🎥 视频	🎵 音频	📄 文档	❤️ 反应	🧵 线程	@ 提及	🎨 格式化
WhatsApp	✅	✅	✅	✅	✅	✅	❌	✅	❌
Telegram	✅	✅	✅	✅	✅	✅	❌	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅	✅	✅
Signal	✅	✅	✅	✅	✅	❌	❌	❌	❌
iMessage	✅	✅	✅	✅	✅	✅	❌	❌	❌

通道选择建议: Discord/Slack 功能最全面，适合团队协作；WhatsApp/Telegram 用户基数大，适合个人使用；Signal 注重隐私安全。

7. 工具系统架构

Clawdbot 提供 6 大类工具，涵盖系统操作、浏览器控制、设备能力、通道交互等。

🛠️ 工具分类体系

💻 系统工具

bash - 执行 Shell 命令
read - 读取文件内容
write - 写入文件内容
edit - 编辑文件（补丁）
process - 进程管理

🌐 浏览器工具

browser.open - 打开网页
browser.snapshot - 网页截图
browser.click - 点击元素
browser.type - 输入文本
browser.scroll - 滚动页面

⚡ 基于 Playwright 实现

📱 设备工具

camera.snap - 拍照
camera.clip - 录像
screen.record - 录屏
location.get - 获取位置
notify - 发送通知

📲 需要设备配对（Node 模式）

💬 通道工具

discord.send - 发送 Discord 消息
slack.post - 发送 Slack 消息
telegram.send - 发送 Telegram 消息
channel.reply - 跨通道回复

🔗 支持主动消息推送

🗂️ 会话工具

session.list - 列出会话
session.switch - 切换会话
session.history - 查看历史
session.clear - 清空上下文

💾 会话管理与上下文控制

⚙️ 自动化工具

cron.schedule - 定时任务
webhook.create - 创建 Webhook
workflow.run - 运行工作流
monitor.watch - 监控任务

🔄 通过插件扩展

⚡ 工具执行流程

图：从 LLM 调用工具到返回结果的完整流程，包含参数验证、策略检查、沙箱隔离等安全机制

执行步骤：

LLM 工具调用: Agent 决定调用工具
参数验证: 基于 TypeBox/JSON Schema 验证
策略检查: 多层策略继承（全局 → Provider → Agent → 群组 → 沙箱）
沙箱判断: 主会话直接执行，群组进入 Docker 沙箱
工具执行: 执行工具代码，流式输出
结果返回: 返回结果，记录日志

工具策略继承链

图：展示工具权限策略的多层继承关系

策略层级：

全局策略: 影响所有会话
Provider 策略: 特定模型提供商
Agent 策略: 特定 Agent 配置
群组策略: 特定会话/群组
沙箱策略: 沙箱内的限制

🔒 安全机制说明

🎯 参数验证: 基于 TypeBox/JSON Schema 验证输入参数类型和格式
🔐 策略检查: 多层策略继承（全局 → Provider → Agent → 群组 → 沙箱）
🛡️ 沙箱隔离: 群组会话默认启用 Docker 沙箱，限制文件/网络访问
📡 流式反馈: 工具执行过程实时反馈，支持长时间运行的任务
📝 审计日志: 所有工具调用均记录日志，可追溯和审计
⏱️ 超时控制: 每个工具可配置超时时间，防止长时间占用

8. 安全模型

Clawdbot 采用多层安全机制，确保系统和数据安全。

安全架构

图：展示网络安全、认证安全、执行安全的完整体系

网络安全

Token 认证

配对时生成随机 Token
Token 存储在客户端和服务端
每次连接验证 Token

Tailscale VPN

通过 Tailscale 建立加密隧道
无需公网 IP
零信任网络架构

SSH 隧道

支持 SSH 端口转发
适合 Linux 服务器部署
公钥认证

TLS 加密

WebSocket over TLS (wss://)
自签名证书或 Let's Encrypt
端到端加密

设备配对流程

图：展示设备发现、配对、认证的完整流程

配对步骤：

发现: mDNS/Bonjour 广播
配对请求: 生成 Token + QR 码
扫描配对: 客户端扫描 QR 码
Token 验证: 验证 Token 有效性
建立连接: WebSocket 连接成功

通道安全

DM 策略

dm-allow-all: 允许所有 DM
dm-allow-listed: 仅允许白名单用户
dm-deny-all: 拒绝所有 DM

通道白名单

配置允许的用户 ID
支持通配符匹配
动态更新白名单

命令网关

特定命令需要管理员权限
命令别名和重定向
命令频率限制

执行隔离

沙箱策略

主会话：信任模式，直接执行
群组会话：沙箱模式，Docker 隔离

Docker 隔离

独立容器执行工具
限制文件系统访问
限制网络访问
资源配额控制

工具策略

细粒度工具权限控制
黑名单/白名单模式
工具参数过滤

资源限制

CPU 配额
内存限制
磁盘配额
超时控制

9. 会话状态管理

会话状态机

图：展示会话从创建到关闭的完整生命周期

状态流转：

idle: 空闲状态，等待消息
queued: 消息已入队，等待执行
running: Agent 正在执行
waiting-for-approval: 等待用户批准（危险操作）
completed: 执行完成
error: 执行出错

会话类型

主会话 (Main Session)

个人私密对话
信任模式，无沙箱
串行队列
长期保留上下文

群组会话 (Group Session)

多人群组对话
沙箱模式
并行队列
上下文窗口限制

DM 会话 (Direct Message)

私信对话
根据白名单决定是否响应
可配置沙箱策略

上下文管理

上下文窗口: 限制历史消息数量
自动清理: 定期清理旧会话
手动清理: session.clear 命令
持久化: 会话存储到本地文件

10. 部署模式

Clawdbot 支持多种部署模式，适应不同场景需求。

部署架构对比

图：展示本地、远程、混合三种部署模式的区别

本地部署

适用场景: 个人使用，数据敏感

架构:

Gateway 运行在本机（macOS/Linux）
通道直接连接到 Gateway
本地访问，低延迟

优势:

✅ 数据完全本地
✅ 无需配置网络
✅ 零成本

劣势:

❌ 设备需要常开
❌ 无法远程访问（除非 VPN）

远程部署

适用场景: 团队使用，7x24 在线

架构:

Gateway 运行在远程服务器（Linux）
通过 SSH/Tailscale 访问
客户端通过网络连接

优势:

✅ 7x24 在线
✅ 团队共享
✅ 统一管理

劣势:

❌ 需要服务器成本
❌ 网络延迟
❌ 数据在云端

混合部署

适用场景: 既要本地能力，又要远程访问

架构:

Gateway 运行在本机
通过 Tailscale 建立 VPN
移动设备远程访问

优势:

✅ 数据本地存储
✅ 可远程访问
✅ 低延迟

劣势:

❌ 需要 Tailscale 配置
❌ 本机需要常开

部署清单

本地部署步骤

安装 Node.js ≥22
安装 Clawdbot: npm install -g clawdbot
初始化配置: clawdbot init
启动 Gateway: clawdbot gateway run
连接通道: 扫描 QR 码配对

远程部署步骤

准备 Linux 服务器（推荐 Ubuntu 22.04）
安装依赖: Node.js, Docker
配置 Tailscale 或 SSH
部署 Gateway: clawdbot gateway run --bind loopback
配置通道和 Agent

Docker 部署

docker run -d \
  --name clawdbot-gateway \
  -p 18789:18789 \
  -v ~/.clawdbot:/root/.clawdbot \
  clawdbot/gateway:latest

11. 数据流架构

完整数据流

端到端数据流
展示从用户输入到 AI 回复的完整数据流

流式数据流
展示 Agent 流式输出的数据流向 图：从用户输入到 Agent 输出的完整数据流

12. 协议交互流程

RPC 调用流程

图：客户端与 Gateway 之间的 RPC 协议交互

RPC 请求格式:

{
  "jsonrpc": "2.0",
  "id": "req-123",
  "method": "agent.run",
  "params": {
    "message": "Hello",
    "session_id": "main"
  }
}

RPC 响应格式:

{
  "jsonrpc": "2.0",
  "id": "req-123",
  "result": {
    "status": "success",
    "output": "Hi there!"
  }
}

流式事件

事件类型:

text: 文本输出
tool_call: 工具调用
tool_result: 工具结果
thinking: 思考过程
error: 错误信息

事件格式:

{
  "type": "tool_call",
  "data": {
    "tool": "bash",
    "params": {
      "command": "ls -la"
    }
  }
}

总结

Clawdbot 通过精心设计的三层架构，实现了：

✅ 统一的通道抽象: 一次集成，处处可用
✅ 强大的工具系统: 从文件操作到浏览器控制
✅ 企业级安全: 沙箱隔离、策略控制、审计日志
✅ 灵活的部署: 本地、远程、混合部署任选
✅ 优雅的流式交互: 实时反馈，流畅体验

这是一个真正为开发者和团队设计的 AI 助手平台，兼顾隐私、安全和易用性。

参考资源

官方文档: docs.clawd.bot
GitHub 仓库: github.com/clawdbot/cl…
安装指南: docs.clawd.bot/install
配置手册: docs.clawd.bot/configurati…
API 文档: docs.clawd.bot/api