Telegram

Telegram 機器人預設使用 Privacy Mode，這會限制它們能收到的群組訊息。

若要查看所有群組訊息，可採用以下任一方式：

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

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

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

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

如果你偏好使用介面而非聊天命令，也可以在 BotFather's web app 中使用相同設定。

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.2 專用的豐富區塊（原生表格、詳細資料、豐富媒體、公式）。

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

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

啟用後：系統會告知代理程式，此機器人／帳號可使用豐富訊息（以及受支援的 Markdown + HTML 島式撰寫合約）；Markdown 文字會透過 OpenClaw 的 Markdown IR，呈現為具型別的 Bot API 10.2 豐富區塊（標題、表格、詳細資料、核取清單、豐富媒體、公式、地圖、拼貼）；媒體說明仍使用 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 會以「找不到討論串」拒絕 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 會在主題內固定產生確認訊息。由 session.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: "揮手的貓",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。

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

表情符號解析順序：

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• 代理身分表情符號的備援值（agents.entries.*.identity.emoji，否則為「👀」）

Telegram 預期使用 Unicode 表情符號（例如「👀」）；使用 "" 可停用某個頻道或帳號的反應。

範圍（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。若要接收公開傳入流量，請在本機連接埠前放置反向 Proxy，或刻意設定 webhookHost: "0.0.0.0"。

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

完成持久化寫入後，OpenClaw 會透過核心頻道傳入排放機制領取並處理更新（每個聊天／每個主題的處理通道、在回合接收時完成、接收前停滯逾時）。耗時的代理回合不會占用 Telegram 的傳遞 ACK。

• channels.telegram.textChunkLimit 預設為 4000；streaming.chunkMode="newline" 會優先依段落邊界（空白行）切分，再依長度切分。
• channels.telegram.mediaMaxMb（預設為 100）限制輸入與輸出媒體的大小。
• 群組情境歷程使用 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。

命令列介面與訊息工具的傳送目標接受數字聊天 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 傳送功能也支援 --presentation 搭配 buttons 區塊來建立行內鍵盤（當 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 會重建傳輸並重試清除網路鉤子。
• 記錄中的 Polling stall detected 表示在預設 120 秒內未完成長輪詢存活檢查後，OpenClaw 會重新啟動輪詢並重建傳輸。
• 當執行中的輪詢帳號在啟動寬限期後尚未完成 getUpdates、執行中的網路鉤子帳號在啟動寬限期後尚未完成 setWebhook，或上次成功的輪詢傳輸活動已過期時，openclaw channels status --probe 和 openclaw doctor 會發出警告。
• 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 或透明 Proxy 在媒體下載期間，將 api.telegram.org 改寫為其他私人／內部／特殊用途位址，請選擇啟用僅限 Telegram 的繞過：

channels:telegram:network:  dangerouslyAllowPrivateNetwork: true

• 每個帳號也可在 channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork 中選擇啟用相同設定。
• 若你的 Proxy 將 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