OpenClaw
渠道整合10 分鐘閱讀

OpenClaw Telegram 整合完整指南

學習如何建立 Telegram 機器人並連接到 OpenClaw。完整教學涵蓋機器人建立、設定、命令和群組聊天設定。

O

OpenClaw Guides

Tutorial Authors

概述

Telegram 整合讓您可以透過專用的 Telegram 機器人與 OpenClaw 互動。OpenClaw 預設使用 grammY 框架進行長輪詢，並支援可選的 webhook 模式用於生產環境部署。

前提條件

  • 已安裝並執行 OpenClaw
  • 一個 Telegram 帳戶

步驟 1：建立 Telegram 機器人

與 BotFather 對話

  1. 開啟 Telegram 搜尋 @BotFather
  2. 開始對話並發送 /newbot
  3. 按照提示操作：
You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

儲存機器人權杖 — 下一步您將需要它。

停用隱私模式（建議用於群組）

如果您計劃在群組聊天中使用機器人，請停用隱私模式以便它可以讀取所有訊息：

/setprivacy
@myopenclaw_bot
Disable

更改隱私模式後，您必須將機器人從現有群組中移除並重新加入才能使變更生效。或者，將機器人提升為群組管理員 — 管理員機器人始終能接收所有訊息。

步驟 2：設定 OpenClaw

權杖儲存

您可以透過兩種方式儲存機器人權杖。設定檔優先於環境變數。

選項 A — 環境變數：

bash
# 新增到 ~/.openclaw/.env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

選項 B — 直接寫在設定檔中：

json5
// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

最小設定

編輯 ~/.openclaw/openclaw.json：

json5
{
  channels: {
    telegram: {
      // 從環境變數 TELEGRAM_BOT_TOKEN 取得權杖，或直接設定 botToken
    }
  }
}

這就是您所需的全部 — 當 Telegram 頻道設定完成後，OpenClaw 會自動啟動長輪詢。

步驟 3：測試您的機器人

  1. 開啟 Telegram 搜尋您的機器人使用者名稱
  2. 用 /start 開始對話
  3. 發送任何訊息進行測試

存取控制 — DM 政策

透過 dmPolicy 控制誰可以在私訊中向您的機器人發送訊息：

| 政策 | 行為 | |--------|----------| | "pairing"（預設） | 未知的發送者會收到一個有時效的配對碼；您透過 CLI 核准 | | "allowlist" | 只有在 allowFrom 中的使用者 ID / @使用者名稱可以發送訊息 | | "open" | 任何人都可以向機器人發送訊息 | | "disabled" | 完全關閉私訊功能 |

配對模式（預設）

當新使用者向機器人發送訊息時，他們會收到一個配對碼。使用以下命令核准：

bash
# 列出待處理的配對請求
openclaw pairing list telegram

# 核准特定代碼
openclaw pairing approve telegram <CODE>

配對碼會在 1 小時後過期。

白名單模式

json5
{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

開放模式

json5
{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

群組聊天支援

啟用群組存取

將群組 ID 新增到 groups 物件中。使用 "*" 允許所有群組：

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // 使用預設值的特定群組
        "-1009876543210": {             // 帶有覆寫設定的特定群組
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

或允許所有群組：

json5
{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

群組政策

控制誰可以在群組內與機器人互動：

| 設定 | 說明 | |---------|-------------| | groupPolicy: "open" | 任何群組成員都可以向機器人發送訊息 | | groupPolicy: "allowlist" | 只有在 groupAllowFrom 中的發送者可以互動 | | groupPolicy: "disabled" | 機器人忽略所有群組訊息 |

json5
{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

提及要求

預設情況下，機器人在群組中需要 @mention。您可以按群組更改此設定：

json5
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // 機器人回應所有訊息
        }
      }
    }
  }
}

或在群組聊天中使用僅限當前工作階段的命令 /activation always。

個別群組覆寫

每個群組條目支援以下欄位：

| 欄位 | 說明 | |-------|-------------| | groupPolicy | 覆寫全域群組政策 | | requireMention | 是否需要 @mention | | skills | 此群組中可用的技能 | | allowFrom | 此群組的發送者白名單 | | systemPrompt | 此群組的自訂系統提示詞 | | enabled | 啟用/停用此特定群組 |

訊息格式與分段

HTML 解析模式

OpenClaw 使用 Telegram 的 HTML 解析模式發送訊息（而非 Markdown）。來自 LLM 的 Markdown 會自動轉換為 HTML 安全標籤。如果 Telegram 拒絕 HTML，訊息會以純文字重試。

文字分段

長訊息會被分割為多條 Telegram 訊息：

json5
{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // 每條訊息的最大字元數（預設：4000）
      chunkMode: "newline"     // "length"（預設）或 "newline"
    }
  }
}
  • "length" — 在字元數上限處分割
  • "newline" — 在套用長度限制之前，於段落邊界處分割

媒體處理

媒體大小限制

json5
{
  channels: {
    telegram: {
      mediaMaxMb: 5    // 最大檔案大小（MB）（預設：5）
    }
  }
}

貼圖

  • 靜態貼圖（WEBP）會透過視覺處理並描述給 LLM
  • 動態/影片貼圖會被跳過
  • 貼圖描述會快取在 ~/.openclaw/telegram/sticker-cache.json 中，以避免重複的視覺呼叫

要讓機器人能夠發送貼圖：

json5
{
  channels: {
    telegram: {
      actions: {
        sticker: true    // 預設：false
      }
    }
  }
}

歷史紀錄與上下文

json5
{
  channels: {
    telegram: {
      historyLimit: 50,        // 群組上下文（預設：50）
      dmHistoryLimit: 100      // 私訊上下文
    }
  }
}

個別使用者私訊覆寫：

json5
{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

設定為 0 可停用歷史紀錄。

串流

OpenClaw 在私訊中支援基於草稿的串流（需啟用論壇主題）：

| 設定 | 說明 | |---------|-------------| | streamMode: "off" | 串流已停用（預設） | | streamMode: "partial" | 持續更新草稿訊息 | | streamMode: "block" | 分塊更新草稿訊息 |

區塊模式設定：

json5
{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Webhook 模式（生產環境）

對於生產環境部署，使用 webhook 取代長輪詢：

json5
{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // 本地路徑，預設：/telegram-webhook
    }
  }
}

Webhook 監聽器綁定到 0.0.0.0:8787。當設定了 webhookUrl 時，OpenClaw 會自動從輪詢切換到 webhook 模式。

命令

原生命令

OpenClaw 在啟動時會向 Telegram 的機器人選單註冊以下命令：

| 命令 | 說明 | |---------|-------------| | /start | 歡迎訊息 | | /status | 顯示機器人狀態 | | /reset | 重設對話 | | /model | 顯示/切換模型 |

自訂命令

透過設定新增選單項目（僅限選單 — 除非在其他地方處理，否則不會執行）：

json5
{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

命令名稱必須是小寫 a-z0-9_，1-32 個字元。前導 / 會自動移除。無法覆寫原生命令。

內嵌按鈕

控制內嵌按鈕的可用性：

| 設定 | 範圍 | |---------|-------| | capabilities.inlineButtons: "off" | 已停用 | | capabilities.inlineButtons: "dm" | 僅限私訊 | | capabilities.inlineButtons: "group" | 僅限群組 | | capabilities.inlineButtons: "all" | 私訊和群組皆可 | | capabilities.inlineButtons: "allowlist" | 兩者皆可 + 發送者過濾（預設） |

網路與代理

json5
{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Bot API 請求逾時（預設：500）
      network: {
        autoSelectFamily: false   // 停用 Happy Eyeballs（Node 22 預設開啟）
      },
      proxy: "socks5://127.0.0.1:1080"   // Bot API 的 SOCKS/HTTP 代理
    }
  }
}

疑難排解

機器人不回應

  1. 驗證權杖是否正確：
bash
curl "https://api.telegram.org/bot<TOKEN>/getMe"
  1. 檢查 OpenClaw 日誌：
bash
openclaw logs --follow

訊息未到達群組

  • 隱私模式必須停用（/setprivacy → Disable）或機器人必須是管理員
  • 使用 /activation always 測試（僅限當前工作階段）；透過設定中的 requireMention: false 持久化

IPv6 路由失敗

如果 IPv6 路由失敗，機器人可能會靜默停止回應。檢查 api.telegram.org 的 DNS：

bash
dig api.telegram.org AAAA

透過啟用 IPv6 出站或強制使用 IPv4 來修復：

bash
# 新增到 /etc/hosts
149.154.167.220  api.telegram.org

或使用網路設定：

json5
{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

長輪詢中止（Node 22+）

Node 22 對 AbortSignal 實例更加嚴格。請升級 OpenClaw 到最新版本或降級到 Node 20。

setMyCommands 失敗

出站 HTTPS/DNS 到 api.telegram.org 可能被封鎖。請檢查您的防火牆規則。

安全最佳實踐

  1. 永遠不要分享您的機器人權杖 — 如果洩露，請立即透過 BotFather 撤銷
  2. 使用配對或白名單進行私訊存取控制
  3. 設定群組政策以控制誰可以在群組中互動
  4. 安全地查找使用者 ID — 透過 openclaw logs --follow 或 Bot API 的 getUpdates 端點 — 避免使用第三方 ID 機器人
  5. 在生產環境中使用帶有密鑰的 webhook

後續步驟