概念

Plugins 是 OpenClaw 與外部世界的「介面」— 接收訊息、發送回覆。

主要 channel plugins：

Plugin	用途
WhatsApp	透過 WhatsApp Web 連接
Telegram	Bot API 或 MTProto
Discord	Bot token
Signal	signal-cli
Slack	Bot token

Plugin 的角色

外部世界                    OpenClaw
─────────────────────────────────────────
                    ┌─────────────┐
Telegram ──────────▶│   Plugin    │──────▶ Gateway
用戶發訊息          │ (telegram)  │        路由到 Agent
                    └─────────────┘
                           │
                           ▼
                    回覆訊息給用戶

核心代碼

1. Plugin 生命週期

// Plugin 啟動流程
async function startPlugin(config) {
  const plugin = plugins[config.channel];
  
  // 1. 初始化連接
  await plugin.connect({
    token: config.token,
    account: config.account
  });
  
  // 2. 監聽訊息
  plugin.on('message', async (msg) => {
    // 3. 轉發給 Gateway
    await gateway.handleIncomingMessage({
      channel: config.channel,
      from: msg.sender,
      text: msg.text,
      metadata: msg.metadata
    });
  });
  
  // 4. 監聽 Gateway 回覆
  gateway.on('outbound', async (reply) => {
    if (reply.channel === config.channel) {
      await plugin.send(reply.to, reply.text);
    }
  });
}

2. Telegram Plugin

// Telegram 使用 Bot API
const bot = new TelegramBot(token);

bot.on('message', async (msg) => {
  await gateway.handleIncomingMessage({
    channel: 'telegram',
    from: msg.from.id.toString(),
    text: msg.text,
    metadata: {
      chatId: msg.chat.id,
      messageId: msg.message_id,
      chatType: msg.chat.type  // 'private' | 'group'
    }
  });
});

// 發送回覆
async function sendTelegram(chatId, text) {
  await bot.sendMessage(chatId, text, {
    parse_mode: 'Markdown'
  });
}

3. WhatsApp Plugin

// WhatsApp 使用 Baileys (WhatsApp Web)
const sock = makeWASocket({
  auth: state,
  printQRInTerminal: true  // 第一次需要掃 QR code
});

sock.ev.on('messages.upsert', async ({ messages }) => {
  for (const msg of messages) {
    if (msg.key.fromMe) continue;  // 忽略自己發的
    
    await gateway.handleIncomingMessage({
      channel: 'whatsapp',
      from: msg.key.remoteJid,
      text: msg.message?.conversation || '',
      metadata: {
        messageId: msg.key.id
      }
    });
  }
});

WhatsApp 特殊性：

需要定期重新連接（session 會過期）
群組訊息需要額外處理
不能太頻繁發送（會被 ban）

4. 設定範例

// openclaw.json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "env:TELEGRAM_BOT_TOKEN",
      "allowFrom": ["9876543210"],      // 只允許特定用戶
      "mentionTriggers": ["@mybot"],    // 群組中 @mention 才回覆
      "groupPolicy": "mention-only"
    },
    
    "whatsapp": {
      "enabled": true,
      "account": "personal",
      "allowFrom": ["+1234567890"],
      "sessionRefreshHours": 12         // 每 12 小時刷新
    }
  }
}

5. 訊息路由（Bindings）

{
  "bindings": [
    {
      "agentId": "my-assistant",
      "match": {
        "channel": "whatsapp",
        "from": "+1234567890"
      }
    },
    {
      "agentId": "dev-agent",
      "match": {
        "channel": "telegram",
        "from": "*"  // 所有 telegram 用戶
      }
    }
  ]
}

邏輯：

訊息進來 → 匹配 binding → 找到對應 agent
沒有匹配 → 使用 default agent

💡 關鍵洞察

Plugin 只負責「收發」
- 不做 AI 決策
- 純粹是訊息轉換器
- Gateway 決定怎麼處理
WhatsApp 最複雜
- 基於 WhatsApp Web，不是官方 API
- Session 會過期，需要定期刷新
- 可能被 ban（發太快/太多）
Telegram 最穩定
- 官方 Bot API
- 不會被 ban
- 支援 inline buttons、reactions
Binding 是路由規則
- 決定「誰用哪個 agent」
- 可以按 channel、用戶、群組配置
- 靈活但要小心別漏掉

🔗 核心檔案

Channel 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/channels/
Telegram 設定：/opt/homebrew/lib/node_modules/openclaw/docs/channels/telegram.md
WhatsApp 設定：/opt/homebrew/lib/node_modules/openclaw/docs/channels/whatsapp.md

明天： Cron 系統（schedule, payload, delivery）

Day 5: Plugin 架構（Telegram/WhatsApp 如何整合）