OpenClaw Telegram 頻道
即時通訊
簡單
透過 grammY Bot API 框架將 OpenClaw 連接至 Telegram。使用 @BotFather 建立 Telegram 機器人，取得 token，幾分鐘內就能讓 AI 助手在 Telegram 上執行。預設使用長輪詢模式，可選 Webhook 模式。這是最容易設定的頻道之一，支援內嵌按鈕、貼圖、表情回應和群組聊天等豐富功能。
快速資訊
難度簡單
分類即時通訊
支援功能數6 / 6
Telegram 支援功能
文字訊息
支援
媒體與檔案
支援
表情回應
支援
討論串
支援
語音訊息
支援
群組聊天
支援
Telegram 前置條件
- 一個 Telegram 帳號
- 透過 @BotFather 取得的 Bot Token（向 @BotFather 傳送 /newbot）
- OpenClaw Gateway 已執行並設定完成
- 伺服器安裝 Node.js 18+
Telegram 快速設定
1
透過 @BotFather 建立機器人
開啟 Telegram，搜尋 @BotFather，傳送 /newbot。按提示為機器人命名並取得 API token。妥善保存此 token——設定時需要用到。
2
新增 Telegram 頻道設定
在 ~/.openclaw/openclaw.json 中新增 Telegram 頻道設定。將 @BotFather 提供的 bot token 貼到 botToken 欄位。設定 dmPolicy（pairing、allowlist 或 open）來控制誰可以與您的 AI 助手對話。
3
啟動 Gateway 並測試
啟動 Gateway 程序。在 Telegram 中搜尋您的機器人並傳送訊息。如果使用預設的 pairing 策略，透過 'openclaw pairing approve telegram <code>' 審批發送者。OpenClaw 應透過 AI 助手自動回覆。
Telegram 設定範例
config.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
"dmPolicy": "pairing"
}
}
}Telegram 深入了解
架構概述
OpenClaw 透過 grammY 框架連接到 Telegram——這是一個現代的、TypeScript 優先的 Telegram Bot API 函式庫。機器人預設使用長輪詢模式，即定期向 Telegram 伺服器查詢新的更新。這種方式開箱即用，無需額外設定。
您也可以切換到 Webhook 模式用於正式環境部署。在 Webhook 模式下，Telegram 會主動將更新推送到您的伺服器端點，效率更高、延遲更低。
長輪詢可在 NAT 和防火牆後正常運作，無需額外設定。Webhook 模式需要一個公開可存取的 HTTPS 端點。
可以透過 TELEGRAM_BOT_TOKEN 環境變數或設定檔 channels.telegram.botToken 欄位儲存您的 bot token。
透過 @BotFather 建立機器人
BotFather 是 Telegram 官方的機器人建立和管理工具。以下是詳細步驟：
1. 開啟 Telegram，搜尋 @BotFather
2. 傳送 /newbot 開始建立流程
3. 為機器人選擇一個顯示名稱（如「我的 AI 助手」）
4. 選擇一個以 'bot' 結尾的使用者名稱（如 "my_ai_assistant_bot"）
5. BotFather 會回傳一個 API token——請妥善保存
建立後，您還可以使用 BotFather 指令進一步自訂：
• /setdescription — 設定機器人簡介中顯示的描述
• /setabouttext — 設定「關於」部分文字
• /setuserpic — 上傳頭像
• /setprivacy — 切換群組訊息的隱私模式
請保管好您的 bot token。任何擁有該 token 的人都可以控制您的機器人。如果洩露，請在 BotFather 中使用 /revoke 產生新的 token。
私訊策略
DM（私訊）策略控制誰可以與您的 AI 助手進行私聊。OpenClaw 支援三種策略：
• pairing（預設）— 新使用者需要通過配對流程。他們傳送訊息後會收到一個配對碼（有效期 1 小時），您在終端透過指令審批或拒絕。審批後即可自由聊天。
• allowlist — 只有在 allowFrom 清單中明確列出的數字使用者 ID 才能與機器人對話。其他人會被靜默忽略。
• open — 任何向機器人傳送訊息的人都會得到回覆。在正式環境中請謹慎使用。
openclaw.json
{
"channels": {
"telegram": {
"dmPolicy": "pairing",
"allowFrom": [123456789, 987654321]
}
}
}要查找使用者的 Telegram 數字 ID，可以使用 @userinfobot 或在使用者傳送訊息時查看 Gateway 日誌。
群組聊天管理
OpenClaw 支援 Telegram 群組聊天，並提供彈性的存取控制，透過兩個獨立機制：
1. 群組白名單 — 決定允許哪些群組。可以是所有群組，或僅限 channels.telegram.groups 中列出的群組。
2. 群組策略 — 控制允許的群組內傳送者權限：
• open — 任何群組成員都可以觸發機器人
• allowlist — 僅已審批的傳送者可以互動
• disabled — 完全忽略群組訊息
預設情況下，機器人在群組中需要 @提及 才會回覆。您可以更改此行為：
• 使用 /activation always 指令（僅當前工作階段生效）回覆所有訊息
• 在設定中設定 requireMention: false 永久開啟全部回覆
openclaw.json
{
"channels": {
"telegram": {
"groupPolicy": "open",
"requireMention": false,
"groups": ["-1001234567890"]
}
}
}對於論壇風格的群組（話題），OpenClaw 使用執行緒 ID 隔離每個話題，並可以套用每個話題的設定覆寫。
要讓機器人在非管理員身份下看到群組中的所有訊息，您必須在 BotFather 中透過 /setprivacy 關閉隱私模式，然後將機器人移出群組並重新加入。
訊息格式與串流傳輸
OpenClaw 提供多種訊息格式化和傳輸選項：
格式化：出站訊息使用 Telegram 的 HTML 解析器，自動從 Markdown 風格轉換。如果 HTML 解析失敗，訊息會以純文字重試。
串流傳輸：草稿氣泡在私聊中支援部分回覆串流傳輸。兩種模式可選：
• partial（預設）— AI 產生時逐步更新單條訊息
• block — 以完整區塊的方式分段傳送
文字預設按 4,000 字元分塊（Telegram 限制）。啟用 chunkMode: "newline" 可按段落邊界分割，而非硬性截斷。
openclaw.json
{
"channels": {
"telegram": {
"streamMode": "partial",
"chunkMode": "newline"
}
}
}內嵌按鈕
OpenClaw 支援 Telegram 的互動式內嵌鍵盤按鈕。啟用後，AI 可以在訊息下方展示按鈕供使用者點選。點選按鈕會將回呼資料以格式化訊息的形式傳送回代理。
可用模式：
• off — 停用按鈕（預設）
• dm — 僅在私聊中啟用
• group — 僅在群組聊天中啟用
• all — 全部啟用
• allowlist — 按傳送者授權限制
openclaw.json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}貼圖與媒體
OpenClaw 支援處理 Telegram 貼圖和媒體檔案：
貼圖：靜態貼圖會被下載並透過視覺分析處理，產生的描述會被快取以避免重複 API 呼叫。動畫和影片貼圖跳過處理。代理可以使用儲存的檔案 ID 傳送貼圖，並透過描述、表情或貼圖包名稱搜尋快取的貼圖。
媒體：預設媒體上傳/下載限制為 5 MB。機器人支援傳送和接收圖片、文件、音訊檔案和影片。
在代理設定中啟用 sticker 動作，以允許透過檔案 ID 或快取搜尋傳送貼圖。
表情回應
OpenClaw 支援 Telegram 的表情回應系統，包括接收和傳送表情回應：
收到的回應會產生系統事件，新增到代理上下文中。您可以設定哪些回應觸發通知：
• off — 不通知
• own — 僅機器人訊息的回應
• all — 聊天中所有回應
機器人也可以傳送回應。設定回應能力等級：
• off — 不回應
• ack — 處理時傳送確認回應（預設）
• minimal — 基本回應
• extensive — 完整表情範圍
openclaw.json
{
"channels": {
"telegram": {
"reactionNotifications": "own",
"reactionLevel": "ack"
}
}
}指令與工具
原生機器人指令（如 /status、/reset）會自動註冊到 Telegram 的機器人指令選單中，方便使用者發現。自訂指令可以透過設定新增，但僅作為選單入口使用。
代理還支援工具操作：
• 向特定聊天傳送訊息
• 對訊息傳送表情回應
• 刪除訊息
• 使用 [[reply_to:<id>]] 標籤回覆特定訊息
在代理回覆中使用 [[reply_to_current]] 可直接回覆使用者的當前訊息。
在回覆中包含 [[audio_as_voice]] 或在工具呼叫中設定 asVoice: true 可強制使用語音訊息格式。
Webhook 模式
對於正式環境部署，推薦使用 Webhook 模式而非長輪詢。在 Webhook 模式下，Telegram 會主動將更新推送到您的伺服器，降低延遲和資源消耗。
要啟用 Webhook，在設定中設定 webhookUrl 和 webhookSecret。本機端點預設繫結到 0.0.0.0:8787。
openclaw.json
{
"channels": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram/webhook",
"webhookSecret": "your-random-secret-string"
}
}
}從輪詢切換到 Webhook 模式時，Gateway 會在啟動時自動向 Telegram 註冊 Webhook URL。
Webhook 模式需要一個公開可存取的 HTTPS 端點。請確保您的伺服器擁有有效的 SSL 憑證。
Telegram 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 啟用或停用 Telegram 頻道 |
| botToken | string | "" | 來自 @BotFather 的 Telegram Bot API token。也可使用 TELEGRAM_BOT_TOKEN 環境變數 |
| dmPolicy | string | "pairing" | 控制誰可以私訊機器人。選項：pairing、allowlist、open |
| allowFrom | number[] | [] | 允許與機器人對話的 Telegram 數字使用者 ID（當 dmPolicy 為 allowlist 時） |
| groupPolicy | string | "disabled" | 群組聊天策略。選項：disabled、open、allowlist |
| groups | string[] | [] | 允許的群組聊天 ID 清單。為空且 groupPolicy 非 disabled 時允許所有群組 |
| requireMention | boolean | true | 機器人在群組中是否需要 @提及 才回覆 |
| streamMode | string | "partial" | AI 回覆的串流模式。選項：partial（逐步更新）、block（分塊傳送） |
| chunkMode | string | "split" | 長回覆的處理方式。選項：split（硬字元限制）、newline（按段落分割） |
| webhookUrl | string | "" | Webhook 模式的 HTTPS URL。設定後從輪詢切換為 Webhook |
| webhookSecret | string | "" | Webhook 驗證的密鑰 token |
| reactionNotifications | string | "off" | 哪些回應觸發通知。選項：off、own、all |
| reactionLevel | string | "ack" | 機器人的回應能力。選項：off、ack、minimal、extensive |
| capabilities.inlineButtons | string | "off" | 內嵌按鈕模式。選項：off、dm、group、all、allowlist |
| configWrites | boolean | true | 超級群組升級時自動遷移聊天 ID。設為 false 可停用 |
enabled
Type: booleanDefault: true
啟用或停用 Telegram 頻道
botToken
Type: stringDefault: ""
來自 @BotFather 的 Telegram Bot API token。也可使用 TELEGRAM_BOT_TOKEN 環境變數
dmPolicy
Type: stringDefault: "pairing"
控制誰可以私訊機器人。選項：pairing、allowlist、open
allowFrom
Type: number[]Default: []
允許與機器人對話的 Telegram 數字使用者 ID（當 dmPolicy 為 allowlist 時）
groupPolicy
Type: stringDefault: "disabled"
群組聊天策略。選項：disabled、open、allowlist
groups
Type: string[]Default: []
允許的群組聊天 ID 清單。為空且 groupPolicy 非 disabled 時允許所有群組
requireMention
Type: booleanDefault: true
機器人在群組中是否需要 @提及 才回覆
streamMode
Type: stringDefault: "partial"
AI 回覆的串流模式。選項：partial（逐步更新）、block（分塊傳送）
chunkMode
Type: stringDefault: "split"
長回覆的處理方式。選項：split（硬字元限制）、newline（按段落分割）
webhookUrl
Type: stringDefault: ""
Webhook 模式的 HTTPS URL。設定後從輪詢切換為 Webhook
webhookSecret
Type: stringDefault: ""
Webhook 驗證的密鑰 token
reactionNotifications
Type: stringDefault: "off"
哪些回應觸發通知。選項：off、own、all
reactionLevel
Type: stringDefault: "ack"
機器人的回應能力。選項：off、ack、minimal、extensive
capabilities.inlineButtons
Type: stringDefault: "off"
內嵌按鈕模式。選項：off、dm、group、all、allowlist
configWrites
Type: booleanDefault: true
超級群組升級時自動遷移聊天 ID。設為 false 可停用
Telegram 常見問題
Telegram 故障排除
機器人在群組中不被提及就不回覆
Telegram 機器人預設啟用隱私模式。啟用時，機器人只能接收 @提及 它的訊息或以斜線指令開頭的訊息。
在 BotFather 中關閉隱私模式：向 @BotFather 傳送 /setprivacy，選擇您的機器人，然後選擇 'Disable'。接著將機器人移出群組並重新加入。同時在 OpenClaw 設定中設定 requireMention: false（如果您希望機器人回覆所有訊息）。
機器人不回覆任何訊息
bot token 可能不正確，Gateway 可能未執行，或存在網路連線問題。
透過 Telegram Bot API 直接測試驗證 token 是否正確：curl https://api.telegram.org/bot<token>/getMe。檢查 Gateway 日誌中的連線錯誤。對於 IPv6 路由問題導致的靜默失敗，可強制 api.telegram.org 使用 IPv4 解析，或透過 dig 指令驗證 DNS 回傳可用位址。
Webhook 未收到更新
Webhook URL 不可公開存取，SSL 憑證無效，或 Webhook 未正確註冊。
驗證 Webhook URL 可從網際網路存取（用 curl 測試）。確保 SSL 憑證有效且非自簽名。使用以下指令檢查 Webhook 狀態：curl https://api.telegram.org/bot<token>/getWebhookInfo。重新啟動 Gateway 以重新註冊 Webhook。
訊息被截斷或分割不正確
Telegram 有 4,096 字元的訊息限制。較長的 AI 回覆會被自動分塊。
將 chunkMode 設為 'newline' 以按段落邊界分割，而非硬性字元限制截斷。您也可以在設定中調整最大文字分塊大小。