OpenClaw Telegram Bot 設定：指令、路由與多代理會話

嘿，自動化開發者們——如果您正在將 OpenClaw 連接到 Telegram，並想知道當訊息從私訊、群組和主題中湧入時，路由實際上是如何運作的，那麼請繼續閱讀。

我花了過去兩週的時間，將 OpenClaw 在三種不同的設置下運行於 Telegram：個人私訊、團隊群組和論壇主題。這不是演示場景，而是真實的路由測試，我故意破壞會話隔離，讓它承受大量的並發請求，觀察 Gateway 如何處理多帳戶配置。

我不斷思考的問題是：當您同時處理多個聊天時，這能否真正維持乾淨的會話邊界，還是會全部崩潰成一個混亂的對話線？

以下是我的發現，以及經得起考驗的配置模式。

背景介紹，OpenClaw（前身為 Moltbot 和 Clawdbot）在 2026 年初作為開源自主 AI 助手獲得了超過 100,000 個 GitHub 星標。由 Peter Steinberger 創建，它將像 Telegram 這樣的消息平台連接到本地或私有伺服器上運行的 AI 代理。

---

創建 Telegram Bot（BotFather）

Every OpenClaw Telegram setup starts with @BotFather, Telegram's official bot creation interface. This hasn't changed since Telegram launched bots — it's still the only way to generate API tokens.

What you'll need:

• Active Telegram account (phone verification required)
• 3 minutes for initial setup
• Bot token stored somewhere secure (I use a password manager)

Step-by-step bot creation

1. Open Telegram and search for @BotFather
   1. Verified account has a blue checkmark
   2. Send /start to see available commands
2. Create new bot with /newbot
   1. Bot name: What users see in conversations (can include spaces)
   2. Username: Must end with bot (e.g., YourProjectBot)
   3. Username must be globally unique across Telegram
3. Save your API token immediately
   1. Format: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
   2. Treat this like a password — anyone with this token controls your bot
   3. If compromised, use /revoke in BotFather to generate a new one

Critical BotFather settings (optional but recommended):

/setjoingroups  → Allow/deny adding bot to groups
/setprivacy     → OFF = bot sees all group messages
                  ON = bot only sees mentions and commands

I learned this the hard way: if you set privacy to ON and wonder why your bot ignores group messages, that's why. OpenClaw's routing expects full message access by default.

---

Connect Token + Verify Updates

Getting the token into OpenClaw is where most setup guides stop — but that's where real testing should start.

Basic connection config

OpenClaw supports two token input methods:

Environment variable (quick testing):

export TELEGRAM_BOT_TOKEN="your_token_here"
openclaw gateway

Config file (production approach):

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      "dmPolicy": "pairing"
    }
  }
}

Verification test sequence

Here's the sequence I run every time to confirm the Gateway actually sees Telegram updates:

1. Start Gateway with logging:

openclaw gateway --log-level debug

1. Send /start to your bot in Telegram
   1. Should trigger pairing flow if dmPolicy: "pairing"
   2. Check terminal for incoming update logs
2. Monitor update stream:

openclaw logs --follow

Common failure point: Bot token typo. If you see 401 Unauthorized in logs, regenerate the token in BotFather and update your config. Don't waste an hour troubleshooting like I did.

安全注意事項： 在生產部署中，考慮使用 DigitalOcean 的強化 OpenClaw 映像，其預設包含防火牆規則、容器隔離及非 root 執行。

---

可擴展的指令設計

OpenClaw 的指令系統是路由邏輯開始發揮作用的地方。Gateway 能識別所有頻道的斜線指令，但 Telegram 添加了自己的指令自動完成層。

OpenClaw 官方儲存庫記錄了完整的指令集，但經過實際測試後，只有少數指令被證明是必需的。

核心指令模式

這些是我在生產設定中實際使用的指令（不是完整列表，只是經過實際使用後留下的）：

Important: /activation always only affects the current session. To persist it, add it to your config's requireMention settings.

Setting up custom commands in BotFather

This is what makes your bot feel native in Telegram:

1. In BotFather: /mybots → Select your bot → Edit Commands
2. Send command list (one per line):

new - Start fresh sessionstatus - Check session statehelp - Show all commands

1. These appear in Telegram's / autocomplete menu

Reality check: I initially set up 15 commands. After two weeks, I only use 4. Start minimal.

For deeper understanding of Telegram's bot architecture, see the official Telegram Bot tutorial which covers the Bot API fundamentals.

---

Routing by Chat/User/Topic

This is where OpenClaw's session architecture either makes sense or falls apart. Session keys determine whether conversations stay isolated or bleed together.

Session key structure

OpenClaw generates session keys using this pattern:

agent:<agentId>:telegram:<chatType>:<chatId>[:topic:<topicId>]

Breakdown:

• DMs: All messages from one user → shared main session
• Groups: Each group → isolated session (telegram:group:<chatId>)
• Forum topics: Each topic → separate session (:topic:<threadId> suffix)

Multi-account routing config

Here's a real config I ran for testing three separate Telegram bots routing to different agents:

{
  "channels": {
    "telegram": {
      "accounts": [
        {
          "name": "personal",
          "botToken": "token1...",
          "routing": { "agent": "main" }
        },
        {
          "name": "work",
          "botToken": "token2...",
          "routing": { "agent": "work-agent" }
        },
        {
          "name": "testing",
          "botToken": "token3...",
          "routing": { "agent": "sandbox" }
        }
      ]
    }
  }
}

Each account routes to a separate agent workspace with independent memory and tools. No cross-contamination.

Group routing with mention controls

Default behavior: groups require @mention to trigger responses. Override per-group:

{
  "channels": {
    "telegram": {
      "groups": {
        "*": { "requireMention": true },
        "-1001234567890": { 
          "requireMention": false 
        }
      }
    }
  }
}

Group ID discovery: Add bot to group, send a message, check openclaw logs --follow for the chat.id value (always negative for groups).

Forum topic isolation

Telegram forums add message_thread_id to messages. OpenClaw appends :topic:<threadId> to session keys automatically.

Critical edge case I hit: Topic ID 1 (general topic) requires special handling. OpenClaw omits message_thread_id when sending to topic 1 because Telegram rejects it.

Config example for per-topic system prompts:

{
  "telegram": {
    "groups": {
      "-1003595003457": {
        "requireMention": false,
        "topics": {
          "14": {
            "requireMention": false,
            "systemPrompt": "You are a coding assistant."
          },
          "27": {
            "systemPrompt": "You focus on deployment issues."
          }
        }
      }
    }
  }
}

Each topic maintains isolated conversation history.

---

Debugging Missed Messages

When messages disappear into the void, it's usually one of these three culprits.

Diagnostic checklist

1. Check BotFather privacy settings

/mybots → Your Bot → Bot Settings → Group Privacy → OFF

1. If ON, bot only sees mentions — not regular messages.
2. Verify group whitelist

openclaw logs --follow | grep "skipping group message"

1. If channels.telegram.groups is defined, unlisted groups are ignored.
2. Confirm bot membership
   1. Bot must be added as a member (not just admin with no read access)
   2. Test: send a message, check if bot's "last seen" timestamp updates
3. Review Gateway logs

openclaw logs --level debug --filter telegram

Common routing failures

Session hygiene checks

I run this sequence weekly to catch routing drift:

# List active sessions
openclaw sessions list
# Check specific session state
openclaw sessions show <sessionKey>
# Force session cleanup (last resort)
openclaw sessions prune --older-than 7d

When sessions leak: If you see context bleeding between chats, it's usually a config error where multiple chats map to the same session key. Review channels.telegram.accounts[].routing.agent settings.

---

What Actually Worked Long-Term

After two weeks of daily use across three different Telegram setups, here's what survived:

Stable config pattern

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "env:TELEGRAM_BOT_TOKEN",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Why this works:

• DM pairing prevents unauthorized access
• Wildcard group policy with mention requirement = safe defaults
• Token from env var = easier rotation without touching config

What didn't scale

• Custom commands beyond /new, /status, /help — Users forget them
• Per-topic system prompts — Maintenance burden grows fast
• Multiple accounts without clear routing rules — Session chaos

Boundary conditions

OpenClaw Telegram routing is solid for:

• Personal DM automation (single user)
• Small team groups (< 20 active members)
• Forum topics with distinct purposes

It gets messy when:

• You're managing 10+ groups without config discipline
• Users expect instant responses (add queue monitoring)
• Session state matters across Gateway restarts (implement persistence checks)

Security reminder: As noted in security analysis, OpenClaw stores session transcripts and credentials locally. Treat your ~/.openclaw directory as sensitive — use encrypted drives and restrict file permissions.

---

如果 OpenClaw + Telegram 能幫你到達目的地，那就用它吧。只需保持會話密鑰清潔，並確保知道哪些群組使用哪個代理。

在 Macaron，我們自動處理相同的路由挑戰——跨平台的會話隔離，添加頻道時無需手動配置修補。如果你想測試多平台路由，而不必每次擴展時重建配置，試試真正的工作流程，看看它如何處理你的設置。

常見問題

問：我的機器人完全不回應群組消息。我應該先檢查哪裡？ BotFather 隱私設置。如果設置為開啟，機器人只會看到直接 @提及——其他所有消息都會被靜默丟棄。前往 BotFather → /mybots → 機器人設置 → 群組隱私 → 將其關閉。這是群組設置中最常見的「為什麼它不起作用」的原因。

問：我如何找到我群組的聊天 ID？ 將機器人添加到群組中，發送任何消息，然後運行 openclaw logs --follow。在接收到的更新中會顯示 chat.id——對於群組來說，它將是一個負數。這就是你在白名單配置中放入的值。

問：我是否需要為每個我正在路由的 Telegram 帳戶提供單獨的機器人令牌？ 是的。channels.telegram.accounts[] 中的每個條目都需要自己的 BotFather 令牌。一個令牌，一個機器人身份。如果你運行多個機器人並且它們相互干擾，OpenClaw gateway config reference 會分解帳戶級別路由隔離實際如何運作。

Q: 論壇主題——我需要手動配置每一個嗎？ 只有在您需要針對每個主題設置系統提示時才需要。OpenClaw 自動處理會話鍵隔離（:topic:<threadId> 後綴），因此會話在無需任何配置的情況下保持獨立。只有當您希望每個主題的代理行為不同時，才需要手動設置。

Q: 網關重啟後，會話經常失去上下文。這是預期的嗎？ 默認情況下是的——會話狀態不會在重啟後保留，除非您已配置持久性。如果這對您的使用案例來說是個問題，請查看 OpenClaw 快速入門指南 以了解網關層級的持久性選項。

Q: 我正在 VPS 上設置這個。有什麼 Telegram 特定的事項需要注意嗎？ 確保您的伺服器對 api.telegram.org 的出站連接沒有被封鎖——一些便宜的 VPS 提供商會限制這一點。除此之外，通常的安全措施適用：非 root 執行、防火牆規則、環境變量中的 token 而不是硬編碼。若您從頭開始設置，OpenClaw VPS 部署指南 涵蓋了完整的設置步驟。

Q: 我以前用 Moltbot 運行 Telegram。遷移簡單嗎？ 基本上是的，但配置結構有所改變。若切換後遇到衝突或意外行為，請查看 Moltbot Telegram 設置比較——它詳細說明了兩者之間的變化。