Skip to main content

Telegram Runbook（OpenClaw）

目標：快速定位「為何 Telegram 收不到 / 回不了」，並提供可重現修復流程。
適用：OpenClaw + Telegram Bot（BotFather token）。

0) 先看症狀，再動手​

先回答三個問題：

  1. Gateway 有沒有活著？
  2. Telegram health 是 OK 還是 WARN？
  3. 是不是其實沒完成 pairing（最常見）？

1) 30 秒快查版​

/app/dist/index.js status --deep

看 Health：

  • Gateway reachable + Telegram OK
    → 通道層通常正常，優先檢查 pairing / DM 政策。
  • Telegram WARN (fetch failed)
    → 優先檢查 token、設定、網路（含 IPv6/代理問題）。

2) 正常路徑（新 bot 上線）​

  1. 設定 token（不要把真 token 寫進文件）
/app/dist/index.js config set channels.telegram.botToken '"<BOT_TOKEN>"' --json
  1. 啟用 Telegram channel（如未啟用）
/app/dist/index.js config set channels.telegram.enabled true --json
/app/dist/index.js config set plugins.entries.telegram.enabled true --json
  1. 驗證健康狀態
/app/dist/index.js status --deep

期望：Telegram OK。

3) 核心卡點：pairing（dmPolicy=pairing）​

若 status --deep 顯示 Telegram OK，但你 DM bot 沒回：

3.1 使用者側​

  • 先對 bot 發 /start
  • 取得 pairing code（例如 EURZEYDZ）

3.2 管理側​

列出待批准請求：

/app/dist/index.js pairing list telegram

批准 code：

/app/dist/index.js pairing approve telegram <CODE>

批准後再測：

  • Telegram 傳 ping-final
  • 期望收到 pong-final

4) 若仍失敗：分層排查​

A. Telegram WARN: fetch failed​

  1. 重新覆寫 token（避免空白/錯字/舊 token）
  2. 再跑 status --deep
  3. 若間歇性失敗，檢查網路 egress（DNS/IPv6/Proxy）

參考檢查（主機網路）：

curl -I --max-time 10 https://api.telegram.org

B. Telegram OK 但沒回覆​

  1. 檢查 channels.telegram.dmPolicy
    • pairing：需要先 approve pairing
    • open：任何 DM 皆可（測試可暫開，正式建議配對/allowlist）
  2. 確認使用者是否已 /start
  3. 再測 ping/pong

5) 常見誤區​

  • Telegram OK 不等於 這個使用者已配對。
  • 同時段不同節點可能看到短暫不同 health（瞬時波動）。
  • 只看控制台訊息不夠，最後一定要做一次實際 ping/pong。

6) 驗收標準（Done）​

滿足以下三項才算修復完成：

  1. status --deep 顯示 Telegram OK
  2. pairing list telegram 無待處理（或目標帳號已批准）
  3. 使用者在 Telegram 發 ping-*，可收到 pong-*

7) 安全注意事項​

  • 不要把真實 bot token 寫進 repo、文件、聊天室。
  • 文件中僅保留 "<BOT_TOKEN>" 樣板。
  • 若需截圖/貼 log，先遮罩 token、chat id、個資。

8) 附：常用指令清單​

# 健康檢查
/app/dist/index.js status --deep

# 查看 pairing 請求
/app/dist/index.js pairing list telegram

# 批准 pairing code
/app/dist/index.js pairing approve telegram <CODE>

# 開放式 DM（臨時測試用，測完建議改回 pairing/allowlist）
/app/dist/index.js config set channels.telegram.dmPolicy '"open"' --json