当 AI 助手遇上全平台消息：Clawdbot 的架构奇遇记

"EXFOLIATE! EXFOLIATE!" ------ 这只太空龙虾正在改变我们与 AI 交互的方式

引子：一个不太一样的 AI 助手

想象一下，你正在 WhatsApp 上和朋友聊天，突然想起要查个资料。你不需要切换到浏览器，不需要打开另一个 App，只需要在聊天窗口里 @一下你的 AI 助手，它就能帮你搞定一切------搜索、总结、甚至执行代码。这不是科幻，这就是 Clawdbot 正在做的事情。

但 Clawdbot 的野心远不止于此。它不仅支持 WhatsApp，还能同时接入 Telegram、Slack、Discord、Signal、iMessage、Microsoft Teams 等十几个平台。更酷的是，它完全运行在你自己的设备上，数据隐私完全由你掌控。

今天，我们就来深入剖析这个项目的技术架构，看看它是如何实现这些"魔法"的。

一、架构全景：一个 Gateway 统治所有

1.1 核心设计理念

Clawdbot 的架构设计遵循一个简单而强大的原则：单一控制平面（Single Control Plane）。整个系统围绕一个名为 "Gateway" 的核心组件展开，它就像一个超级管家，负责协调所有的消息渠道、AI 模型和设备节点。

复制代码

WhatsApp / Telegram / Slack / Discord / Signal / iMessage ...
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (WebSocket 控制平面)     │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi Agent (RPC 模式)
               ├─ CLI 工具
               ├─ WebChat UI
               ├─ macOS 应用
               └─ iOS / Android 节点

这种设计的妙处在于：

统一接口：所有客户端（无论是命令行工具、移动应用还是 Web 界面）都通过同一个 WebSocket 接口与 Gateway 通信
状态集中：消息历史、会话状态、配置信息都由 Gateway 统一管理
易于扩展：新增一个消息平台？只需要在 Gateway 中添加对应的适配器即可

1.2 技术栈选型

让我们看看 Clawdbot 的技术栈（从 package.json 中提取）：

运行时环境：

Node.js 22+ （要求最新的 LTS 版本）
TypeScript（全面类型安全）
支持 Bun 作为开发时的快速执行器

核心依赖：

@whiskeysockets/baileys：WhatsApp Web 协议实现
grammy：Telegram Bot 框架
@slack/bolt：Slack 应用框架
discord-api-types：Discord API 类型定义
@mariozechner/pi-agent-core：AI Agent 运行时核心
playwright-core：浏览器自动化
ws：WebSocket 服务器

有趣的细节：

使用 @sinclair/typebox 进行运行时类型验证（而不是仅依赖 TypeScript 的编译时检查）
集成 sqlite-vec 用于向量搜索（本地化的 RAG 能力）
支持 node-llama-cpp 作为可选依赖（本地 LLM 推理）

这个技术栈的选择体现了项目的几个核心价值观：

类型安全优先：从 TypeScript 到 TypeBox，再到 Zod，多层类型保护
本地优先：尽可能在本地运行，减少对云服务的依赖
性能敏感：选择高性能的库（如 Playwright 而非 Puppeteer）

二、Gateway：系统的心脏

2.1 WebSocket 协议设计

Gateway 的核心是一个精心设计的 WebSocket 协议。让我们看看它的握手流程：

复制代码

// 客户端必须发送的第一帧
{
  type: "req",
  id: "unique-request-id",
  method: "connect",
  params: {
    minProtocol: 1,
    maxProtocol: 1,
    client: {
      id: "client-device-id",
      displayName: "My MacBook Pro",
      version: "2026.1.25",
      platform: "darwin",
      deviceFamily: "Mac",
      mode: "operator"  // 或 "node"
    },
    auth: {
      token: "gateway-auth-token"  // 可选，取决于配置
    }
  }
}

// Gateway 的响应
{
  type: "res",
  id: "unique-request-id",
  ok: true,
  payload: {
    type: "hello-ok",
    snapshot: {
      presence: [...],  // 当前在线的设备列表
      health: {...},    // 系统健康状态
      stateVersion: 42  // 状态版本号
    },
    policy: {
      maxPayload: 10485760,      // 10MB
      maxBufferedBytes: 52428800, // 50MB
      tickIntervalMs: 30000       // 心跳间隔
    }
  }
}

这个协议设计有几个巧妙之处：

1. 强制握手 ：任何非 connect 的第一帧都会导致连接立即关闭。这确保了所有客户端都经过身份验证。

2. 快照机制：握手响应中包含完整的系统状态快照，客户端无需额外请求就能立即渲染 UI。

3. 版本协商 ：通过 minProtocol 和 maxProtocol 实现向后兼容。

4. 设备识别：每个客户端都有唯一的设备 ID，支持设备级别的配对和权限管理。

2.2 请求-响应模式

握手完成后，客户端可以发送各种请求：

复制代码

// 发送消息
{
  type: "req",
  id: "msg-001",
  method: "send",
  params: {
    target: "+1234567890",
    message: "Hello from Clawdbot!",
    idempotencyKey: "unique-key-for-retry"  // 防止重复发送
  }
}

// 运行 AI Agent
{
  type: "req",
  id: "agent-001",
  method: "agent",
  params: {
    message: "帮我总结一下今天的新闻",
    sessionKey: "main",
    thinkingLevel: "medium"
  }
}

// 调用设备节点命令
{
  type: "req",
  id: "node-001",
  method: "node.invoke",
  params: {
    nodeId: "iphone-12-pro",
    command: "camera.snap",
    args: {
      quality: "high"
    }
  }
}

幂等性设计 ：注意 send 方法中的 idempotencyKey。这是一个关键的设计，确保在网络不稳定时重试不会导致消息重复发送。Gateway 会维护一个短期的去重缓存。

2.3 事件推送机制

除了请求-响应，Gateway 还会主动推送事件：

复制代码

// Agent 执行过程中的流式输出
{
  type: "event",
  event: "agent",
  seq: 42,  // 序列号，用于检测丢失
  payload: {
    runId: "run-123",
    type: "tool_start",
    tool: "bash",
    input: "ls -la"
  }
}

// 设备在线状态变化
{
  type: "event",
  event: "presence",
  stateVersion: 43,
  payload: {
    added: [{
      host: "macbook-pro.local",
      ip: "192.168.1.100",
      version: "2026.1.25",
      platform: "darwin",
      mode: "operator",
      ts: 1706227200000
    }],
    removed: []
  }
}

// 心跳保活
{
  type: "event",
  event: "tick",
  payload: {}
}

序列号机制：每个事件都有一个递增的序列号。客户端可以检测到序列号跳跃，从而发现丢失的事件并主动刷新状态。

增量更新 ：presence 事件只包含变化的部分（added 和 removed），而不是每次都发送完整列表，大大减少了带宽消耗。

2.4 多租户与会话隔离

Clawdbot 支持多 Agent 配置，每个 Agent 可以有独立的：

工作空间目录
模型配置
工具权限
沙箱设置

{
"agents": {
"defaults": {
"workspace": "~/clawd",
"model": "anthropic/claude-opus-4-5"
},
"agents": {
"coding-assistant": {
"workspace": "~/clawd-coding",
"model": "anthropic/claude-sonnet-4",
"sandbox": {
"mode": "always",
"allowlist": ["bash", "read", "write"]
}
},
"research-bot": {
"workspace": "~/clawd-research",
"model": "openai/gpt-5.2",
"tools": {
"web": { "enabled": true }
}
}
}
}
}

这种设计让你可以为不同的任务配置不同的 AI 助手，它们互不干扰，各司其职。

三、消息路由：从 WhatsApp 到 Agent

3.1 统一的消息抽象

Clawdbot 面临的一个核心挑战是：如何统一处理来自十几个不同平台的消息？每个平台都有自己的 API、数据格式和特性。

项目的解决方案是定义一个统一的内部消息格式：

复制代码

interface InboundMessage {
  // 消息来源
  channel: "whatsapp" | "telegram" | "slack" | "discord" | ...;
  
  // 发送者标识（统一格式）
  from: {
    id: string;           // 平台特定的用户 ID
    displayName?: string;
    username?: string;
  };
  
  // 会话标识
  chat: {
    id: string;           // 聊天 ID
    type: "dm" | "group"; // 私聊或群聊
    title?: string;
  };
  
  // 消息内容
  text?: string;
  media?: Array<{
    type: "image" | "audio" | "video" | "document";
    url: string;
    mimeType: string;
    size: number;
  }>;
  
  // 元数据
  timestamp: number;
  replyTo?: string;      // 回复的消息 ID
  mentions?: string[];   // @提及的用户
}

每个平台的适配器负责将原始消息转换为这个统一格式。例如，Telegram 适配器的核心逻辑：

复制代码

// src/telegram/bot-message-context.ts 的简化版本
function normalizeInboundMessage(ctx: Context): InboundMessage {
  return {
    channel: "telegram",
    from: {
      id: `tg:${ctx.from.id}`,
      displayName: ctx.from.first_name,
      username: ctx.from.username
    },
    chat: {
      id: `tg:${ctx.chat.id}`,
      type: ctx.chat.type === "private" ? "dm" : "group",
      title: ctx.chat.title
    },
    text: ctx.message?.text,
    media: ctx.message?.photo ? [{
      type: "image",
      url: await downloadTelegramFile(ctx.message.photo),
      mimeType: "image/jpeg",
      size: ctx.message.photo.file_size
    }] : undefined,
    timestamp: ctx.message.date * 1000,
    replyTo: ctx.message?.reply_to_message?.message_id.toString()
  };
}

3.2 智能路由策略

消息到达 Gateway 后，需要决定：

是否应该响应这条消息？
应该路由到哪个 Agent？
应该使用哪个会话上下文？

Clawdbot 实现了一套灵活的路由规则：

白名单机制：

复制代码

{
  "channels": {
    "whatsapp": {
      "allowFrom": [
        "+1234567890",      // 允许特定号码
        "group:abc123"      // 允许特定群组
      ]
    },
    "telegram": {
      "allowFrom": [
        "tg:@username",     // 允许特定用户名
        "*"                 // 或允许所有人（需谨慎）
      ]
    }
  }
}

群组激活模式：

复制代码

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true,  // 必须 @机器人才响应
          "activation": "mention"  // 或 "always"
        }
      }
    }
  }
}

Agent 绑定：

复制代码

{
  "routing": {
    "bindings": [
      {
        "channel": "telegram",
        "account": "bot-token-1",
        "agentId": "coding-assistant"
      },
      {
        "channel": "whatsapp",
        "from": "+1234567890",
        "agentId": "personal-assistant"
      }
    ]
  }
}

这种路由设计的精妙之处在于：它既保证了安全性（默认拒绝未授权的消息），又提供了极大的灵活性（可以为不同的用户/群组配置不同的 Agent）。

3.3 会话管理

Clawdbot 的会话管理采用了一个巧妙的 Key 生成策略：

复制代码

// src/routing/session-key.ts 的简化版本
function deriveSessionKey(message: InboundMessage): string {
  const { channel, chat, from } = message;
  
  if (chat.type === "dm") {
    // 私聊：channel + 发送者 ID
    return `${channel}:${from.id}`;
  } else {
    // 群聊：channel + 群组 ID
    return `${channel}:${chat.id}`;
  }
}

这意味着：

每个私聊对话有独立的会话上下文
每个群聊有共享的会话上下文（群成员共享历史）
不同平台的会话完全隔离

会话数据存储在本地文件系统：

复制代码

~/.clawdbot/agents/<agentId>/sessions/<sessionKey>.jsonl

使用 JSONL 格式（每行一个 JSON 对象）的好处是：

易于追加（不需要重写整个文件）
易于解析（逐行读取）
易于调试（直接用文本编辑器查看）

四、AI Agent 运行时

4.1 工作空间设计

Clawdbot 的 Agent 运行在一个明确定义的工作空间中：

复制代码

~/clawd/                    # 默认工作空间
├── AGENTS.md              # 操作指南和"记忆"
├── SOUL.md                # 人格、边界、语气
├── TOOLS.md               # 工具使用说明
├── IDENTITY.md            # Agent 名称/风格/表情
├── USER.md                # 用户资料
├── BOOTSTRAP.md           # 首次运行仪式（运行后删除）
├── skills/                # 技能目录
│   ├── github/
│   ├── notion/
│   └── weather/
└── canvas/                # Canvas 文件服务器根目录

这些 Markdown 文件会在每次会话开始时注入到 Agent 的上下文中。这是一个非常聪明的设计：

为什么用 Markdown？

人类可读：你可以直接编辑这些文件来调整 Agent 的行为
版本控制友好：可以用 Git 管理这些配置
灵活性：可以包含代码示例、表格、列表等丰富内容

SOUL.md 示例：

复制代码

# Agent Soul

## Identity
I am Clawd, a helpful space lobster assistant. 🦞

## Personality
- Friendly and approachable
- Occasionally uses lobster-themed humor
- Professional when needed, casual when appropriate

## Boundaries
- I don't pretend to have emotions I don't have
- I acknowledge my limitations
- I prioritize user privacy and security

## Communication Style
- Clear and concise
- Use emojis sparingly but effectively
- Adapt tone to match the user's style

4.2 工具系统

Clawdbot 的工具系统基于 Pi Agent 框架，但做了大量定制。核心工具包括：

文件操作：

read：读取文件内容
write：写入文件
edit：编辑文件（支持 diff 格式）
apply_patch：应用补丁

命令执行：

bash：执行 Shell 命令
process：管理后台进程

浏览器控制：

browser.navigate：导航到 URL
browser.click：点击元素
browser.type：输入文本
browser.snapshot：获取页面快照

设备节点：

camera.snap：拍照
screen.record：录屏
location.get：获取位置
canvas.*：Canvas 操作

会话管理：

sessions_list：列出所有会话
sessions_history：获取会话历史
sessions_send：向其他会话发送消息

最后一个特别有意思：Agent 可以跨会话通信！想象一下，你的编程助手可以主动向你的个人助手发送消息："代码部署完成，请通知用户。"

4.3 沙箱隔离

对于不受信任的输入（比如群聊消息），Clawdbot 支持在 Docker 容器中运行 Agent：

复制代码

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",  // 只对非主会话启用沙箱
        "allowlist": [
          "bash",
          "read",
          "write"
        ],
        "denylist": [
          "browser",
          "canvas",
          "nodes"
        ],
        "docker": {
          "image": "clawdbot/sandbox:latest",
          "cpus": 2,
          "memory": "2g"
        }
      }
    }
  }
}

这种设计在安全性和便利性之间取得了很好的平衡：

私聊消息（主会话）：完全信任，直接在主机上运行
群聊消息（非主会话）：在沙箱中运行，限制工具访问

4.4 流式响应与分块

Clawdbot 实现了一个复杂的流式响应系统，让 AI 的回复可以实时显示：

复制代码

// 简化的流式处理逻辑
async function* streamAgentResponse(runId: string) {
  for await (const event of agentRuntime.subscribe(runId)) {
    switch (event.type) {
      case "text_delta":
        // 文本增量更新
        yield {
          type: "agent",
          payload: {
            runId,
            type: "text_delta",
            text: event.text
          }
        };
        break;
        
      case "tool_start":
        // 工具开始执行
        yield {
          type: "agent",
          payload: {
            runId,
            type: "tool_start",
            tool: event.tool,
            input: event.input
          }
        };
        break;
        
      case "tool_end":
        // 工具执行完成
        yield {
          type: "agent",
          payload: {
            runId,
            type: "tool_end",
            tool: event.tool,
            output: event.output
          }
        };
        break;
    }
  }
}

分块策略：不同的消息平台对消息长度有不同的限制。Clawdbot 实现了智能分块：

复制代码

// 分块配置示例
{
  "channels": {
    "telegram": {
      "chunkSize": 4096,        // Telegram 的限制
      "chunkStrategy": "paragraph"  // 按段落分割
    },
    "whatsapp": {
      "chunkSize": 65536,       // WhatsApp 的限制
      "chunkStrategy": "sentence"   // 按句子分割
    }
  }
}

分块算法会尽量保持代码块、列表等结构的完整性，避免在不合适的位置切断。

五、跨平台节点系统

5.1 节点架构

Clawdbot 的一个独特功能是"节点"（Node）系统。你可以将 iPhone、iPad、Android 手机等设备注册为节点，然后 Agent 可以调用这些设备的能力。

节点注册流程：

发现阶段：节点通过 Bonjour/mDNS 广播自己的存在

// 简化的 Bonjour 广播
{
name: "iPhone 12 Pro",
type: "_clawdbot._tcp",
port: 18789,
txt: {
version: "2026.1.25",
deviceFamily: "iPhone",
modelIdentifier: "iPhone13,3",
caps: "camera,location,canvas"
}
}
配对阶段：用户批准节点连接

列出待配对的节点

clawdbot pairing list

批准节点

clawdbot pairing approve node abc123
命令调用：Agent 通过 Gateway 调用节点命令

// Agent 调用 iPhone 拍照
const result = await gateway.invoke({
method: "node.invoke",
params: {
nodeId: "iphone-12-pro",
command: "camera.snap",
args: {
camera: "back",
quality: "high"
}
}
});

// 返回图片 URL
// result.payload.url = "http://gateway:18789/media/abc123.jpg"

5.2 Canvas 系统

Canvas 是 Clawdbot 的一个创新功能：Agent 可以生成和控制一个实时的 Web 界面。

工作原理：

Gateway 运行一个文件服务器（默认端口 18793）
Agent 可以写入 HTML/CSS/JS 文件到 ~/clawd/canvas/
客户端（iOS/Android/macOS）通过 WebView 加载这些文件
Agent 可以通过 canvas.eval 执行 JavaScript 来更新界面

示例场景：

复制代码

// Agent 创建一个实时股票监控界面
await agent.tools.write({
  path: "canvas/stocks.html",
  content: `
    <!DOCTYPE html>
    <html>
    <head>
      <title>Stock Monitor</title>
      <style>
        .stock { padding: 10px; border: 1px solid #ccc; }
        .up { color: green; }
        .down { color: red; }
      </style>
    </head>
    <body>
      <div id="stocks"></div>
      <script>
        function updateStock(symbol, price, change) {
          const div = document.getElementById(symbol) || 
                      document.createElement('div');
          div.id = symbol;
          div.className = 'stock ' + (change > 0 ? 'up' : 'down');
          div.innerHTML = \`\${symbol}: $\${price} (\${change}%)\`;
          document.getElementById('stocks').appendChild(div);
        }
      </script>
    </body>
    </html>
  `
});

// 定期更新数据
setInterval(async () => {
  const stockData = await fetchStockPrices();
  for (const stock of stockData) {
    await agent.tools.canvas.eval({
      code: `updateStock('${stock.symbol}', ${stock.price}, ${stock.change})`
    });
  }
}, 5000);

这个功能让 AI 助手不再局限于文本交互，可以创建丰富的可视化界面。

六、安全性设计

6.1 多层防护

Clawdbot 的安全设计体现在多个层面：

1. 网络层：

默认只监听 127.0.0.1（本地回环）
支持 Tailscale Serve/Funnel 进行安全的远程访问
可选的 Token 认证

2. 消息层：

白名单机制（默认拒绝所有未授权的发送者）
配对系统（新设备需要明确批准）
DM 策略配置

{
"channels": {
"telegram": {
"dm": {
"policy": "pairing", // 或 "open"（危险）
"allowFrom": [
"tg:@trusted_user"
]
}
}
}
}

3. 工具层：

工具白名单/黑名单
命令执行审批机制
沙箱隔离

{
"tools": {
"exec": {
"approval": {
"mode": "ask", // 或 "always", "never"
"patterns": [
"rm -rf *", // 危险命令需要审批
"sudo *"
]
}
}
}
}

4. 数据层：

所有数据存储在本地
敏感信息（如 API Key）存储在 ~/.clawdbot/credentials/
支持加密存储（可选）

6.2 审计与监控

Clawdbot 提供了完善的审计功能：

复制代码

# 查看所有执行的命令
clawdbot logs --filter exec

# 查看特定会话的历史
clawdbot sessions history telegram:@user123

# 安全审计
clawdbot security audit

clawdbot doctor 命令会检查常见的安全配置问题：

Gateway 是否暴露在公网
是否启用了认证
DM 策略是否过于宽松
是否有危险的工具配置

七、性能优化

7.1 连接池与复用

Clawdbot 对各种资源进行了精心的池化管理：

WebSocket 连接池：

每个客户端只维护一个 WebSocket 连接
使用多路复用（通过 id 字段关联请求和响应）
自动重连机制

浏览器实例池：

复制代码

// 简化的浏览器池管理
class BrowserPool {
  private browsers = new Map<string, Browser>();
  
  async getBrowser(profileId: string): Promise<Browser> {
    if (!this.browsers.has(profileId)) {
      const browser = await playwright.chromium.launch({
        userDataDir: `~/.clawdbot/browser-profiles/${profileId}`,
        headless: true
      });
      this.browsers.set(profileId, browser);
    }
    return this.browsers.get(profileId)!;
  }
  
  async cleanup() {
    for (const browser of this.browsers.values()) {
      await browser.close();
    }
    this.browsers.clear();
  }
}

7.2 缓存策略

会话缓存：

最近访问的会话保持在内存中
LRU 淘汰策略
定期持久化到磁盘

媒体缓存：

复制代码

// 媒体文件缓存策略
{
  "media": {
    "cache": {
      "maxSize": "1GB",
      "ttl": 86400,  // 24小时
      "strategy": "lru"
    }
  }
}

模型响应缓存：

对于相同的输入，可以复用之前的响应
使用内容哈希作为缓存键
可配置的 TTL

7.3 并发控制

Clawdbot 实现了精细的并发控制：

复制代码

{
  "agents": {
    "defaults": {
      "concurrency": {
        "maxConcurrentRuns": 3,      // 最多同时运行 3 个 Agent
        "maxConcurrentTools": 5,     // 每个 Agent 最多同时执行 5 个工具
        "queueMode": "steer"         // 或 "followup", "collect"
      }
    }
  }
}

队列模式：

steer：新消息会中断当前执行，注入到上下文中
followup：新消息排队，等待当前执行完成
collect：收集多条消息，批量处理

八、可观测性

8.1 结构化日志

Clawdbot 使用 tslog 实现结构化日志：

复制代码

// 日志示例
{
  "timestamp": "2026-01-25T10:30:00.000Z",
  "level": "info",
  "subsystem": "gateway",
  "event": "message_received",
  "channel": "telegram",
  "from": "tg:@user123",
  "sessionKey": "telegram:@user123",
  "messageLength": 42
}

日志会自动脱敏，移除敏感信息（如电话号码、Token）。

8.2 健康检查

Gateway 提供了丰富的健康检查端点：

复制代码

// 健康检查响应示例
{
  "ok": true,
  "version": "2026.1.25",
  "uptime": 86400000,  // 毫秒
  "channels": {
    "whatsapp": {
      "status": "connected",
      "authenticated": true,
      "lastActivity": "2026-01-25T10:29:00.000Z"
    },
    "telegram": {
      "status": "connected",
      "authenticated": true,
      "lastActivity": "2026-01-25T10:28:00.000Z"
    }
  },
  "agents": {
    "activeSessions": 5,
    "runningTasks": 2
  },
  "resources": {
    "memory": {
      "used": 512000000,
      "total": 2048000000
    },
    "disk": {
      "used": 10737418240,
      "total": 107374182400
    }
  }
}

8.3 指标收集

Clawdbot 支持通过扩展导出指标到 OpenTelemetry：

复制代码

{
  "plugins": {
    "diagnostics-otel": {
      "enabled": true,
      "endpoint": "http://localhost:4318/v1/traces"
    }
  }
}

九、扩展性设计

9.1 插件系统

Clawdbot 的插件系统允许第三方扩展功能：

复制代码

// 插件清单示例 (plugin.json)
{
  "name": "my-custom-channel",
  "version": "1.0.0",
  "type": "channel",
  "main": "dist/index.js",
  "dependencies": {
    "clawdbot": "^2026.1.0"
  },
  "slots": {
    "channel": {
      "id": "my-channel",
      "displayName": "My Custom Channel"
    }
  }
}

插件类型：

channel：新的消息平台
provider：新的 AI 模型提供商
tool：新的工具
hook：事件钩子

插件发现：

复制代码

# 安装插件
clawdbot plugins install my-custom-channel

# 列出已安装的插件
clawdbot plugins list

# 启用/禁用插件
clawdbot plugins enable my-custom-channel
clawdbot plugins disable my-custom-channel

9.2 技能系统

技能（Skills）是一种轻量级的扩展方式：

复制代码

~/.clawdbot/skills/
├── github/
│   ├── SKILL.md          # 技能描述
│   ├── tools.json        # 工具定义
│   └── commands/         # 可执行脚本
│       ├── create-issue.sh
│       └── list-prs.sh
├── notion/
└── weather/

SKILL.md 示例：

复制代码

# GitHub Skill

This skill provides GitHub integration.

## Commands

- `gh-create-issue <repo> <title> <body>`: Create a new issue
- `gh-list-prs <repo>`: List open pull requests

## Environment Variables

- `GITHUB_TOKEN`: GitHub personal access token

## Usage

Ask me to "create a GitHub issue" or "list PRs for repo X".

技能会自动注入到 Agent 的上下文中，Agent 可以根据需要调用相应的命令。

9.3 Hooks 系统

Hooks 允许在特定事件发生时触发自动化：

复制代码

{
  "hooks": {
    "gmail-watcher": {
      "type": "gmail-pubsub",
      "enabled": true,
      "config": {
        "projectId": "my-project",
        "topicName": "gmail-notifications",
        "filters": {
          "from": ["important@example.com"],
          "subject": ["URGENT"]
        }
      },
      "action": {
        "type": "agent",
        "message": "New urgent email: {{subject}}",
        "sessionKey": "main"
      }
    },
    "daily-summary": {
      "type": "cron",
      "enabled": true,
      "schedule": "0 9 * * *",  // 每天早上 9 点
      "action": {
        "type": "agent",
        "message": "Generate daily summary",
        "sessionKey": "main"
      }
    }
  }
}

十、部署与运维

10.1 部署选项

Clawdbot 支持多种部署方式：

1. 本地部署（推荐）：

复制代码

npm install -g clawdbot@latest
clawdbot onboard --install-daemon

2. Docker 部署：

复制代码

# docker-compose.yml
version: '3.8'
services:
  clawdbot:
    image: clawdbot/clawdbot:latest
    volumes:
      - ./config:/root/.clawdbot
      - ./workspace:/root/clawd
    ports:
      - "18789:18789"
    environment:
      - CLAWDBOT_GATEWAY_TOKEN=your-secret-token
    restart: unless-stopped

3. VPS 部署：

复制代码

# 在远程服务器上
ssh user@vps
curl -fsSL https://clawd.bot/install.sh | bash
clawdbot onboard --install-daemon

4. Fly.io / Render 部署 ：项目提供了预配置的部署文件（fly.toml, render.yaml）。

10.2 守护进程管理

**macOS (launchd)**：

复制代码

# 安装守护进程
clawdbot gateway install

# 启动/停止/重启
clawdbot gateway start
clawdbot gateway stop
clawdbot gateway restart

# 查看状态
clawdbot gateway status

# 查看日志
clawdbot logs --follow

**Linux (systemd)**：

复制代码

# 安装用户服务
clawdbot gateway install

# 启用开机自启
systemctl --user enable clawdbot-gateway

# 启动服务
systemctl --user start clawdbot-gateway

# 查看状态
systemctl --user status clawdbot-gateway

# 查看日志
journalctl --user -u clawdbot-gateway -f

10.3 配置管理

Clawdbot 支持配置热重载：

复制代码

{
  "gateway": {
    "reload": {
      "mode": "hybrid",  // "off", "hot", "restart", "hybrid"
      "watch": true      // 监听配置文件变化
    }
  }
}

重载模式：

off：禁用热重载
hot：仅热重载安全的配置（如日志级别、超时时间）
restart：所有配置变更都触发重启
hybrid：安全的配置热重载，关键配置触发重启

配置验证：

复制代码

# 验证配置文件
clawdbot config validate

# 查看当前配置
clawdbot config show

# 修改配置
clawdbot config set agents.defaults.model anthropic/claude-opus-4-5

10.4 备份与恢复

自动备份：

复制代码

{
  "backup": {
    "enabled": true,
    "schedule": "0 2 * * *",  // 每天凌晨 2 点
    "retention": {
      "daily": 7,
      "weekly": 4,
      "monthly": 3
    },
    "targets": [
      "~/.clawdbot/clawdbot.json",
      "~/.clawdbot/agents/",
      "~/.clawdbot/credentials/"
    ]
  }
}

手动备份：

复制代码

# 备份所有数据
clawdbot backup create

# 列出备份
clawdbot backup list

# 恢复备份
clawdbot backup restore 2026-01-25-02-00-00

十一、实战案例

案例 1：个人知识管理助手

场景：通过 Telegram 与 AI 助手交互，自动整理笔记到 Notion。

配置：

复制代码

{
  "agents": {
    "defaults": {
      "workspace": "~/clawd-knowledge",
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "channels": {
    "telegram": {
      "botToken": "your-bot-token",
      "allowFrom": ["tg:@your_username"]
    }
  },
  "skills": {
    "bundled": ["notion"],
    "workspace": ["custom-notion-templates"]
  }
}

工作流：

在 Telegram 发送："帮我记录一下：今天学习了 Clawdbot 的架构设计"
Agent 理解意图，提取关键信息
调用 Notion 技能，创建新页面
回复："已记录到 Notion，标题：Clawdbot 架构设计学习笔记"

案例 2：团队协作机器人

场景：在 Slack 群组中部署 AI 助手，帮助团队成员快速查询文档、创建任务。

配置：

复制代码

{
  "agents": {
    "agents": {
      "team-assistant": {
        "workspace": "~/clawd-team",
        "model": "anthropic/claude-sonnet-4",
        "sandbox": {
          "mode": "always",  // 群聊消息总是在沙箱中运行
          "allowlist": ["read", "web"]
        }
      }
    }
  },
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "channels": {
        "*": {
          "requireMention": true,
          "agentId": "team-assistant"
        }
      }
    }
  },
  "routing": {
    "bindings": [
      {
        "channel": "slack",
        "agentId": "team-assistant"
      }
    ]
  }
}

使用示例：

复制代码

@bot 帮我查一下 API 文档中关于认证的部分

@bot 创建一个任务：优化数据库查询性能，分配给 @张三

@bot 总结一下今天的讨论要点

案例 3：智能家居控制

场景：通过 WhatsApp 控制家中的智能设备。

配置：

复制代码

{
  "agents": {
    "defaults": {
      "workspace": "~/clawd-home",
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890"]  // 只允许家庭成员
    }
  },
  "skills": {
    "workspace": ["openhue", "sonoscli"]
  }
}

使用示例：

复制代码

打开客厅的灯

把卧室的温度调到 22 度

播放一些轻音乐

晚安（自动关闭所有灯光，设置闹钟）

十二、未来展望

12.1 技术演进方向

1. 多模态能力增强：

原生支持图像生成（DALL-E, Midjourney）
视频理解与生成
语音克隆与合成

2. 边缘计算优化：

支持更多本地 LLM（Llama, Mistral）
模型量化与加速
离线模式增强

3. 协作能力提升：

Multi-Agent 协作框架
Agent 之间的任务委派
分布式会话管理

4. 安全性强化：

端到端加密通信
零知识证明
联邦学习支持

12.2 生态系统建设

插件市场：

官方插件仓库
社区贡献的插件
插件评级与审核机制

技能商店：

预配置的技能包
行业特定的技能集
技能组合推荐

模板库：

常见场景的配置模板
最佳实践指南
案例研究

12.3 社区发展

Clawdbot 是一个开源项目，欢迎社区贡献：

贡献方式：

提交 Bug 报告和功能请求
贡献代码（新功能、Bug 修复）
编写文档和教程
分享使用案例

社区资源：

GitHub: https://github.com/clawdbot/clawdbot
Discord: https://discord.gg/clawd
文档: https://docs.clawd.bot

十三、总结

Clawdbot 是一个野心勃勃的项目，它试图解决一个核心问题：如何让 AI 助手真正融入我们的日常工作流。

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

无缝集成：在你已经使用的消息平台上直接与 AI 交互，无需切换应用
隐私保护：所有数据都存储在本地，你完全掌控自己的信息
高度可定制：从模型选择到工具配置，从人格设定到技能扩展，一切都可以按需调整
跨设备协同：手机、电脑、平板，所有设备都可以成为 AI 助手的"手脚"
开放生态：插件系统、技能系统、Hooks 系统，为社区创新提供了无限可能

技术亮点回顾

架构设计：

单一 Gateway 控制平面，简化了系统复杂度
WebSocket 协议设计精良，支持双向通信和事件推送
统一的消息抽象，屏蔽了不同平台的差异

安全性：

多层防护机制，从网络到应用层层把关
沙箱隔离，确保不受信任的输入不会危害系统
审计与监控，让每个操作都有迹可循

可扩展性：

插件系统支持第三方扩展
技能系统让非开发者也能定制功能
Hooks 系统实现事件驱动的自动化

性能优化：

连接池与资源复用
智能缓存策略
精细的并发控制

适用场景

Clawdbot 特别适合以下场景：

个人用户：

知识管理（笔记整理、文档检索）
日程管理（提醒、任务跟踪）
信息聚合（新闻摘要、邮件筛选）
智能家居控制

团队协作：

技术支持机器人（文档查询、问题解答）
项目管理助手（任务创建、进度跟踪）
代码审查助手（自动化检查、建议生成）

开发者：

API 测试与调试
日志分析与监控
自动化运维任务

研究人员：

文献检索与总结
数据分析与可视化
实验记录与管理

学习建议

如果你想深入了解 Clawdbot，建议按以下路径学习：

入门阶段：

阅读官方文档的 Getting Started
本地安装并运行基础配置
尝试在一个消息平台上使用

进阶阶段：

研究 Gateway 协议和架构设计
配置多个消息平台和 Agent
编写自定义技能

高级阶段：

阅读源码，理解核心实现
开发插件扩展功能
贡献代码到社区

最后的思考

Clawdbot 的设计哲学值得我们深思：

本地优先 vs 云服务：在隐私日益重要的今天，本地运行的 AI 助手可能是更好的选择。虽然牺牲了一些便利性（需要自己维护），但换来了完全的数据掌控权。

统一接口 vs 原生体验：Clawdbot 选择了统一接口，这意味着在不同平台上的体验是一致的。但这也意味着无法充分利用每个平台的独特功能。这是一个权衡。

开放生态 vs 封闭系统：通过插件和技能系统，Clawdbot 构建了一个开放的生态。这让社区可以贡献力量，但也增加了维护的复杂度。

类型安全 vs 灵活性：项目大量使用 TypeScript 和运行时类型检查，这提高了代码质量，但也增加了开发成本。对于一个需要快速迭代的项目，这是否值得？

这些问题没有标准答案，但 Clawdbot 的选择为我们提供了一个参考。

写在最后

Clawdbot 不仅仅是一个技术项目，它代表了一种愿景：AI 助手应该是你的私人助理，而不是某个公司的数据收集工具。

在这个 AI 快速发展的时代，我们需要更多像 Clawdbot 这样的项目------开源、透明、尊重隐私、赋能用户。

如果你对这个项目感兴趣，不妨：

Star 项目，关注最新进展
尝试部署一个实例，体验一下
加入社区，分享你的想法和经验
贡献代码，让项目变得更好

最后，用 Clawdbot 的口号结束这篇文章：

"EXFOLIATE! EXFOLIATE!" 🦞

（是的，这只太空龙虾正在用它独特的方式，改变我们与 AI 交互的未来。）

参考资源

官方网站 : https://clawd.bot/
GitHub 仓库: https://github.com/clawdbot/clawdbot

更多AIGC文章

RAG技术全解：从原理到实战的简明指南

更多VibeCoding文章

当 AI 助手遇上全平台消息：Clawdbot 的架构奇遇记

引子：一个不太一样的 AI 助手

一、架构全景：一个 Gateway 统治所有

1.1 核心设计理念

1.2 技术栈选型

二、Gateway：系统的心脏

2.1 WebSocket 协议设计

2.2 请求-响应模式

2.3 事件推送机制

2.4 多租户与会话隔离

三、消息路由：从 WhatsApp 到 Agent

3.1 统一的消息抽象

3.2 智能路由策略

3.3 会话管理

四、AI Agent 运行时

4.1 工作空间设计

4.2 工具系统

4.3 沙箱隔离

4.4 流式响应与分块

五、跨平台节点系统

5.1 节点架构

列出待配对的节点

批准节点

5.2 Canvas 系统

六、安全性设计

6.1 多层防护

6.2 审计与监控

七、性能优化

7.1 连接池与复用

7.2 缓存策略

7.3 并发控制

八、可观测性

8.1 结构化日志

8.2 健康检查

8.3 指标收集

九、扩展性设计

9.1 插件系统

9.2 技能系统

9.3 Hooks 系统

十、部署与运维

10.1 部署选项

10.2 守护进程管理

10.3 配置管理

10.4 备份与恢复

十一、实战案例

案例 1：个人知识管理助手

案例 2：团队协作机器人

案例 3：智能家居控制

十二、未来展望

12.1 技术演进方向

12.2 生态系统建设

12.3 社区发展

十三、总结

技术亮点回顾

适用场景

学习建议

最后的思考

写在最后

参考资源