Telegram（Bot API）

Telegram 機器人預設為**隱私模式**，這會限制它能接收到的群組訊息。

如果機器人需要看到所有群組訊息，可以：

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

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

管理員身分在 Telegram 群組設定中控制。

管理員機器人會接收所有群組訊息，這對於需要持續運行的群組行為很有用。

- `/setjoingroups` 允許/拒絕群組邀請
- `/setprivacy` 控制群組可見性行為

OpenClaw 可以即時串流部分回覆：

- 私訊：預覽訊息 + `editMessageText`
- 群組/主題：預覽訊息 + `editMessageText`

條件：

- `channels.telegram.streaming` 可為 `off | partial | block | progress`（預設：`partial`）
- `progress` 在 Telegram 上對應到 `partial`（跨頻道命名相容）
- 舊版 `channels.telegram.streamMode` 和布林值 `streaming` 會自動對應

純文字回覆：

- DM：OpenClaw 保持同一則預覽訊息並在最終時就地編輯（不會發送第二則訊息）
- 群組/主題：OpenClaw 保持同一則預覽訊息並在最終時就地編輯（不會發送第二則訊息）

複合回覆（例如媒體內容）時，OpenClaw 會退回正常的最終送達，然後清除預覽訊息。

預覽串流與區塊串流是分開的。當為 Telegram 明確啟用區塊串流時，OpenClaw 會跳過預覽串流以避免重複串流。

如果原生草稿傳輸不可用/被拒絕，OpenClaw 會自動退回到 `sendMessage` + `editMessageText`。

Telegram 專用推理串流：

- `/reasoning stream` 在生成過程中將推理內容傳送到即時預覽
- 最終答案不包含推理文字

傳出文字使用 Telegram `parse_mode: "HTML"`。

- 類 Markdown 文字會轉換為 Telegram 安全的 HTML。
- 原始模型 HTML 會被跳脫以減少 Telegram 解析失敗。
- 如果 Telegram 拒絕解析後的 HTML，OpenClaw 會以純文字重試。

連結預覽預設啟用，可透過 `channels.telegram.linkPreview: false` 停用。

Telegram 指令選單在啟動時透過 `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`
- 自訂指令不能覆蓋原生指令
- 衝突/重複會被跳過並記錄

注意事項：

- 自訂指令僅為選單項目；不會自動實作行為
- 外掛/技能指令即使未顯示在 Telegram 選單中，輸入時仍可運作

如果停用原生指令，內建指令會被移除。自訂/外掛指令如有設定仍可能註冊。

常見設定失敗：

- `setMyCommands failed` 且錯誤為 `BOT_COMMANDS_TOO_MUCH` 表示 Telegram 選單在裁剪後仍溢位；請減少外掛/技能/自訂指令或停用 `channels.telegram.commands.native`。
- `setMyCommands failed` 且為網路/fetch 錯誤通常表示對 `api.telegram.org` 的對外 DNS/HTTPS 被阻擋。

### 裝置配對指令（`device-pair` 外掛）

安裝 `device-pair` 外掛後：

1. `/pair` 產生設定碼
2. 在 iOS 應用程式中貼上碼
3. `/pair approve` 核准最新的待處理請求

詳情：[配對](/docs/channels/pairing#pair-via-telegram-recommended-for-ios)。

設定行內鍵盤範圍：

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

按帳號覆寫：

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

範圍：

- `off`
- `dm`
- `group`
- `all`
- `allowlist`（預設）

舊版 `capabilities: ["inlineButtons"]` 對應到 `inlineButtons: "all"`。

訊息動作範例：

{
  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: <value>`

Telegram 工具動作包括：

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

頻道訊息動作公開便捷別名（`send`、`react`、`delete`、`edit`、`sticker`、`sticker-search`、`topic-create`）。

控制閘門：

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

注意：`edit` 和 `topic-create` 目前預設啟用，沒有獨立的 `channels.telegram.actions.*` 開關。
執行時傳送使用啟動/重新載入時的設定/密鑰快照，因此動作路徑不會在每次傳送時重新解析 SecretRef。

反應移除語義：[/tools/reactions](/docs/tools/reactions)

Telegram 支援在生成輸出中使用明確的回覆討論串標記：

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

`channels.telegram.replyToMode` 控制處理方式：

- `off`（預設）
- `first`
- `all`

注意：`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` 僅限主題使用，不從群組預設繼承。

**按主題的代理路由**：每個主題可以透過在主題設定中設定 `agentId` 來路由到不同的代理。這讓每個主題擁有自己的隔離工作空間、記憶和工作階段。範例：

```json5
{
  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 主題綁定**：論壇主題可以透過頂層具型別的 ACP 綁定來固定 ACP harness 工作階段：

- `bindings[]` 搭配 `type: "acp"` 和 `match.channel: "telegram"`

範例：

```json5
{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
    },
  ],
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "42": {
              requireMention: false,
            },
          },
        },
      },
    },
  },
}
```

目前僅適用於群組和超級群組中的論壇主題。

**從聊天中綁定討論串的 ACP 生成**：

- `/acp spawn <agent> --thread here|auto` 可以將當前 Telegram 主題綁定到新的 ACP 工作階段。
- 後續的主題訊息會直接路由到已綁定的 ACP 工作階段（不需要 `/acp steer`）。
- 成功綁定後 OpenClaw 會在主題中釘選生成確認訊息。
- 需要 `channels.telegram.threadBindings.spawnAcpSessions=true`。

範本上下文包含：

- `MessageThreadId`
- `IsForum`

DM 討論串行為：

- 帶有 `message_thread_id` 的私人聊天保持 DM 路由，但使用支援討論串的工作階段鍵/回覆目標。

### 音訊訊息

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

視訊備忘錄不支援說明文字；提供的訊息文字會單獨傳送。

### 貼圖

收到貼圖的處理：

- 靜態 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 反應以 `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`），而非確切的來源主題

輪詢/webhook 的 `allowed_updates` 會自動包含 `message_reaction`。

`ackReaction` 在 OpenClaw 處理收到的訊息時傳送一個確認表情符號。

解析順序：

- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- 代理身分表情符號備援（`agents.list[].identity.emoji`，否則 "👀"）

注意事項：

- Telegram 期望 unicode 表情符號（例如 "👀"）。
- 使用 `""` 可停用特定頻道或帳號的反應。

頻道設定寫入預設啟用（`configWrites !== false`）。

Telegram 觸發的寫入包括：

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

停用：

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

預設：長輪詢。

Webhook 模式：

- 設定 `channels.telegram.webhookUrl`
- 設定 `channels.telegram.webhookSecret`（設定 webhook URL 時必填）
- 選用 `channels.telegram.webhookPath`（預設 `/telegram-webhook`）
- 選用 `channels.telegram.webhookHost`（預設 `127.0.0.1`）
- 選用 `channels.telegram.webhookPort`（預設 `8787`）

Webhook 模式的預設本地監聽綁定到 `127.0.0.1:8787`。

如果你的公開端點不同，請在前方放置反向代理並將 `webhookUrl` 指向公開 URL。
當你刻意需要外部存取時，設定 `webhookHost`（例如 `0.0.0.0`）。

- `channels.telegram.textChunkLimit` 預設為 4000。
- `channels.telegram.chunkMode="newline"` 優先依段落邊界（空白行）分割，再進行長度分割。
- `channels.telegram.mediaMaxMb`（預設 100）限制 Telegram 收發媒體大小。
- `channels.telegram.timeoutSeconds` 覆寫 Telegram API 用戶端逾時（未設定時套用 grammY 預設值）。
- 群組上下文歷史使用 `channels.telegram.historyLimit` 或 `messages.groupChat.historyLimit`（預設 50）；`0` 為停用。
- DM 歷史控制：
  - `channels.telegram.dmHistoryLimit`
  - `channels.telegram.dms["<user_id>"].historyLimit`
- `channels.telegram.retry` 設定套用於 Telegram 傳送輔助工具（CLI/工具/動作），處理可恢復的對外 API 錯誤。

CLI 傳送目標可以是數字聊天 ID 或使用者名稱：

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

Telegram 投票使用 `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:` 目標）

動作閘門：

- `channels.telegram.actions.sendMessage=false` 停用對外 Telegram 訊息（包括投票）
- `channels.telegram.actions.poll=false` 停用 Telegram 投票建立，但保留一般傳送功能

Telegram 支援在核准者 DM 中進行執行核准，並可選擇在來源聊天或主題中張貼核准提示。

設定路徑：

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target`（`dm` | `channel` | `both`，預設：`dm`）
- `agentFilter`、`sessionFilter`

核准者必須是數字 Telegram 使用者 ID。當 `enabled` 為 false 或 `approvers` 為空時，Telegram 不會作為執行核准用戶端。核准請求會退回到其他已設定的核准路由或執行核准備援政策。

送達規則：

- `target: "dm"` 僅傳送核准提示到已設定的核准者 DM
- `target: "channel"` 將提示傳回來源 Telegram 聊天/主題
- `target: "both"` 同時傳送到核准者 DM 和來源聊天/主題

只有已設定的核准者可以核准或拒絕。非核准者無法使用 `/approve`，也無法使用 Telegram 核准按鈕。

頻道送達會在聊天中顯示指令文字，因此只在受信任的群組/主題中啟用 `channel` 或 `both`。當提示落在論壇主題中時，OpenClaw 會在核准提示和核准後的後續訊息中保留主題。

行內核准按鈕也依賴 `channels.telegram.capabilities.inlineButtons` 允許目標介面（`dm`、`group` 或 `all`）。

相關文件：[執行核准](/docs/tools/exec-approvals)

- 如果 `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` 表示原生選單項目過多；減少外掛/技能/自訂指令或停用原生選單
- `setMyCommands failed` 且為網路/fetch 錯誤通常表示對 `api.telegram.org` 的 DNS/HTTPS 可達性問題

- Node 22+ 搭配自訂 fetch/proxy 可能在 AbortSignal 型別不匹配時觸發立即中止行為。
- 某些主機會優先將 `api.telegram.org` 解析為 IPv6；損壞的 IPv6 出口可能導致間歇性 Telegram API 故障。
- 如果日誌包含 `TypeError: fetch failed` 或 `Network request for 'getUpdates' failed!`，OpenClaw 現在會將這些視為可恢復的網路錯誤並重試。
- 在直接出口/TLS 不穩定的 VPS 主機上，透過 `channels.telegram.proxy` 路由 Telegram API 呼叫：

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

- Node 22+ 預設為 `autoSelectFamily=true`（WSL2 除外）和 `dnsResultOrder=ipv4first`。
- 如果你的主機是 WSL2 或使用純 IPv4 行為效果更好，可以強制選擇地址族群：

channels:
  telegram:
    network:
      autoSelectFamily: false

- 環境變數覆寫（暫時）：
  - `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