Clawdbot 三大杀手锏

🏗️ WebSocket Gateway 架构深度剖析

Clawdbot 采用单一 Gateway 控制平面设计,所有消息平台、客户端、节点均通过 WebSocket 连接到 Gateway,实现统一的会话管理、路由和工具调度。

Clawdbot 三层架构
Clawdbot 工作流程
┌─────────────────── 消息渠道层 ────────────────────┐
│  WhatsApp(Baileys)  Telegram(grammY)  Discord    │
│  Slack(@slack/bolt)  Signal  iMessage  MS Teams  │
│  Matrix  BlueBubbles  Google Chat  Nostr  Tlon   │
└──────────────────────┬────────────────────────────┘
                       ▼
┌──────────────────── Gateway 控制平面 ─────────────────┐
│  🌐 WebSocket Server (ws://127.0.0.1:18789)        │
│  ├─ Protocol Version: v1                            │
│  ├─ 50+ RPC Methods (agent/chat/config/cron...)   │
│  ├─ Device Pairing + Token Auth                    │
│  ├─ Session Management (会话路由/历史/状态)        │
│  ├─ Event Streaming (agent/chat/presence/tick)     │
│  └─ Idempotency Keys (安全重试机制)                │
└──────────────────────┬────────────────────────────┘
                       ├──→ Pi Agent (RPC模式)
                       ├──→ CLI (clawdbot commands)
                       ├──→ Control UI (Web管理界面)
                       ├──→ macOS App (菜单栏控制)
                       └──→ iOS/Android Nodes (role: node)
                                    │
                                    ▼
┌──────────────────── Canvas Host ──────────────────┐
│  HTTP Server (port 18793)                          │
│  ├─ Agent-editable HTML                            │
│  ├─ A2UI (Agent-to-UI) Protocol                    │
│  ├─ Live Canvas Snapshots                          │
│  └─ Eval Execution Environment                     │
└────────────────────────────────────────────────────┘
                
🔌

统一 WebSocket 协议

基于 TypeBox + JSON Schema 的类型化协议,支持请求-响应模式 (req/res) 和服务端推送事件 (event),确保客户端与服务端强类型通信。

  • 首帧必须为 connect 握手
  • 支持 CLAWDBOT_GATEWAY_TOKEN 认证
  • Idempotency Keys 防重放
  • Swift/TypeScript 代码生成
🎛️

50+ RPC 方法

Gateway 暴露丰富的 RPC 接口,涵盖 Agent 管理、Chat 交互、Config 配置、Cron 定时任务、设备配对、Exec 审批、Node 调用、Session 管理等全方位能力。

  • agent / agentWait / agentsLis
  • chat.send / chat.abort / chat.history
  • config.get / config.set / config.apply
  • cron.add / cron.run / cron.list
  • sessions.list / sessions.compact / sessions.delete
  • node.invoke / node.describe / node.pair
🔐

设备配对机制

所有 WebSocket 客户端(操作者 + 节点)均需提供设备标识 (device identity),新设备需通过配对审批获取 device token 以供后续连接。

  • 本地连接(loopback)可自动审批
  • 远程连接需签名 challenge
  • Gateway auth 适用所有连接
  • Role-based Access (operator/node)
🌐

远程访问支持

通过 Tailscale VPN 或 SSH 隧道实现远程访问,保持相同的握手和认证流程,可选 TLS + 证书锁定提升安全性。

  • Tailscale: 首选方案(P2P加密)
  • SSH Tunnel: ssh -N -L 18789:127.0.0.1:18789
  • TLS + 可选证书锁定
  • 相同的 Token Auth 流程

🔧 企业级工具系统

Clawdbot 提供一流的 Agent 工具表面,涵盖浏览器控制、Canvas 操作、节点调用、消息管理、定时任务等,支持工具配置文件 (Tool Profiles)、工具组 (Tool Groups)、按提供商策略 (byProvider) 等高级特性。

JSON5 配置示例
{
  tools: {
    profile: "coding",                // 预设工具组合
    deny: ["group:runtime"],          // 全局禁用运行时工具
    byProvider: {                     // 按提供商限制工具
      "google-antigravity": {
        profile: "minimal"
      },
      "openai/gpt-5.2": {
        allow: ["group:fs", "sessions_list"]
      }
    }
  },
  agents: {
    list: [
      {
        id: "support",
        tools: {
          profile: "messaging",       // 仅消息工具
          allow: ["slack", "discord"] // 额外允许渠道工具
        }
      }
    ]
  }
}

Exec 工具(Shell 执行)

在工作区运行 Shell 命令,支持前台/后台执行、TTY/PTY 模式、三种执行宿主(sandbox/gateway/node)、三种安全模式(deny/allowlist/full)。

  • host=sandbox: 默认沙箱隔离
  • host=gateway: Gateway 主机执行
  • host=node: 配对设备执行(macOS/iOS/Android)
  • PTY 支持:交互式 CLI 工具(tmux/vim)
  • 审批系统:allowlist + ask 策略
🌐

Browser 工具(浏览器自动化)

托管的独立 Chrome/Brave/Edge profile,Agent 专用浏览器,与个人浏览器完全隔离,支持确定性标签控制、快照、截图、PDF 生成。

  • 两种模式: clawd (托管) / chrome (扩展中继)
  • Agent 操作: click/type/drag/select
  • 快照模式: labeled/efficient/aria
  • 多 profile 支持: clawd/work/remote
  • 远程 CDP 控制(Browserless)
📦

工具配置文件 (Tool Profiles)

预设工具组合,快速配置 Agent 可用工具集,支持 minimal(最小)、coding(编码)、messaging(消息)、full(完整)四种模式。

  • minimal: 仅 session_status
  • coding: fs + runtime + sessions + memory + image
  • messaging: 消息工具 + sessions
  • full: 无限制(默认)
🎯

工具组 (Tool Groups)

工具策略支持 group:* 快捷方式,一次性控制多个相关工具,简化配置管理。

  • group:runtime → exec, bash, process
  • group:fs → read, write, edit, apply_patch
  • group:sessions → sessions_*, session_status
  • group:memory → memory_search, memory_get
  • group:web → web_search, web_fetch
  • group:ui → browser, canvas
  • group:automation → cron, gateway
  • group:messaging → message

🔒 安全设计与沙箱隔离

运行具有 Shell 访问权限的 AI Agent 是...辛辣的 🌶️。Clawdbot 提供多层安全机制,包括 DM 配对、沙箱模式、工具策略、Exec 审批、安全审计等,确保在保持功能强大的同时最小化风险。

🛡️ 重要:定期运行 clawdbot security audit --fix 检查安全配置
🔐

DM 配对机制(默认)

所有消息平台的 DM 默认采用配对策略 (dmPolicy="pairing"),未知发送者会收到配对码,机器人不处理其消息,防止陌生人滥用。

  • Telegram/WhatsApp/Discord/Slack 默认 pairing
  • clawdbot pairing list <provider>
  • clawdbot pairing approve <provider> <code>
  • 可选 allowlist 白名单策略
📦

沙箱模式(三种隔离级别)

Agent 可在 Docker 容器中运行,隔离文件系统、网络和进程,防止恶意 Prompt Injection 攻击导致主机受损。

  • agent: 每个 Agent 一个容器
  • session: 每个会话一个容器
  • shared: 所有会话共享(关闭隔离)
  • 可配置 Docker 绑定挂载

Exec 审批系统

沙箱 Agent 在 Gateway 或 Node 主机执行命令前需获得批准,通过 macOS/iOS/Android App 或 CLI 管理 allowlist。

  • ~/.clawdbot/exec-approvals.json 存储
  • per-agent allowlist(通配符支持)
  • 技能二进制自动允许(可选)
  • 实时审批 UI(macOS/iOS/Android)
🔍

安全审计工具

clawdbot security audit 检查入站访问、工具爆炸半径、网络暴露、浏览器控制暴露、磁盘权限、插件、模型选择等。

  • --deep: 包含 Gateway 实时探测
  • --fix: 应用安全防护措施
  • 检查 DM/Group 策略
  • 权限审计(700/600)

🎓 AgentSkills 技能生态

Clawdbot 使用 AgentSkills 兼容的技能文件夹,教 Agent 如何使用工具。每个技能是包含 SKILL.md(YAML frontmatter + 指令)的目录,支持 ClawdHub 公共技能注册表。

技能加载优先级
1. <workspace>/skills           (最高优先级 - 每个 Agent 独立)
2. ~/.clawdbot/skills            (共享技能 - 所有 Agent 可见)
3. bundled skills                (内置技能 - npm 包/App 内置)
4. skills.load.extraDirs        (额外目录 - 配置额外路径)
📚

ClawdHub 技能注册表

公共技能注册表,浏览、安装、更新、同步技能。访问 clawdhub.com 发现更多技能。

  • clawdhub install <skill-slug>
  • clawdhub update --all
  • clawdhub sync --all
  • 默认安装到 ./skills 或工作区
🔧

技能格式与兼容性

遵循 AgentSkills 规范,SKILL.md 包含 YAML frontmatter(name/description)和指令内容,支持单行 frontmatter 键。

  • AgentSkills.io 兼容格式
  • Pi Agent 运行时支持
  • 环境变量 + 配置门控
  • 二进制依赖检测
🚀

Per-Agent vs 共享技能

多 Agent 设置中,每个 Agent 有独立工作区,支持 per-agent 技能(工作区内)和共享技能(~/.clawdbot/skills)。

  • Per-agent: <workspace>/skills
  • 共享: ~/.clawdbot/skills
  • 冲突时优先工作区技能
  • 插件技能同样参与优先级
🔌

插件技能支持

插件可在 clawdbot.plugin.json 中列出技能目录,插件启用时加载技能,参与正常优先级规则。

  • clawdbot.plugin.json 声明
  • 相对路径引用
  • metadata.clawdbot.requires.config 门控
  • 参与技能优先级规则

💬 15+ 消息渠道深度集成

Clawdbot 提供统一的消息抽象层,支持 15+ 消息平台的深度集成,每个平台都有详细的配置选项、策略管理、路由规则等。

💬 WhatsApp
via @whiskeysockets/baileys
✈️ Telegram
via grammy + long-polling/webhook
🎮 Discord
via discord.js + Gateway API
💼 Slack
via @slack/bolt + Socket/HTTP Mode
🔐 Signal
via signal-cli + SSE
💭 iMessage
via Barcelona RPC (macOS)
📱 BlueBubbles
iMessage bridge (Private API)
📧 Google Chat
via Google Workspace API
👥 MS Teams
Plugin via Bot Framework
🌐 Matrix
Plugin via matrix-bot-sdk + E2EE
💬 Mattermost
Plugin via WebSocket API
☁️ Nextcloud Talk
Plugin via Talk API
🌊 Nostr
Plugin via nostr-tools
🚀 Tlon/Urbit
Plugin via Urbit HTTP API
🌐 WebChat
Built-in via Gateway WS API
渠道策略配置示例
{
  channels: {
    telegram: {
      accounts: [{
        id: "main",
        botToken: "${TELEGRAM_BOT_TOKEN}",
        dmPolicy: "pairing",              // DM 配对
        groups: {
          "-1001234567890": {             // 群组 ID
            requireMention: true,         // 需要 @mention
            allowFrom: ["@admin"],        // 白名单
            autoThread: true              // 自动回复为主题
          }
        }
      }]
    },
    discord: {
      accounts: [{
        token: "${DISCORD_BOT_TOKEN}",
        dm: {
          policy: "pairing",              // DM 配对
          allowFrom: ["123456789"]        // 用户 ID 白名单
        },
        guilds: {
          "987654321": {                  // 服务器 ID
            channels: {
              "123456789": {              // 频道 ID
                requireMention: false,    // 无需 @mention
                autoThread: false
              }
            }
          }
        }
      }]
    },
    whatsapp: {
      ackReaction: "👍",                   // 确认 reaction
      groups: {
        "[email protected]": {               // 群组 JID
          allowFrom: ["[email protected]"]
        }
      }
    }
  }
}

📊 Clawdbot vs 其他 AI

对比 ChatGPT、Siri、Claude Code,看看 Clawdbot 有什么不同

Clawdbot 对比分析

👨‍💻 开发者体验与 CLI 工具

Clawdbot 提供强大的 CLI 工具、配置系统、插件架构、文档生成等,极大提升开发和运维效率。

CLI 命令全家桶

clawdbot 提供丰富的 CLI 命令,涵盖 Gateway 管理、会话操作、消息发送、Agent 调用、配置管理、安全审计等。

  • clawdbot gateway run --port 18789
  • clawdbot agent --message "Hello"
  • clawdbot message send --target +123456
  • clawdbot sessions list / compact / delete
  • clawdbot pairing list / approve <provider>
  • clawdbot security audit --fix
  • clawdbot doctor --non-interactive
  • clawdbot update --update
⚙️

配置系统(JSON5 + $include)

~/.clawdbot/clawdbot.json 采用 JSON5 格式(支持注释),支持 $include 指令模块化配置,环境变量替换 ${VAR}。

  • JSON5: 注释、尾随逗号、多行字符串
  • $include: 模块化拆分配置文件
  • ${VAR}: 环境变量替换
  • config.env: 优先级高于环境变量
🔌

插件架构(渠道/提供商/技能)

插件系统支持扩展 Clawdbot 功能,包括消息渠道插件、AI 提供商插件、工具插件、技能插件等。

  • clawdbot plugins install <path/npm>
  • clawdbot plugins list / enable / disable
  • clawdbot.plugin.json 元数据
  • config schema + UI hints
📊

状态与诊断工具

clawdbot status 提供全面的系统状态报告,clawdbot doctor 自动诊断和修复常见问题。

  • status --all: 完整只读调试报告
  • status --deep: 包含 Gateway 探测
  • doctor --fix: 自动修复配置问题
  • logs: pretty/plain/JSONL 模式

🛠️ 核心技术栈

Node.js 22+
运行时基线
TypeScript + ESM
语言 + 模块系统
Pi Agent Core
Agent 运行时(RPC 模式)
TypeBox + AJV
类型化 Schema + 验证
WebSocket (ws)
Gateway 协议传输层
@whiskeysockets/baileys
WhatsApp 集成
grammy
Telegram 集成
discord.js
Discord 集成
@slack/bolt
Slack 集成
Playwright
浏览器自动化
SQLite + sqlite-vec
向量搜索 + 内存索引
Docker
沙箱隔离

🚀 快速开始

Clawdbot 成本分析
Bash (Node ≥22)
# 全局安装 clawdbot
npm install -g clawdbot@latest

# 运行引导向导 (推荐)
clawdbot onboard --install-daemon

# 启动 Gateway
clawdbot gateway run --port 18789 --verbose

# 发送消息
clawdbot message send --target +1234567890 --message "Hello"

# 与助手对话
clawdbot agent --message "Ship checklist" --thinking high

# 安全审计
clawdbot security audit --fix

# 查看状态
clawdbot status --all

👨‍💻 维护者团队

👨‍💻

Peter Steinberger

Benevolent Dictator · 项目创始人

  • GitHub: @steipete
  • X/Twitter: @steipete
  • 资深 iOS/macOS 开发者
🎮

Shadow

Discord + Slack Subsystem 维护者

  • GitHub: @thewilloftheshadow
  • X/Twitter: @4shad0wed
  • Discord/Slack 集成专家
✈️

Jos

Telegram + API + Nix Mode 维护者

  • GitHub: @joshp123
  • X/Twitter: @jjpcodes
  • Telegram/API 架构师

🎯 Clawdbot 适合你吗?

帮你判断是否适合使用 Clawdbot

Clawdbot 适用人群