Telegram

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

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

• 直接聊天：預覽訊息 + editMessageText
• 群組/主題：預覽訊息 + editMessageText

• channels.telegram.streaming 為 off | partial | block | progress（預設：partial）
• progress 會為工具進度保留一則可編輯的狀態草稿，在完成時清除，並以一般訊息傳送最終答案
• streaming.preview.toolProgress 控制工具/進度更新是否重用相同的已編輯預覽訊息（預設：預覽串流啟用時為 true）
• streaming.preview.commandText 控制這些工具進度行中的命令/exec 詳細資訊：raw（預設，保留已發布行為）或 status（僅工具標籤）
• 會偵測舊版 channels.telegram.streamMode 與布林 streaming 值；執行 openclaw doctor --fix 以將它們遷移至 channels.telegram.streaming.mode

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

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

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

• 短 DM/群組/主題預覽：OpenClaw 會保留同一則預覽訊息，並就地執行最終編輯
• 會拆成多則 Telegram 訊息的長文字最終內容，會在可行時重用現有預覽作為第一個最終片段，然後只傳送剩餘片段
• 進度模式的最終內容會清除狀態草稿，並使用一般最終傳送，而不是把草稿編輯成回答
• 如果最終編輯在完成文字確認前失敗，OpenClaw 會使用一般最終傳送，並清理過期的預覽

• /reasoning stream 會在生成期間將推理傳送到即時預覽
• 推理預覽會在最終傳送後刪除；當推理應保持可見時，請使用 /reasoning on
• 最終回答傳送時不會包含推理文字

• 類似 Markdown 的文字會轉譯為 Telegram 安全的 HTML。
• 原始模型 HTML 會被逸出，以減少 Telegram 解析失敗。
• 如果 Telegram 拒絕已解析的 HTML，OpenClaw 會以純文字重試。

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

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

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

• 自訂指令只是選單項目；它們不會自動實作行為
• 即使未顯示在 Telegram 選單中，Plugin/Skills 指令在輸入時仍可運作

• setMyCommands failed 搭配 BOT_COMMANDS_TOO_MUCH 表示 Telegram 選單在修剪後仍然超出限制；請減少 Plugin/Skills/自訂指令，或停用 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 會在輪詢前停止，因此這不會被回報為 Webhook 清理失敗。
• setMyCommands failed 搭配網路/擷取錯誤通常表示到 api.telegram.org 的傳出 DNS/HTTPS 被封鎖。

​

裝置配對指令（device-pair Plugin）

1. /pair 會產生設定程式碼
2. 在 iOS 應用程式貼上程式碼
3. /pair pending 會列出待處理請求（包含角色/範圍）
4. 核准請求：
   • /pair approve <requestId> 用於明確核准
   • /pair approve 用於只有一個待處理請求時
   • /pair approve latest 用於最新請求

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

{
  channels: {
    telegram: {
      accounts: {
        main: {
          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" }],
  ],
}

• sendMessage（to、content、選用 mediaUrl、replyToMessageId、messageThreadId）
• react（chatId、messageId、emoji）
• deleteMessage（chatId、messageId）
• editMessage（chatId、messageId、content）
• createForumTopic（chatId、name、選用 iconColor、iconCustomEmojiId）

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker（預設：停用）

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

• off（預設）
• first
• all

• 主題工作階段金鑰會附加 :topic:<threadId>
• 回覆與輸入中狀態會以主題對話串為目標
• 主題設定路徑： channels.telegram.groups.<chatId>.topics.<threadId>

• 訊息傳送會省略 message_thread_id（Telegram 會拒絕 sendMessage(...thread_id=1)）
• 輸入中動作仍會包含 message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}

​

音訊訊息

• 預設：音訊檔案行為
• 在代理回覆中標記 [[audio_as_voice]] 可強制傳送語音備忘
• 傳入語音備忘的逐字稿會在代理情境中被框定為機器產生、 不受信任的文字；提及偵測仍會使用原始 逐字稿，因此受提及閘控的語音訊息會繼續運作。

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

​

影片訊息

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

​

貼圖

• 靜態 WEBP：下載並處理（佔位符 <media:sticker>）
• 動畫 TGS：略過
• 影片 WEBM：略過

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

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

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

• 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 表示只處理使用者對 bot 傳送訊息的反應（透過已傳送訊息快取盡力而為）。
• 反應事件仍會遵守 Telegram 存取控制（dmPolicy、allowFrom、groupPolicy、groupAllowFrom）；未授權的傳送者會被丟棄。
• Telegram 不會在反應更新中提供討論串 ID。
  • 非論壇群組會路由到群組聊天工作階段
  • 論壇群組會路由到群組的一般主題工作階段（:topic:1），而不是精確的來源主題

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• 代理身分表情符號後備值（agents.list[].identity.emoji，否則為 ”👀”）

• Telegram 預期使用 Unicode 表情符號（例如 ”👀”）。
• 使用 "" 可停用頻道或帳號的反應。

• 群組遷移事件（migrate_to_chat_id）以更新 channels.telegram.groups
• /config set 和 /config unset（需要啟用命令）

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

• channels.telegram.textChunkLimit 預設為 4000。
• channels.telegram.chunkMode="newline" 會先偏好段落邊界（空白行），再依長度分割。
• channels.telegram.mediaMaxMb（預設 100）會限制傳入與傳出的 Telegram 媒體大小。
• channels.telegram.mediaGroupFlushMs（預設 500）控制 Telegram 相簿/媒體群組在 OpenClaw 將其作為單一傳入訊息分派前緩衝多久。如果相簿部分抵達較晚，請增加此值；若要降低相簿回覆延遲，請減少此值。
• channels.telegram.timeoutSeconds 會覆寫 Telegram API 用戶端逾時（若未設定，套用 grammY 預設值）。Bot 用戶端會將低於 60 秒傳出文字/輸入請求防護的設定值限縮，使 grammY 不會在 OpenClaw 的傳輸防護與後備機制執行前中止可見回覆傳遞。長輪詢仍會使用 45 秒 getUpdates 請求防護，因此閒置輪詢不會無限期遭到放棄。
• channels.telegram.pollingStallThresholdMs 預設為 120000；僅針對誤判的輪詢停滯重啟，在 30000 到 600000 之間調整。
• 群組情境歷史會使用 channels.telegram.historyLimit 或 messages.groupChat.historyLimit（預設 50）；0 表示停用。
• 當 Gateway 已觀察到父訊息時，回覆/引用/轉寄的補充情境會正規化到一個選定的對話情境視窗；已觀察訊息快取會保存在工作階段儲存旁邊。Telegram 在更新中只包含一層淺層 reply_to_message，因此早於快取的鏈會受限於 Telegram 目前的更新負載。
• Telegram 允許清單主要控管誰可以觸發代理，而不是完整的補充情境遮蔽邊界。
• DM 歷史控制：
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• channels.telegram.retry 設定會套用到 Telegram 傳送輔助工具（CLI/工具/動作），用於可復原的傳出 API 錯誤。傳入最終回覆傳遞也會針對 Telegram 預連線失敗使用有界限的安全傳送重試，但不會重試可能重複可見訊息的模糊傳送後網路封套。

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 --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

• --poll-duration-seconds（5-600）
• --poll-anonymous
• --poll-public
• --thread-id 用於論壇主題（或使用 :topic: 目標）

• 當 channels.telegram.capabilities.inlineButtons 允許時，使用含有 buttons 區塊的 --presentation 建立行內鍵盤
• --pin 或 --delivery '{"pin":true}' 可在 bot 能於該聊天釘選時請求釘選傳遞
• --force-document 可將傳出的圖片和 GIF 作為文件傳送，而不是壓縮照片或動畫媒體上傳

• channels.telegram.actions.sendMessage=false 會停用傳出 Telegram 訊息，包括輪詢
• channels.telegram.actions.poll=false 會停用 Telegram 輪詢建立，同時保留一般傳送啟用

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

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

• 當 channels.telegram.groups 存在時，群組必須列在其中（或包含 "*"）
• 驗證 Bot 在群組中的成員資格
• 檢閱日誌：openclaw logs --follow 查看略過原因

• 授權你的傳送者身分（配對及/或數字 allowFrom）
• 即使群組政策為 open，命令授權仍然適用
• setMyCommands failed 搭配 BOT_COMMANDS_TOO_MUCH 表示原生命令選單項目過多；減少 Plugin/skill/自訂命令，或停用原生選單
• deleteMyCommands / setMyCommands 啟動呼叫與 sendChatAction 輸入狀態呼叫都有界限，並會在請求逾時時透過 Telegram 的傳輸備援重試一次。持續性的網路/擷取錯誤通常表示對 api.telegram.org 的 DNS/HTTPS 可達性有問題

• getMe returned 401 是已設定 Bot Token 的 Telegram 驗證失敗。
• 在 BotFather 重新複製或重新產生 Bot Token，然後針對預設帳號更新 channels.telegram.botToken、channels.telegram.tokenFile、channels.telegram.accounts.<id>.botToken 或 TELEGRAM_BOT_TOKEN。
• 啟動期間的 deleteWebhook 401 Unauthorized 也是驗證失敗；將其視為「沒有 Webhook 存在」只會把相同的錯誤 Token 失敗延後到之後的 API 呼叫。

• Node 22+ 加上自訂 fetch/proxy 時，如果 AbortSignal 型別不相符，可能會觸發立即中止行為。
• 某些主機會先將 api.telegram.org 解析為 IPv6；損壞的 IPv6 輸出可能造成間歇性的 Telegram API 失敗。
• 如果日誌包含 TypeError: fetch failed 或 Network request for 'getUpdates' failed!，OpenClaw 現在會將這些視為可復原的網路錯誤並重試。
• 在輪詢啟動期間，OpenClaw 會為 grammY 重用成功的啟動 getMe 探測，因此執行器在第一次 getUpdates 前不需要第二次 getMe。
• 如果在輪詢啟動期間 deleteWebhook 因暫時性網路錯誤而失敗，OpenClaw 會繼續進入長輪詢，而不是進行另一個輪詢前的控制平面呼叫。仍處於啟用狀態的 Webhook 會以 getUpdates 衝突呈現；OpenClaw 隨後會重建 Telegram 傳輸並重試 Webhook 清理。
• 如果 Telegram Socket 以短而固定的節奏回收，請檢查是否有過低的 channels.telegram.timeoutSeconds；Bot 用戶端會將設定值限制在輸出與 getUpdates 請求防護值以下，但較舊版本在此值低於那些防護值時，可能會在每次輪詢或回覆時中止。
• 如果日誌包含 Polling stall detected，OpenClaw 預設會在 120 秒內沒有完成長輪詢存活訊號後，重新啟動輪詢並重建 Telegram 傳輸。
• 當執行中的輪詢帳號在啟動寬限期後尚未完成 getUpdates、執行中的 Webhook 帳號在啟動寬限期後尚未完成 setWebhook，或最後一次成功的輪詢傳輸活動已過舊時，openclaw channels status --probe 和 openclaw doctor 會發出警告。
• 只有在長時間執行的 getUpdates 呼叫是健康的，但你的主機仍回報誤判的輪詢停滯重新啟動時，才增加 channels.telegram.pollingStallThresholdMs。持續停滯通常指向主機與 api.telegram.org 之間的 proxy、DNS、IPv6 或 TLS 輸出問題。
• Telegram 也會遵循 Bot API 傳輸的處理程序 proxy env，包括 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 及其小寫變體。NO_PROXY / no_proxy 仍可繞過 api.telegram.org。
• 如果 OpenClaw 受管理 proxy 是透過服務環境的 OPENCLAW_PROXY_URL 設定，且不存在標準 proxy env，Telegram 也會將該 URL 用於 Bot API 傳輸。
• 在直接輸出/TLS 不穩定的 VPS 主機上，透過 channels.telegram.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

• RFC 2544 基準測試範圍答案（198.18.0.0/15）預設已允許 用於 Telegram 媒體下載。如果受信任的 fake-IP 或 透明 proxy 在媒體下載期間將 api.telegram.org 改寫為其他 private/internal/special-use 位址，你可以選擇啟用 僅限 Telegram 的繞過：

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• 同一個選擇性啟用也可在每個帳號層級使用，位於 channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork。
• 如果你的 proxy 將 Telegram 媒體主機解析為 198.18.x.x，請先保持 危險旗標關閉。Telegram 媒體預設已允許 RFC 2544 基準測試範圍。

• 環境覆寫（暫時）：
  • 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 A
dig +short api.telegram.org AAAA