张刚AI拆解

Clawdbot 产品功能与实现原理 

作者：

张刚

在

产品概述

Clawdbot 是一个个人 AI 助手平台，将消息渠道（WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等）连接到在您自己设备上运行的 AI 代理。它作为一个本地优先的系统运行，其中 Gateway 控制平面管理渠道连接、代理执行和会话状态，而 Pi 代理运行时 处理与您工作区、浏览器和系统的工具访问的 AI 交互。

核心功能

多渠道消息集成

● WhatsApp (通过 Baileys WhatsApp Web 协议) 

● Telegram (Bot API / grammY) 

● Discord (Bot API / discord.js) 

● Slack (Bolt) 

● Signal、iMessage 等更多渠道 

智能代理系统

● Pi 代理运行时：基于 @mariozechner/pi-agent-core 的 RPC 模式集成 

● 多代理路由：将不同的渠道/账户/对等方路由到隔离的代理（工作区 + 每代理会话） 

● 会话管理：直接聊天折叠到共享的 main 会话；群组会话隔离 

丰富的工具生态

● 浏览器控制：专用的 clawd Chrome/Chromium，支持 CDP 控制

● Canvas + A2UI：代理驱动的可视化工作空间 

● 节点功能：相机快照、屏幕录制、位置获取、通知 

● 语音唤醒 + 对话模式：macOS/iOS/Android 的始终在线语音功能 

实现原理

系统架构

Clawdbot 围绕一个 Gateway 进程组织，该进程作为所有消息渠道、WebSocket 控制平面和代理编排的唯一真实来源。

graph TB
    %% 外部消息平台子图 - 移除双引号嵌套，兼容所有解析器
    subgraph External 外部消息平台
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
    end

    %% Gateway进程 - 替换<br/>为空格，移除HTML标签
    subgraph Gateway Gateway进程 ws://127.0.0.1:18789
        GW[WebSocket + HTTP 服务器]
        MON[渠道监控器]
        AUTO[自动回复]
        SESS[会话管理]
    end

    %% 代理运行时子图
    subgraph Agent 代理运行时
        PI[Pi 嵌入式运行器]
        TOOLS[工具系统]
        SANDBOX[沙箱隔离]
    end

    %% 外部平台 -> 渠道监控器
    WA --> MON
    TG --> MON
    DC --> MON
    SL --> MON
    %% Gateway 内部流转
    MON --> GW
    GW --> AUTO
    AUTO --> SESS
    %% Gateway -> 代理运行时
    SESS --> PI
    %% 代理运行时内部依赖
    PI --> TOOLS
    PI --> SANDBOX

1. Gateway 控制平面

Gateway 是一个运行在端口 18789（可配置）上的 WebSocket 服务器，提供：

● WebSocket RPC 协议：用于 CLI、UI 和节点发出命令

● HTTP 端点：控制 UI、webhook、OpenAI 兼容 API、工具调用

● 渠道监控器：从外部平台轮询/流式传输事件并标准化消息

● Cron 服务：用于计划的代理运行

● 配置热重载：监视配置文件并采用混合重启策略

2. 代理运行时

Clawdbot 使用来自 @mariozechner/pi-agent-core 的 Pi 代理运行时，采用 RPC 模式。代理执行生命周期包括：

1.  认证配置文件选择：轮换认证配置文件并跟踪失败配置文件的冷却时间

2.  系统提示构建：组装 AGENTS.md、SOUL.md、TOOLS.md、技能快照和运行时上下文

3.  工具注册：按策略过滤工具并创建 Pi 工具定义

4.  会话运行：调用带历史记录的 session.prompt()，通过订阅流式传输块

5.  响应传递：分块大响应、去重消息工具输出，并通过渠道发送

3. 消息处理管道

graph TB
MSG["外部消息"] --> MON["渠道监控器"]
MON --> CTX["标准化上下文"]
CTX --> POL{"策略检查"}
POL --> ROUTE{"代理路由"}
ROUTE --> RUN["代理运行"]
RUN --> SEND["渠道发送"]

● 策略执行：如果发送者不在允许列表中或提及要求失败，则早期拒绝消息

● 命令与自动回复：斜杠命令短路到本机处理程序；正常消息路由到代理

● 工具策略过滤：移除在任何级别被拒绝的工具

● 响应去重：跟踪工具输出以避免重复代理已通过 message_send 发送的内容

安全模型

Clawdbot 实施深度防御，具有多层安全：

层级默认姿态配置
DM 访问需要配对dmPolicy: “pairing”
群组访问需要提及requireMention: true
工具访问主会话主机执行，群组沙箱sandbox.mode: “non-main”
Gateway 认证需要令牌（即使是环回）gateway.auth.token
执行安全基于允许列表tools.exec.security: “allowlist”

工具策略层次结构（7 个级别，拒绝总是获胜）：

全局 → 提供商 → 代理 → 群组 → 沙箱 → 子代理 → 配置文件

部署模式

本地 Gateway（默认）

大多数用户在主计算机上运行 Gateway，使用 systemd/launchd 守护进程：

clawdbot onboard --install-daemon
clawdbot gateway status

远程 Gateway

对于 VPS 部署，在服务器上运行 Gateway 并通过 SSH 隧道或 Tailscale 连接本地客户端。

Notes

Clawdbot 是一个开源项目，采用 MIT 许可证。核心架构围绕单一 Gateway 进程设计，确保会话状态的一致性和渠道连接的稳定性。系统支持插件扩展，允许第三方渠道、工具和提供商而无需修改核心代码。详细的配置选项和部署场景请参考官方文档。

更多文章