🏗️ WebSocket Gateway 架构深度剖析
Clawdbot 采用单一 Gateway 控制平面设计,所有消息平台、客户端、节点均通过 WebSocket 连接到 Gateway,实现统一的会话管理、路由和工具调度。
┌─────────────────── 消息渠道层 ────────────────────┐ │ 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) 等高级特性。
{
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+ 消息平台的深度集成,每个平台都有详细的配置选项、策略管理、路由规则等。
{
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 有什么不同
👨💻 开发者体验与 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 模式
🛠️ 核心技术栈
🚀 快速开始
# 全局安装 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