Telegram

Telegram Bot 預設使用隱私模式，這會限制它們可接收的群組訊息。

若要查看所有群組訊息，請選擇以下任一方式：

• 透過 /setprivacy 停用隱私模式，或
• 將機器人設為群組管理員。

切換隱私模式後，請在每個群組中移除再重新加入機器人，讓 Telegram 套用變更。

管理員狀態由 Telegram 群組設定控制。管理員機器人會收到所有群組訊息，適合需要持續運作的群組行為。

• /setjoingroups — 允許／拒絕加入群組
• /setprivacy — 群組可見性行為

如果你偏好使用圖形介面而非聊天命令，也可以在 BotFather 的網頁應用程式中使用相同的設定。

OpenClaw 會在直接聊天、群組和主題中即時串流部分回覆：先傳送預覽訊息，接著重複呼叫 editMessageText，最後就地完成。

• channels.telegram.streaming 可設為 off | partial | block | progress（預設：partial）
• 簡短的初始答案預覽會經過防抖處理；如果執行仍在進行，則會在有限延遲後具體呈現
• progress 會為工具進度保留一則可編輯的狀態草稿；若答案活動早於工具進度抵達，則顯示穩定的狀態標籤；完成時清除該草稿，並將最終答案作為一般訊息傳送
• streaming.preview.toolProgress 控制工具／進度更新是否重複使用同一則經編輯的預覽訊息（預覽串流啟用時預設為 true）
• streaming.preview.commandText 控制這些行內的命令／執行詳細資訊：raw（預設）或 status（僅顯示工具標籤）
• streaming.progress.commentary（預設：false）可選擇在暫時的進度草稿中加入助理評論／前言文字
• 系統會偵測舊版 channels.telegram.streamMode、布林值 streaming，以及已淘汰的原生草稿預覽鍵；請執行 openclaw doctor --fix 以遷移它們

工具進度行是在工具執行期間顯示的簡短狀態更新（命令執行、檔案讀取、規劃更新、修補摘要，以及應用程式伺服器模式下的 Codex 前言／評論）。Telegram 預設會保持顯示這些內容（與 v2026.4.22+ 的已發布行為一致）。

保留答案預覽編輯，但隱藏工具進度行：

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "toolProgress": false }      }    }  }}

保持工具進度可見，但隱藏命令／執行文字：

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": { "commandText": "status" }      }    }  }}

progress 模式會顯示工具進度，但不會將最終答案編輯進該訊息。請將命令文字政策放在 streaming.progress 下：

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

streaming.mode: "off" 會停用預覽編輯，並抑制一般工具／進度訊息，而不是將其作為獨立狀態訊息傳送；核准提示、媒體和錯誤仍會透過一般最終傳遞路徑路由。streaming.preview.toolProgress: false 則只保留答案預覽編輯。

對於純文字回覆：簡短預覽會就地完成最終編輯；拆分為多則訊息的長篇最終內容會重複使用預覽作為第一個區塊，接著只傳送其餘部分；進度模式的最終內容會清除狀態草稿，並使用一般最終傳遞；如果在確認完成前最終編輯失敗，OpenClaw 會退回一般最終傳遞，並清理過時的預覽。對於複雜回覆（媒體承載內容），OpenClaw 一律退回一般最終傳遞並清理預覽。

預覽串流和區塊串流互斥——明確啟用區塊串流時，OpenClaw 會略過預覽串流以避免重複串流。

推理：/reasoning stream 會在生成期間將推理串流至即時預覽，接著在最終傳遞後刪除推理預覽（使用 /reasoning on 可讓它保持可見）。最終答案傳送時不包含推理文字。

傳出文字預設使用標準 Telegram HTML 訊息，可在目前的用戶端中閱讀：粗體、斜體、連結、程式碼、隱藏文字、引文——而非 Bot API 10.1 的僅限豐富內容區塊（原生表格、詳細資料、豐富媒體、公式）。

選擇啟用 Bot API 10.1 豐富訊息：

{channels: {telegram: {  richMessages: true,},},}

啟用時：系統會告知代理程式此機器人／帳號可使用豐富訊息；Markdown 文字會透過 OpenClaw 的 Markdown IR 轉譯為 Telegram 豐富 HTML；明確的豐富 HTML 承載內容會保留 Bot API 10.1 支援的標籤（標題、表格、詳細資料、豐富媒體、公式）；媒體說明文字仍使用 Telegram HTML 說明文字（豐富訊息不會取代說明文字，且說明文字上限為 1024 個字元）。

如此可避免模型文字使用 Telegram 的豐富 Markdown 符號，因此 $400-600K 之類的金額不會被解析為數學式。過長的豐富文字會依 Telegram 的限制自動拆分。超過 20 欄限制的表格會退回程式碼區塊。

預設：關閉，以維持用戶端相容性——部分目前的 Desktop、Web、Android 及第三方用戶端會將已接受的豐富訊息顯示為不支援。除非所有與機器人搭配使用的用戶端都能呈現這些訊息，否則請維持關閉。/status 會顯示目前工作階段的豐富訊息為開啟或關閉。

連結預覽預設為開啟。channels.telegram.linkPreview: false 會停用豐富文字的自動實體偵測。

Telegram 的命令選單會在啟動時透過 setMyCommands 註冊。commands.native: "auto" 會為 Telegram 啟用原生命令。

新增自訂命令選單項目：

{channels: {telegram: {  customCommands: [    { command: "backup", description: "Git 備份" },    { command: "generate", description: "建立圖片" },  ],},},}

規則：名稱會正規化（移除開頭的 /、轉為小寫）；有效模式為 a-z、0-9、_，長度 1-32；自訂命令不能覆寫原生命令；衝突／重複項目會被略過並記錄。

自訂命令僅是選單項目——不會自動實作行為。即使未顯示於 Telegram 選單中，輸入外掛／skill 命令時仍可運作。如果停用原生命令，內建命令會被移除；若已設定，自訂／外掛命令仍可註冊。

常見設定失敗：

• 經過裁減重試後，setMyCommands failed 並出現 BOT_COMMANDS_TOO_MUCH，表示選單仍然溢出；請減少外掛／skill／自訂命令，或停用 channels.telegram.commands.native。
• 當直接使用 Bot API curl 命令可正常運作，但 deleteWebhook、deleteMyCommands 或 setMyCommands 失敗並顯示 404: Not Found 時，通常表示 channels.telegram.apiRoot 被設為完整的 /bot<TOKEN> 端點。apiRoot 必須只設為 Bot API 根路徑；openclaw doctor --fix 會移除意外附加的 /bot<TOKEN>。
• getMe returned 401 表示 Telegram 拒絕了已設定的機器人權杖。請使用目前的 BotFather 權杖更新 botToken、tokenFile 或 TELEGRAM_BOT_TOKEN（預設帳號）；OpenClaw 會在輪詢前停止，因此不會將此問題回報為網路鉤子清理失敗。
• setMyCommands failed 並出現網路／擷取錯誤，通常表示通往 api.telegram.org 的傳出 DNS／HTTPS 遭到封鎖。

裝置配對命令（device-pair 外掛）

安裝後：

1. /pair 會產生設定代碼
2. 將代碼貼到 iOS 應用程式中
3. /pair pending 會列出待處理的要求（包括角色／範圍）
4. 核准：/pair approve <requestId>、/pair approve（唯一的待處理要求）或 /pair approve latest

如果裝置使用已變更的驗證詳細資訊（角色、範圍、公開金鑰）重試，先前的待處理要求會由具有新 requestId 的要求取代；核准前請重新執行 /pair pending。

更多詳細資訊：配對。

設定行內鍵盤範圍：

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

各帳號覆寫：

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

範圍：off、dm、group、all、allowlist（預設）。舊版 capabilities: ["inlineButtons"] 會對應至 "all"。

訊息動作範例：

{action: "send",channel: "telegram",to: "123456789",message: "選擇一個選項：",buttons: [[  { text: "是", callback_data: "yes" },  { text: "否", callback_data: "no" },],[{ text: "取消", callback_data: "cancel" }],],}

Mini App 按鈕範例：

{action: "send",channel: "telegram",to: "123456789",message: "開啟應用程式：",presentation: {blocks: [  {    type: "buttons",    buttons: [{ label: "啟動", web_app: { url: "https://example.com/app" } }],  },],},}

web_app 按鈕只能在使用者與機器人之間的私人聊天中運作。

未由已註冊的外掛互動處理常式認領的回呼點擊，會以文字傳遞給代理程式：callback_data: <value>。

動作：

• sendMessage（to、content、選用的 mediaUrl、replyToMessageId、messageThreadId）
• react（chatId、messageId、emoji）
• deleteMessage（chatId、messageId）
• editMessage（chatId、messageId、content 或 caption、選用的 presentation 行內按鈕；僅編輯按鈕時會更新回覆標記）
• createForumTopic（chatId、name、選用的 iconColor、iconCustomEmojiId）

易用別名：send、react、delete、edit、sticker、sticker-search、topic-create。

控制開關：channels.telegram.actions.sendMessage、deleteMessage、reactions、sticker（預設：停用）。edit、createForumTopic 和 editForumTopic 預設啟用，沒有專用開關。 執行階段傳送會使用啟動／重新載入時的有效設定／密鑰快照，因此動作路徑不會在每次傳送時重新解析 SecretRef 值。

移除反應的語意：/tools/reactions。

生成輸出中的明確回覆討論串標籤：

• [[reply_to_current]] — 回覆觸發訊息
• [[reply_to:<id>]] — 回覆特定訊息 ID

channels.telegram.replyToMode：off（預設）、first、all。

啟用回覆討論串且可取得原始文字／說明文字時，OpenClaw 會自動加入原生引用摘錄。Telegram 將原生引用文字限制為 1024 個 UTF-16 程式碼單位；較長的訊息會從開頭開始引用，若 Telegram 拒絕該引用，則退回為一般回覆。

off 僅停用隱含的回覆討論串；明確的 [[reply_to_*]] 標籤仍會生效。

論壇超級群組：主題工作階段金鑰會附加 :topic:<threadId>；回覆與輸入中狀態會以主題討論串為目標；主題設定路徑為 channels.telegram.groups.<chatId>.topics.<threadId>。

一般主題（threadId=1）是特殊情況：傳送訊息時會省略 message_thread_id（Telegram 會以 "thread not found" 拒絕 sendMessage(...thread_id=1)），但輸入中動作仍會包含 message_thread_id（實測顯示，這是顯示輸入中指示器的必要條件）。

除非覆寫，主題項目會繼承群組設定（requireMention、allowFrom、skills、systemPrompt、enabled、groupPolicy）。agentId 僅適用於主題，不會繼承群組預設值。topics."*" 會設定該群組中每個主題的預設值；確切的主題 ID 仍優先於 "*"。

個別主題的代理路由：每個主題都可以透過主題設定中的 agentId 路由至不同的代理，使其擁有自己的工作區、記憶與工作階段：

{  channels: {    telegram: {      groups: {        "-1001234567890": {          topics: {            "1": { agentId: "main" },      // 一般主題 -> main 代理            "3": { agentId: "zu" },        // 開發主題 -> zu 代理            "5": { agentId: "coder" }      // 程式碼審查 -> coder 代理          }        }      }    }  }}

接著，每個主題都會有自己的工作階段金鑰，例如 agent:zu:telegram:group:-1001234567890:topic:3。

持續性 ACP 主題繫結：論壇主題可以透過頂層型別化繫結（bindings[]，包含 type: "acp"、match.channel: "telegram"、peer.kind: "group"，以及如 -1001234567890:topic:42 的主題限定 ID）固定 ACP 控制框架工作階段。目前範圍限定於群組／超級群組中的論壇主題。請參閱 ACP 代理。

從聊天產生討論串繫結的 ACP：/acp spawn <agent> --thread here|auto 會將目前主題繫結至新的 ACP 工作階段；後續訊息會直接路由至該處，且 OpenClaw 會在主題中置頂產生確認訊息。需要 channels.telegram.threadBindings.spawnSessions（預設：true）。

範本情境會公開 MessageThreadId 和 IsForum。具有 message_thread_id 的私訊聊天會保留回覆中繼資料，但只有當 Telegram getMe 回報 has_topics_enabled: true 時，才會使用具討論串感知能力的工作階段金鑰。 已移除淘汰的 dm.threadReplies 和 direct.*.threadReplies 覆寫；BotFather 的討論串模式是唯一事實來源。執行 openclaw doctor --fix 以移除過時的設定鍵。

音訊訊息

Telegram 會區分語音訊息與音訊檔案。預設：音訊檔案行為；在代理回覆中加上 [[audio_as_voice]] 標籤，可強制以語音訊息傳送。傳入語音訊息的逐字稿會在代理情境中標示為機器生成且不受信任的文字，但提及偵測仍會使用原始逐字稿，因此受提及控制的語音訊息仍可正常運作。

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/voice.ogg",asVoice: true,}

影片訊息

Telegram 會區分影片檔案與視訊訊息。視訊訊息不支援說明文字；提供的訊息文字會分開傳送。

{action: "send",channel: "telegram",to: "123456789",media: "https://example.com/video.mp4",asVideoNote: true,}

位置與地點

使用現有的 send 動作，並提供一個獨立的 location 物件。座標會傳送原生地圖標記；同時加入 name 和 address 會傳送原生地點卡片。位置傳送不能與訊息文字或媒體合併。

{action: "send",channel: "telegram",to: "123456789",location: {latitude: 48.858844,longitude: 2.294351,accuracy: 12,name: "艾菲爾鐵塔",address: "巴黎戰神廣場",},}

貼圖

傳入：會下載並處理靜態 WEBP（預留位置 <media:sticker>）；略過動畫 TGS 和影片 WEBM。

貼圖情境欄位：Sticker.emoji、Sticker.setName、Sticker.fileId、Sticker.fileUniqueId、Sticker.cachedDescription。描述會快取於 OpenClaw SQLite 外掛狀態中，以減少重複的視覺模型呼叫。

啟用貼圖動作：

{channels: {telegram: {  actions: {    sticker: true,  },},},}

傳送：

{action: "sticker",channel: "telegram",to: "123456789",fileId: "CAACAgIAAxkBAAI...",}

搜尋已快取的貼圖：

{action: "sticker-search",channel: "telegram",query: "cat waving",limit: 5,}

Telegram 的表情回應會以 message_reaction 更新的形式送達，與訊息承載內容分開。啟用後，OpenClaw 會將類似 Telegram reaction added: 👍 by Alice (@alice) on msg 42 的系統事件加入佇列。

• channels.telegram.reactionNotifications：off | own | all（預設：own）
• channels.telegram.reactionLevel：off | ack | minimal | extensive（預設：minimal）

own 表示僅接收使用者對機器人所傳訊息的表情回應（透過已傳送訊息快取盡力判斷）。表情回應事件仍會遵循 Telegram 存取控制（dmPolicy、allowFrom、groupPolicy、groupAllowFrom）；未獲授權的傳送者會被捨棄。

Telegram 不會在表情回應更新中提供討論串 ID：非論壇群組會路由至群組聊天工作階段；論壇群組會路由至一般主題工作階段（:topic:1），而非實際的來源主題。

輪詢／網路鉤子的 allowed_updates 會自動包含 message_reaction。

ackReaction 會在 OpenClaw 處理傳入訊息時傳送確認表情符號。messages.ackReactionScope 決定傳送的時機。

表情符號解析順序：

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• 代理程式身分 emoji 備援（agents.list[].identity.emoji，否則為 "👀"）

Telegram 預期使用 Unicode emoji（例如 "👀"）；使用 "" 可停用某個頻道或帳號的回應反應。

範圍（messages.ackReactionScope，預設為 "group-mentions"；目前無法針對 Telegram 帳號或 Telegram 頻道覆寫）：

all（私訊 + 群組，包括環境聊天室事件）、direct（僅限私訊）、group-all（每則群組訊息，但不含環境聊天室事件，也不含私訊）、group-mentions（群組中提及機器人時；不含私訊 — 預設值）、off / none（停用）。

頻道設定寫入功能預設為啟用（configWrites !== false）。由 Telegram 觸發的寫入包括群組遷移事件（migrate_to_chat_id，更新 channels.telegram.groups），以及 /config set / /config unset（需要啟用命令）。

停用方式：

{channels: {telegram: {  configWrites: false,},},}

預設使用長輪詢。若要使用網路鉤子模式，請設定 channels.telegram.webhookUrl 與 channels.telegram.webhookSecret；可選設定包括 webhookPath（預設為 /telegram-webhook）、webhookHost（預設為 127.0.0.1）、webhookPort（預設為 8787）、webhookCertPath（用於直接 IP 或無網域設定的自簽憑證 PEM）。

在長輪詢模式中，OpenClaw 只會在更新成功分派後，才持久保存其重新啟動進度標記；若處理常式失敗，該更新在同一程序中仍可重試，而不會被標記為已完成。

本機監聽器預設繫結至 127.0.0.1:8787。若要接受公開連入流量，請在本機連接埠前方放置反向代理，或刻意設定 webhookHost: "0.0.0.0"。

網路鉤子模式會驗證請求防護、Telegram 秘密權杖與 JSON 主體，接著將更新提交至持久性輸入佇列，再傳回空的 200。成功持久接收時會包含 x-openclaw-delivery-accepted: durable；健康狀態、路由、驗證身分、資料驗證及儲存錯誤回應則不會包含此標頭。反向代理與主機控制器可要求此標頭，以區分 OpenClaw 已接收與一般的空 200，而不必根據回應時間推斷是否已接受。

接著，OpenClaw 會透過與長輪詢相同的每聊天／每主題機器人通道，以非同步方式處理更新，因此耗時較長的代理程式回合不會阻塞 Telegram 的傳遞確認。

• channels.telegram.textChunkLimit 預設為 4000；streaming.chunkMode="newline" 會優先依段落邊界（空白行）切分，再依長度切分。
• channels.telegram.mediaMaxMb（預設 100）限制傳入與傳出媒體的大小。
• channels.telegram.mediaGroupFlushMs（預設 500，範圍 10-60000）控制相簿／媒體群組在 OpenClaw 將其作為單一傳入訊息分派前的緩衝時間。如果相簿項目較晚抵達，請提高此值；若要縮短相簿回覆延遲，請降低此值。
• channels.telegram.timeoutSeconds 會覆寫 API 用戶端逾時（若未設定，則套用 grammY 預設值）。機器人用戶端會將低於 60 秒傳出文字／輸入中請求防護時間的設定值限制在該值以上，避免 grammY 在 OpenClaw 的傳輸防護與備援機制得以執行前，就中止使用者可見的回覆傳遞。長輪詢仍會對 getUpdates 使用 45 秒的請求防護，避免閒置輪詢遭無限期擱置。
• channels.telegram.pollingStallThresholdMs 預設為 120000；僅在輪詢停滯重新啟動為誤判時，才於 30000 至 600000 之間調整。
• 群組上下文歷史記錄使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（預設 50）；設為 0 可停用。
• 當閘道已觀察到父訊息時，回覆／引用／轉寄的補充上下文會正規化為一個選定的對話上下文視窗；已觀察訊息的快取儲存在 OpenClaw SQLite 外掛狀態中，而 openclaw doctor --fix 會匯入舊版側邊檔案。Telegram 每次更新只包含一層淺層的 reply_to_message，因此早於快取的訊息鏈僅限於該承載內容。
• Telegram 允許清單主要限制誰能觸發代理程式，而不是完整的補充上下文遮蔽邊界。
• 私訊歷史記錄：channels.telegram.dmHistoryLimit、channels.telegram.dms["<user_id>"].historyLimit。
• channels.telegram.retry 適用於 Telegram 傳送輔助函式（命令列介面／工具／動作）所遇到的可復原傳出 API 錯誤。傳入訊息的最終回覆傳遞會對連線前失敗使用有界的安全傳送重試，但不會重試可能導致使用者可見訊息重複的模糊傳送後網路封套。

命令列介面與訊息工具的傳送目標可接受數字聊天 ID、使用者名稱或論壇主題目標：

openclaw message send --channel telegram --target 123456789 --message "hi"openclaw message send --channel telegram --target @name --message "hi"openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

投票使用 openclaw message poll，並支援論壇主題：

openclaw message poll --channel telegram --target 123456789 \--poll-question "Ship it?" --poll-option "Yes" --poll-option "No"openclaw message poll --channel telegram --target -1001234567890:topic:42 \--poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \--poll-duration-seconds 300 --poll-public

僅限 Telegram 的投票旗標：--poll-duration-seconds（5-600）、--poll-anonymous、--poll-public、--thread-id（或 :topic: 目標）。--poll-option 可重複 2-12 次（Telegram 的選項上限）。

Telegram 傳送也支援搭配 buttons 區塊使用 --presentation 來建立行內鍵盤（當 channels.telegram.capabilities.inlineButtons 允許時）、使用 --pin 或 --delivery '{"pin":true}' 在機器人可於該聊天中釘選時要求釘選傳遞，以及使用 --force-document 將傳出圖片、GIF 與影片以文件傳送，而非使用壓縮圖片／動畫／影片上傳。

動作管控：channels.telegram.actions.sendMessage=false 會停用包括投票在內的所有傳出訊息；channels.telegram.actions.poll=false 會停用建立投票，但仍允許一般傳送。

Telegram 支援在核准者私訊中進行執行核准，也可選擇在原始聊天或主題中發布提示。核准者必須是數字 Telegram 使用者 ID。

• channels.telegram.execApprovals.enabled（當至少可解析一位核准者時，"auto" 會啟用）
• channels.telegram.execApprovals.approvers（備援使用 commands.ownerAllowFrom 中的數字擁有者 ID）
• channels.telegram.execApprovals.target：dm（預設）| channel | both
• agentFilter、sessionFilter

channels.telegram.allowFrom、groupAllowFrom 與 defaultTo 控制誰可以與機器人交談，以及機器人將一般回覆傳送到何處——它們不會讓某人成為執行核准者。若尚無命令擁有者，第一個獲核准的私訊配對會初始化 commands.ownerAllowFrom，因此單一擁有者設定無須在 execApprovals.approvers 下重複 ID 即可運作。

頻道傳遞會在聊天中顯示命令文字；僅在受信任的群組／主題中啟用 channel 或 both。提示出現在論壇主題中時，OpenClaw 會為核准提示與後續訊息保留該主題。執行核准預設會在 30 分鐘後到期。

行內核准按鈕也要求 channels.telegram.capabilities.inlineButtons 允許目標介面（dm、group 或 all）。以 plugin: 為前綴的核准 ID 會透過外掛核准解析；其他 ID 會先透過執行核准解析。

請參閱執行核准。

• 若 requireMention=false，Telegram 隱私模式必須允許完整可見性：BotFather /setprivacy -> Disable，然後從群組移除機器人再重新加入。
• 當設定預期接收未提及機器人的群組訊息時，openclaw channels status 會發出警告。
• openclaw channels status --probe 會檢查明確的數字群組 ID；萬用字元 "*" 無法探測成員資格。
• 快速工作階段測試：/activation always。

• 存在 channels.telegram.groups 時，必須列出該群組（或包含 "*"）。
• 確認機器人是群組成員。
• 查看 openclaw logs --follow 以瞭解略過原因。

• 授權你的傳送者身分（配對及／或數字 allowFrom）；即使群組原則為 open，命令授權仍然適用。
• setMyCommands failed 搭配 BOT_COMMANDS_TOO_MUCH 表示原生選單的項目過多；請減少外掛／技能／自訂命令，或停用原生選單。
• deleteMyCommands／setMyCommands 啟動呼叫與 sendChatAction 輸入中呼叫皆為有界操作，並會在請求逾時時透過 Telegram 的傳輸備援機制重試一次。持續發生網路／擷取錯誤通常表示無法透過 DNS／HTTPS 連線至 api.telegram.org。

• getMe returned 401 表示已設定的機器人權杖發生 Telegram 驗證失敗。請在 BotFather 中重新複製或產生權杖，然後更新 channels.telegram.botToken、tokenFile、accounts.<id>.botToken 或 TELEGRAM_BOT_TOKEN（預設帳號）。
• 啟動期間出現 deleteWebhook 401 Unauthorized 也表示驗證失敗；將其視為「不存在網路鉤子」只會把同一個錯誤權杖問題延後到後續 API 呼叫才發生。

• 若 AbortSignal 類型不相符，Node 22+ 搭配自訂 fetch／Proxy 可能會觸發立即中止行為。
• 部分主機會優先將 api.telegram.org 解析為 IPv6；損壞的 IPv6 對外連線會造成間歇性 API 失敗。
• 日誌中的 TypeError: fetch failed 或 Network request for 'getUpdates' failed! 會視為可復原的網路錯誤並重試。
• 在輪詢啟動期間，OpenClaw 會為 grammY 重複使用啟動時成功的 getMe 探測結果，因此執行器在第一次 getUpdates 前不必再次呼叫 getMe。
• 若在輪詢啟動期間，deleteWebhook 因暫時性網路錯誤而失敗，OpenClaw 會繼續進入長輪詢，而不會再進行一次輪詢前控制平面呼叫。若網路鉤子仍處於啟用狀態，之後會呈現為 getUpdates 衝突；OpenClaw 會重建傳輸並重試清理網路鉤子。
• 若 Telegram Socket 以固定的短週期重建，請檢查 channels.telegram.timeoutSeconds 是否過低——機器人用戶端會將低於傳出與 getUpdates 請求防護時間的設定值限制在該值以上，但舊版可能在此值低於這些防護時間時中止每次輪詢或回覆。
• 日誌中的 Polling stall detected 表示 OpenClaw 在預設 120 秒內未完成長輪詢活性活動後，會重新啟動輪詢並重建傳輸。
• 當執行中的輪詢帳號在啟動寬限期後仍未完成 getUpdates、執行中的網路鉤子帳號在啟動寬限期後仍未完成 setWebhook，或最後成功的輪詢傳輸活動已過期時，openclaw channels status --probe 與 openclaw doctor 會發出警告。
• 僅當長時間執行的 getUpdates 呼叫狀態正常，但你的主機仍回報輪詢停滯重新啟動的誤判時，才提高 channels.telegram.pollingStallThresholdMs。持續停滯通常表示 Proxy、DNS、IPv6 或連線至 api.telegram.org 的 TLS 對外連線有問題。
• Telegram 的 Bot API 傳輸會遵循程序的 Proxy 環境變數：HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 及其小寫變體。NO_PROXY／no_proxy 仍可略過 api.telegram.org。
• 若服務環境已設定 OPENCLAW_PROXY_URL，且不存在標準 Proxy 環境變數，Telegram 也會將該 URL 用於 Bot API 傳輸。
• 在直接對外連線／TLS 不穩定的 VPS 主機上，請透過 Proxy 路由 Telegram API 呼叫：

channels:telegram:proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ 預設為 autoSelectFamily=true（WSL2 除外）。Telegram DNS 結果順序依序採用 OPENCLAW_TELEGRAM_DNS_RESULT_ORDER、channels.telegram.network.dnsResultOrder，再採用程序預設值（例如 NODE_OPTIONS=--dns-result-order=ipv4first）；若皆不適用，則在 Node 22+ 上備援為 ipv4first。
• 在 WSL2 上，或僅使用 IPv4 的行為較佳時，請強制指定位址族選擇：

channels:telegram:network:  autoSelectFamily: false

• 預設已允許 Telegram 媒體下載使用 RFC 2544 基準測試範圍的回應（198.18.0.0/15）。如果受信任的假 IP 或透明代理在媒體下載期間將 api.telegram.org 改寫為其他私人／內部／特殊用途位址，請選擇啟用僅限 Telegram 的略過機制：

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• 每個帳號也可透過 channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork 選擇啟用相同設定。
• 如果你的代理將 Telegram 媒體主機解析為 198.18.x.x，請先讓危險旗標保持關閉——預設已允許該範圍。

• 暫時性環境變數覆寫：OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1、OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1、OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first。
• 驗證 DNS 回應：

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