OpenClaw Telegram Bot セットアップ：コマンド、ルーティング、マルチエージェントセッション

自動化ビルダーの皆さんへ — OpenClawをTelegramに接続して、DM、グループ、トピックからメッセージが飛び交うときにルーティングが実際にどのように機能するのか気になるなら、ぜひ読み進めてください。

私は過去2週間、OpenClawをTelegramで3つの異なる設定で実行しました：個人のDM、チームグループ、フォーラムトピック。デモシナリオではありません。セッションの分離を意図的に破り、同時リクエストで溢れさせ、ゲートウェイがマルチアカウントの設定をどのように処理するかを観察しました。

何度も自問したのは、複数のチャットを扱うときに、きちんとしたセッションの境界を維持できるのか、それともすべてが一つの混乱した会話スレッドに崩れるのか？

ここで見つけたことと、生き残った正確な設定パターンをお知らせします。

背景として、OpenClaw（以前はMoltbotとClawdbot）は、2026年初めにオープンソースの自律AIアシスタントとして10万以上の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

Open Telegram and search for @BotFather
1. Verified account has a blue checkmark
2. Send /start to see available commands
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
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:

Start Gateway with logging:

openclaw gateway --log-level debug

Send /start to your bot in Telegram
1. Should trigger pairing flow if dmPolicy: "pairing"
2. Check terminal for incoming update logs
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.

Security note: For production deployments, consider using DigitalOcean's hardened OpenClaw image which includes firewall rules, container isolation, and non-root execution by default.

Command Design That Scales

OpenClaw's command system is where routing logic starts to matter. The Gateway recognizes slash commands across all channels, but Telegram adds its own command autocomplete layer.

The official OpenClaw repository documents the full command set, but after real-world testing, only a handful prove essential.

Core command patterns

These are the commands I actually use in production setups (not the full list — just what survives real usage):

Command

Purpose

Session Scope

/new

Force new session (clears context)

Per-chat

/status

Show session + model + token usage

Current session

/activation

Toggle mention-only vs always-respond

Session-only*

/help

List available commands

N/A

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:

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

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

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

Check BotFather privacy settings

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

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

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

If channels.telegram.groups is defined, unlisted groups are ignored.
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
Review Gateway logs

openclaw logs --level debug --filter telegram

Common routing failures

Symptom

Likely Cause

Fix

Bot responds in DMs, silent in groups

Privacy mode ON

BotFather → Group Privacy → OFF

Some groups work, others don't

Groups whitelist active

Add "*": or specific IDs

Forum topics get mixed responses

Session key collision

Check :topic:<id> suffix in logs

No response at all

Wrong token or Gateway not running

openclaw status, verify token

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では、同じルーティングの課題を自動で処理します。プラットフォーム間でのセッションの分離、チャンネル追加時の手動設定の必要がありません。構成を再構築せずに多プラットフォームのルーティングをテストしたい場合は、実際のワークフローで試してみてセットアップがどのように機能するか確認してください。

FAQ

Q: ボットがグループメッセージに全く反応しない場合、最初にどこを確認すればいいですか？ BotFatherのプライバシー設定です。それがONに設定されている場合、ボットは直接の@メンションしか認識せず、その他はすべて静かに無視されます。BotFather → /mybots → Bot Settings → Group Privacy → OFFにします。これはグループ設定で「なぜ動かないのか」の最も一般的な理由です。

Q: グループのチャットIDを見つけるにはどうすればいいですか？ ボットをグループに追加し、任意のメッセージを送信した後、openclaw logs --followを実行します。受信したアップデートにchat.idが表示されます。グループの場合は負の数になります。それがホワイトリスト設定に入れる値です。

Q: ルーティングする各Telegramアカウントに別々のボットトークンが必要ですか？ はい。channels.telegram.accounts[]の各エントリーには、それぞれ独自のBotFatherトークンが必要です。一つのトークンで一つのボットのアイデンティティです。複数のボットを運用していて混在している場合、OpenClaw gateway config referenceではアカウントレベルのルーティング分離がどのように機能するかについて詳しく説明しています。

Q: フォーラムのトピックは、すべて手動で設定する必要がありますか？ 各トピックごとにシステムプロンプトを設定したい場合のみ必要です。OpenClawはセッションキーの分離を自動で処理します（:topic:<threadId> サフィックスを使用）、そのため、設定なしで会話は別々に管理されます。トピックごとに異なるエージェントの動作を望む場合にのみ手動の設定が必要です。

Q: Gateway再起動後にセッションがコンテキストを失うのは仕様ですか？ デフォルトではそうです。セッションの状態は再起動を跨いで保持されません。保持が必要な場合、OpenClawのクイックスタートガイドでGatewayレベルでの保持オプションを確認してください。

Q: VPS上でこれを設定しています。Telegram特有の知識はありますか？ サーバーのアウトバウンド接続がapi.telegram.orgに対してブロックされていないことを確認してください。安価なVPSプロバイダーはこれを制限する場合があります。それ以外は通常のセキュリティ強化が適用されます：非ルート実行、ファイアウォールルール、環境変数内のトークン（ハードコーディングしない）。OpenClawのVPSデプロイメントガイドは、最初からセットアップを始める場合の完全な手順をカバーしています。

Q: Telegram用のMoltbotを以前使っていました。移行は簡単ですか？ ほとんどはそうですが、設定構造が変更されました。切り替え後に競合や予期しない動作が発生した場合、Moltbot Telegramセットアップ比較を確認する価値があります。これは、両者間で何が変更されたかを示しています。