Clawdbot Telegram 整合

Clawdbot Telegram 整合概述

Clawdbot Telegram 整合讓您可以使用透過 grammY 的 Bot API 將個人 AI 助手連接到 Telegram。此功能已準備好用於機器人私訊和群組，預設使用長輪詢，並支援可選的 webhook。

為什麼要將 Clawdbot 與 Telegram 搭配使用？

Telegram 提供強大的機器人 API 和隱私功能。將 Clawdbot 與 Telegram 整合可提供：

快速設定（初學者）

1. 使用 @BotFather 建立機器人（直接連結）
2. 確認帳號正是 @BotFather，然後複製令牌
3. 透過環境變數（TELEGRAM_BOT_TOKEN=...）或設定檔（channels.telegram.botToken）設定令牌
4. 啟動閘道
5. 私訊存取預設為配對模式；首次接觸時批准配對碼

最小設定：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing"
    }
  }
}

設定 Clawdbot Telegram

前置條件

在將 Clawdbot 連接到 Telegram 之前，請確保您具備：

• 已在您的裝置上安裝 Clawdbot
• 一個 Telegram 帳戶
• 從 @BotFather 取得的 Telegram Bot Token

步驟 1：建立 Telegram 機器人

透過 Telegram 的 BotFather 建立機器人：

1. 開啟 Telegram 並與 @BotFather 聊天（直接連結）
2. 確認帳號正是 @BotFather
3. 執行 /newbot，然後按照提示操作（名稱 + 以 bot 結尾的使用者名稱）
4. 複製令牌並安全保存

可選的 BotFather 設定：

• /setjoingroups — 允許/禁止將機器人加入群組
• /setprivacy — 控制機器人是否可以看到所有群組訊息

步驟 2：設定令牌

透過環境變數或設定檔設定令牌：

環境變數：

TELEGRAM_BOT_TOKEN=123:abc

設定檔（~/.clawdbot/clawdbot.json）：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

如果同時設定了環境變數和設定檔，設定檔優先。

步驟 3：啟動閘道

clawdbot gateway --port 18789

當令牌被解析（優先設定檔，環境變數作為備用）時，Telegram 會啟動。

步驟 4：驗證連線

檢查您的 Clawdbot Telegram 狀態：

clawdbot channels status telegram

令牌 + 隱私 + 權限

令牌建立（BotFather）

• /newbot 建立機器人並返回令牌（請保密）
• 如果令牌洩露，請透過 @BotFather 撤銷/重新生成並更新您的設定

群組訊息可見性（隱私模式）

Telegram 機器人預設為隱私模式，這會限制它們接收哪些群組訊息。選項：

1. 使用 /setprivacy 禁用隱私模式
2. 將機器人設為群組管理員（管理員機器人會接收所有訊息）

注意：當您切換隱私模式時，Telegram 要求從每個群組中移除並重新加入機器人才能使變更生效。

群組權限（管理員權限）

管理員狀態在群組內設定（Telegram UI）。管理員機器人總是接收所有群組訊息。

Clawdbot Telegram 功能

運作方式

• 入站訊息被標準化為共享頻道信封，包含回覆上下文和媒體佔位符
• 群組回覆預設需要提及（原生 @提及或設定的模式）
• 回覆總是路由回同一個 Telegram 聊天
• 長輪詢使用 grammY runner 進行每個聊天的順序處理

草稿串流

Clawdbot 可以使用 sendMessageDraft 在 Telegram 私訊中串流部分回覆。

要求：

• 在 @BotFather 中為機器人啟用執行緒模式（論壇主題模式）
• 僅限私人聊天執行緒
• channels.telegram.streamMode 未設定為 "off"

草稿串流僅限私訊；Telegram 不支援群組或頻道中的此功能。

格式化（Telegram HTML）

• 出站 Telegram 文字使用 parse_mode: "HTML"
• 類 Markdown 輸入被渲染為 Telegram 安全的 HTML
• 來自模型的原始 HTML 會被轉義以避免 Telegram 解析錯誤

指令

Clawdbot Telegram 支援自訂指令：

Clawdbot Telegram 設定

完整設定範例

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

存取控制（私訊 + 群組）

私訊存取：

• dmPolicy: "pairing" — 未知發送者會收到配對碼；透過 CLI 批准
• dmPolicy: "allowlist" — 僅回應允許清單中的使用者
• dmPolicy: "open" — 回應所有人（不建議）

群組存取：

• 設定 channels.telegram.groups，以群組 ID 或 "*" 作為所有群組的鍵
• 使用 requireMention: true 僅在被提及時回應

查找您的 Telegram 使用者 ID

使用 @userinfobot 或類似機器人來取得您的數字 Telegram 使用者 ID。

Clawdbot Telegram 憑證儲存

Clawdbot 安全地儲存 Telegram 憑證：

~/.clawdbot/credentials/telegram/bot_token
~/.clawdbot/credentials/telegram/session.json

您的 Clawdbot Telegram 資料保留在您的本地機器上。

Clawdbot Telegram 故障排除

機器人無回應

如果您的 Clawdbot Telegram 機器人無回應：

1. 驗證令牌：clawdbot channels verify telegram
2. 使用 @BotFather 檢查機器人狀態
3. 查看日誌：cat /tmp/clawdbot/telegram.log

群組啟用

在群組中啟用 Clawdbot：

透過設定（建議）：

{
  "channels": {
    "telegram": {
      "groups": {
        "<group_id>": { "requireMention": true }
      }
    }
  }
}

透過指令（會話級別）： 在群組聊天中使用 /activate。

取得群組聊天 ID

將群組中的訊息轉發給 @userinfobot 或使用 Telegram API。

Clawdbot Telegram 最佳實踐

1. 使用配對模式：預設使用配對碼確保安全
2. 設定隱私模式：根據您的需求在 @BotFather 中設定
3. 處理速率限制：實作適當的速率限制
4. 監控使用情況：追蹤 Clawdbot Telegram 機器人分析

下一步

• Clawdbot WhatsApp 整合 - 將 Clawdbot 連接到 WhatsApp
• Clawdbot Discord 整合 - 在 Discord 上設定 Clawdbot
• Clawdbot 設定指南 - 完整安裝指南