如何快速串接 Telegram Bot API

想在 Telegram 上自動化你的工作流程，最煩人的往往不是寫程式碼，而是處理 API 連線、處理 Webhook 或是搞定那堆繁瑣的權限設定。如果你曾經為了機器人收不到群組訊息而抓狂，這篇指南會幫你省下不少時間。

我們將使用 grammY 驅動的架構，預設採用 Long Polling 模式，讓你不用處理複雜的 Webhook 就能直接讓機器人上線。

需要準備的東西

在開始之前，請確認你手邊有這些東西：

一個 Telegram 帳號
已經安裝並準備好運行的 openclaw 環境
存取 @BotFather 的權限

快速開始

跟著這四個步驟，五分鐘內就能完成基本設定。

1. 在 BotFather 取得 Token

打開 Telegram，搜尋 @BotFather（請務必確認帳號後綴完全一致）。輸入 /newbot 並按照指示操作，完成後請把產生的 token 存好。

2. 設定 Token 與私訊政策

在你的設定檔中加入以下內容。你可以直接在 JSON 裡面寫死 Token，或是使用環境變數 TELEGRAM_BOT_TOKEN 作為預設帳號的備案。

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

3. 啟動 Gateway 並通過配對

執行以下指令來啟動服務並核准你的第一個私訊連線。請注意，配對碼（Pairing code）會在 1 小時後過期。

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

4. 處理群組設定

將機器人加入你的群組，接著調整 channels.telegram.groups 和 groupPolicy 來符合你的存取模型。

注意： Token 的解析順序會考量帳號設定。實務上，設定檔中的值優先權高於環境變數，且 TELEGRAM_BOT_TOKEN 只會套用到預設帳號。

疑難排解

如果你在設定過程中遇到問題，通常跟 Telegram 的隱私設定有關：

機器人收不到群組訊息？

Telegram 機器人預設會開啟 Privacy Mode，這會限制它能看到的訊息。如果你需要機器人接收所有訊息，你有兩個選擇：

透過 /setprivacy 停用隱私模式。
直接將機器人設為群組管理員（Admin）。

小提醒： 當你切換隱私模式後，記得把機器人從群組踢掉再重新加入，這樣 Telegram 才會套用新的設定。

權限調整

你可以直接在 BotFather 透過以下指令快速調整：

/setjoingroups：設定是否允許機器人被加入群組。
/setprivacy：設定機器人在群組中的可見度。

如果你需要機器人具備管理員權限，請直接在 Telegram 群組設定中操作。管理員身分的機器人可以接收所有訊息，這對需要全時運作的群組行為非常有幫助。

如果你在設定過程中卡住了，可以詢問 AI Setup Assistant 獲取即時協助。

下一步

寫完一個 Telegram Bot 最怕的就是它變成「萬人迷」——不是因為受歡迎，而是因為被各種不相干的人私訊，或者在群組裡被亂用。如果你也遇過 Bot 被騷擾或權限難以控管的問題，這篇會幫你理清如何透過設定檔精確控管誰能跟你的 Bot 交流。

需要準備的東西

一個現有的 Telegram bot token
已安裝並能執行的 openclaw 環境
你的 Telegram 帳號（用於測試存取權限）

快速開始

想在 5 分鐘內限制你的 Bot 只聽你的話？按照這個路徑走：

設定 DM Policy：在設定檔中將 channels.telegram.dmPolicy 設為 allowlist。
獲取你的 ID：私訊你的 Bot，然後在終端機執行 openclaw logs --follow 找到 from.id。
填入白名單：將該 ID 填入 channels.telegram.allowFrom 欄位。
重啟服務：現在除了你之外，沒人可以私訊這個 Bot。

私訊存取控制與啟用

你可以透過 channels.telegram.dmPolicy 來決定誰可以私訊你的 Bot，可選的模式有：

pairing (預設值)
allowlist
open (這需要 allowFrom 包含 "*" 才能運作)
disabled

而 channels.telegram.allowFrom 欄位接受數字 ID 或使用者名稱。系統會自動處理並正規化 telegram: 或 tg: 前綴。

尋找你的 Telegram user ID

如果你不想使用第三方機器人（比較安全且注重隱私），推薦這兩個方法：

透過 Log 查看：直接私訊你的 Bot，然後執行 openclaw logs --follow，從輸出的 JSON 中讀取 from.id。
官方 Bot API 方法：

curl "https://api.telegram.org/bot<bot_token>/getUpdates"

如果你不在意隱私，也可以直接在 Telegram 搜尋 @userinfobot 或 @getidsbot 來獲取 ID。

群組政策與白名單

群組的控制由兩個獨立的機制組成：

哪些群組被允許 (channels.telegram.groups)
- 如果沒設定 groups：代表允許所有群組。
- 如果有設定 groups：它會作為白名單運作（需填入明確的 ID 或 "*"）。
誰可以在群組裡傳訊息給 Bot (channels.telegram.groupPolicy)
- open
- allowlist (預設值)
- disabled

系統會使用 groupAllowFrom 來過濾群組內的發送者。如果沒設定，Telegram 會自動退而求其次使用 allowFrom 的設定。

範例：允許特定群組中的任何成員使用 Bot

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

Mention 行為設定

在群組中，Bot 預設需要被 mention 才會回應。Mention 的觸發可以來自：

原生的 @botusername 標註。
設定在 agents.list[].groupChat.mentionPatterns 或 messages.groupChat.mentionPatterns 中的自定義模式。

如果你想在對話中臨時切換觸發方式，可以使用 Session 等級的指令（僅影響當前會話）：

/activation always
/activation mention

如果你希望設定是永久生效的，請使用設定檔。

持久化設定範例：

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

疑難排解

找不到群組聊天 ID？

你可以透過以下幾種方式獲取：

將群組訊息轉傳給 @userinfobot 或 @getidsbot。
執行 openclaw logs --follow 並在群組發言，讀取 chat.id。
檢查 Bot API 的 getUpdates 回傳內容。

Bot 在群組中不理人？

檢查 groupPolicy 是否設定為 allowlist 但你不在名單內。
檢查 requireMention 是否開啟，如果是，請確保訊息中包含 @botusername。

如果你在設定過程遇到任何困難，可以詢問 AI Setup Assistant 獲取即時幫助。

下一步

做 Telegram Bot 最煩人的就是訊息路由亂跳，或是群組裡的討論串（Topics）搞得 Session 亂七八糟。如果你正在處理複雜的對話邏輯，理解 Gateway 的底層運行行為能幫你省下不少 Debug 的時間，讓你清楚訊息是怎麼被標準化並送往正確的地方。

需要準備的東西

根據源文檔，在開始調整運行行為前，你需要確保：

已經配置好 Telegram Gateway process
了解 agents.defaults.maxConcurrent 的配置位置
使用 OpenClaw 進行訊息路由

Quick Start: 核心運行邏輯

這裡幫你整理了 Telegram Gateway 在運行時的幾個關鍵行為，讓你 5 分鐘掌握重點：

1. 路由與所有權

Telegram 是由 Gateway process 負責擁有的。它的路由邏輯非常直覺且固定：從 Telegram 進來的訊息，回覆時就會直接回到 Telegram。這意味著你的模型不需要自己去挑選 Channel，系統會幫你處理好。

2. 訊息標準化 (Normalization)

所有進來的訊息都會被標準化成一個共用的 Channel Envelope。這個 Envelope 會包含：

Reply metadata（回覆元數據）
Media placeholders（媒體佔位符）

3. Session 隔離機制

為了確保對話不會串在一起，Gateway 採用了嚴格的隔離策略：

群組 Session: 直接透過 Group ID 進行隔離。
論壇主題 (Forum Topics): 會在 ID 後面加上 :topic:<threadId>，確保不同主題之間的 Session 是獨立運作的。
私訊 (DM): 如果訊息帶有 message_thread_id，OpenClaw 會使用感知 Thread 的 Session Key 來路由，並在回覆時保留 Thread ID。

4. 併發與效能控制

Long polling 是透過 grammY runner 執行的，它支援每個 Chat 或每個 Thread 的順序處理。如果你需要調整整體的併發量，可以透過 agents.defaults.maxConcurrent 來設定 runner sink 的併發限制。

疑難排解

以下是根據文檔整理的常見問題：

為什麼我設定了 sendReadReceipts 卻沒有效果？ 因為 Telegram Bot API 本身並不支援已讀回執（Read-receipts），所以 sendReadReceipts 這個參數在 Telegram Gateway 中是不起作用的。

訊息回覆時 Thread ID 遺失了怎麼辦？ 請確保你的訊息有正確攜帶 message_thread_id。OpenClaw 會自動識別並保留這些 ID，確保回覆能精確回到原本的 Thread。

如果你在設定過程中遇到任何問題，可以直接詢問 AI Setup Assistant。

下一步

你是不是也遇過這種狀況：開發 Telegram 機器人時，Markdown 解析經常噴錯，或是想讓機器人回話更有「人味」卻卡在打字狀態（Typing status）的同步？處理這些瑣碎的 API 細節、處理論壇主題（Topics）或是管理指令選單，往往比開發核心邏輯還要耗時。

這篇指南會幫你搞定 OpenClaw 在 Telegram 上的所有進階配置，讓你的機器人運作得更像一個真正的原生應用，而不是冷冰冰的腳本。

需要準備的東西

已配置好的 Telegram Bot Token
OpenClaw 運行環境
基礎的 JSON 修改能力

快速開始

想在 5 分鐘內提升你的機器人體驗？試試這兩個最推薦的配置：

開啟 Draft Streaming: 讓機器人在思考時，直接在對話框上方顯示草稿預覽，用戶體驗極佳。
自動註冊指令: 在 config 中加入 commands.native: "auto"，OpenClaw 會在啟動時幫你把指令選單同步到 Telegram 官方選單。

Telegram 功能詳解

Draft streaming (草稿串流)

OpenClaw 可以透過 Telegram 的草稿泡泡 (sendMessageDraft) 實現回覆內容的即時串流。

使用條件：

channels.telegram.streamMode 未設為 "off"（預設為 "partial"）
必須是私訊 (Private chat)
傳入的 update 包含 message_thread_id
機器人已啟用 Topics 功能（getMe().has_topics_enabled）

模式選項：

off: 關閉草稿串流
partial: 根據部分文本頻繁更新草稿
block: 使用 channels.telegram.draftChunk 設定的區塊大小進行更新

block 模式的預設值：

minChars: 200
maxChars: 800
breakPreference: "paragraph"

注意 maxChars 會受到 channels.telegram.textChunkLimit 的限制。草稿串流僅限私訊使用，群組或頻道不支援。如果你偏好早點看到真正的 Telegram 訊息而非草稿更新，請改用 channels.telegram.blockStreaming: true。

Telegram 專屬推理串流： 使用 /reasoning stream 指令，機器人在生成時會將推理過程傳送到草稿泡泡，最終答案則不包含推理文字。

格式化與 HTML Fallback

輸出的文字預設使用 Telegram parse_mode: "HTML"。

類 Markdown 的文字會被渲染成符合 Telegram 安全規範的 HTML。
模型輸出的原始 HTML 會被轉義（escaped），減少 Telegram 解析失敗的機率。
如果 Telegram 拒絕解析後的 HTML，OpenClaw 會自動退回到純文字（plain text）模式重試。

連結預覽預設開啟，你可以透過 channels.telegram.linkPreview: false 關閉它。

原生指令與自定義指令

OpenClaw 啟動時會透過 setMyCommands 處理選單註冊。

原生指令預設值：

commands.native: "auto" 會為 Telegram 啟用原生指令。

新增自定義指令選單：

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

規則與限制：

名稱會自動正規化（移除開頭的 / 並轉為小寫）。
格式要求：a-z, 0-9, _，長度 1 到 32 字元。
自定義指令不能覆蓋原生指令。
衝突或重複的指令會被跳過並記錄在日誌中。
自定義指令僅作為選單項目顯示，不會自動實作行為。

裝置配對指令 (device-pair plugin)： 安裝外掛後：

/pair 生成設定代碼。
將代碼貼入 iOS App。
/pair approve 核准待處理的請求。詳細資訊請參考：Pairing。

Inline buttons (內嵌按鈕)

你可以配置內嵌鍵盤的適用範圍：

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

範圍選項： off, dm, group, all, allowlist (預設)。

訊息動作範例：

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

點擊按鈕後，callback_data 會以 callback_data: <value> 的形式傳回給 agent。

訊息動作 (Actions)

Telegram 支援多種工具動作：

sendMessage, react, deleteMessage, editMessage。

你可以透過 channels.telegram.actions 來管控權限，例如 sticker 預設是關閉的。關於 Reaction 的移除邏輯，請參考 /tools/reactions。

回覆執行緒標記 (Reply threading tags)

OpenClaw 支援在輸出的內容中使用標記來指定回覆對象：

[[reply_to_current]]: 回覆觸發該次對話的訊息。
[[reply_to:<id>]]: 回覆特定的 Telegram 訊息 ID。

論壇主題 (Forum topics)

針對論壇類型的超大群組：

Session keys 會附加 :topic:<threadId>。
回覆與打字狀態會精確定位到該 Topic。
Topic 會繼承群組設定（如 requireMention, skills 等），除非另行覆蓋。
特例：一般主題 (threadId=1) 在發送訊息時會省略 message_thread_id，但打字動作仍會包含。

影音與貼圖 (Stickers)

音訊：

預設發送為音訊檔案。
在回覆中使用 [[audio_as_voice]] 標記可強制轉為語音訊息 (Voice note)。

影片：

支援發送為影片檔案或影片訊息 (Video notes)。注意影片訊息不支援說明文字（Caption）。

貼圖：

靜態 WEBP 會被下載處理（佔位符為 <media:sticker>）。
動態 TGS 與影片 WEBM 會被跳過。
貼圖資訊會快取在 ~/.openclaw/telegram/sticker-cache.json 以減少 vision API 調用。

Webhook 模式

預設使用 Long polling。若要改用 Webhook：

設定 channels.telegram.webhookUrl 與 channels.telegram.webhookSecret。
本地監聽預設綁定在 0.0.0.0:8787。

疑難排解

setMyCommands failed: 這通常代表你的伺服器連向 api.telegram.org 的 DNS 或 HTTPS 連線被阻擋了。
影片訊息沒有文字: Telegram 官方限制 Video notes 不能帶 Caption，OpenClaw 會將文字拆分成另一條訊息發送。
貼圖沒反應: 確認你已在配置中將 channels.telegram.actions.sticker 設為 true。
Reaction 更新沒帶 Thread ID: 這是 Telegram API 的限制。非論壇群組會導向群組 Session，論壇群組則會導向 General Topic (:topic:1)。

如果你在配置過程中遇到任何問題，可以直接詢問我們的 AI Setup Assistant。

下一步

每次開發 Bot 最煩的就是明明在私訊測試都好好的，一丟進群組就變「啞巴」，或是原本跑得順順的，突然因為網路環境變動就開始報錯。這種查不出原因的挫折感，每個開發者都懂。

這篇文章整理了 Telegram Bot 在實際運行中常見的坑，幫你快速定位問題，不再對著 Log 發呆。

需要準備的東西

在開始排查之前，請確保你手邊有這些東西（根據源文件需求）：

BotFather 的存取權限（用於調整隱私設定）
openclaw CLI 工具
Node.js 22+ 環境（如果你遇到特定的網路或 Fetch 問題）
你的 Telegram Bot Token

Quick Start：診斷三部曲

如果你發現 Bot 運作不正常，請先執行這三步最快的路徑：

檢查狀態：執行 openclaw channels status 查看設定是否符合預期。
追蹤日誌：使用 openclaw logs --follow 觀察 Bot 跳過訊息的具體原因。
強制測試：在群組中發送 /activation always 進行快速的 Session 測試。

疑難排解

Bot 對「沒被標記」的群組訊息沒反應

如果你的設定是 requireMention=false，但 Bot 還是不理人，通常是 Telegram 的隱私模式在擋：

找 BotFather：輸入 /setprivacy -> 選擇 Disable。
重要步驟：調整完後，必須將 Bot 從群組移除再重新加入才會生效。
使用 openclaw channels status：它會警告你目前的配置是否與群組訊息可見性衝突。
針對特定群組：使用 openclaw channels status --probe 檢查具體的數字群組 ID；注意，萬用字元 "*" 無法進行成員資格探測。

Bot 完全看不到群組訊息

當 Bot 連訊息都收不到時，請檢查：

設定檔檢查：如果 channels.telegram.groups 存在，該群組必須被列在清單中，或者包含 "*" 萬用字元。
成員身份：確認 Bot 確實還在群組裡。
日誌追蹤：執行 openclaw logs --follow 看看是否有訊息被過濾或跳過的紀錄。

指令部分運作或完全失效

如果指令沒反應，通常跟權限有關：

身份授權：確認發送者的身份已通過 Pairing 或列在 allowFrom 中。
策略限制：即使群組政策（group policy）設為 open，指令的授權邏輯依然適用。
API 錯誤：如果遇到 setMyCommands failed，通常代表你的伺服器連不到 api.telegram.org，請檢查 DNS 或 HTTPS 連線。

輪詢（Polling）或網路不穩定

網路問題有時很玄，特別是跟環境有關：

Node 22+ 陷阱：如果你使用 Node 22 以上版本並搭配自定義的 fetch 或 proxy，可能會因為 AbortSignal 類型不匹配而觸發立即中止（abort）行為。
IPv6 優先問題：有些主機商會優先解析 api.telegram.org 到 IPv6；如果你的環境 IPv6 出口不通，就會導致間歇性的 API 失敗。
驗證 DNS 答案：

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

更多詳細資訊可以參考：Channel troubleshooting。

Telegram Config 參考索引

以下是 Telegram 相關的高頻設定欄位，調整時可以快速對照：

啟動與認證：enabled, botToken, tokenFile, accounts.*
存取控制：dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*
指令選單：commands.native, customCommands
回覆模式：replyToMode
串流設定：streamMode, draftChunk, blockStreaming
格式與傳送：textChunkLimit, chunkMode, linkPreview, responsePrefix
媒體與網路：mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
Webhook：webhookUrl, webhookSecret, webhookPath
功能開關：capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
反應設定：reactionNotifications, reactionLevel
歷史紀錄：configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

詳細說明請見：Configuration reference - Telegram

還是搞不定？試試我們的 AI Setup Assistant 幫你即時診斷。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。