Telegram (Bot API) のセットアップガイド

ボットを開発する際、最初のハードルになるのが環境構築と権限設定です。特にメッセージを確実に受け取り、DM やグループで正しく動作させるための設定は、意外と手間がかかるものです。

開発をスムーズに進めるためには、まず土台をしっかりと固めることが重要です。今回は Telegram を使って、最短でボットを稼働させる方法を紹介します。このガイドでは grammY を介した構成を扱い、デフォルトの Long polling モードで進めます。

必要なもの

Telegram アカウント
@BotFather とのチャット（トークン取得用）

クイックスタート

最短 5 分で Telegram ボットを稼働させるための手順です。

1. BotFather でトークンを作成する

Telegram を開き、@BotFather を探してください。ハンドルの綴りが正確に @BotFather であることを確認しましょう。

/newbot を実行し、指示に従ってトークンを保存します。

2. トークンと DM ポリシーを設定する

設定ファイルに以下の内容を記述します。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

環境変数 TELEGRAM_BOT_TOKEN を使うこともできますが、これはデフォルトアカウントのみに適用されます。

3. Gateway を起動して DM を承認する

以下のコマンドを実行して、ペアリングを完了させます。

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

ペアリングコードの有効期限は 1 時間です。

4. ボットをグループに追加する

ボットをグループに追加した後、アクセスモデルに合わせて channels.telegram.groups と groupPolicy を設定してください。

[!NOTE] トークンの解決順序はアカウントを認識します。実際には、設定ファイルの値が環境変数よりも優先されます。

トラブルシューティング

Telegram 側でよく発生する問題と解決策です。

グループでメッセージが受信できない: Telegram ボットはデフォルトで Privacy Mode が有効になっており、受信できるメッセージが制限されています。すべてのメッセージを表示するには、/setprivacy で無効にするか、ボットをグループ管理者に設定してください。設定変更後は、一度ボットをグループから削除して再追加する必要があります。
管理権限の不足: グループ設定でボットを管理者に昇格させると、すべてのメッセージを受信できるようになります。常に動作させたい場合に有効です。

また、BotFather で以下の設定を確認することもおすすめします。

/setjoingroups: グループへの追加を許可するかどうか
/setprivacy: グループ内での可視性の動作

セットアップで困ったことがあれば、AI Setup Assistant で質問してみてください。

次のステップ

せっかく作ったボットが、知らない人から勝手に使われたり、予期せぬグループで勝手に動作したりするのは困りますよね。セキュリティとプライバシーをしっかり守るために、アクセス制御は最初に設定しておくべき重要なステップです。

OpenClaw では、DM（ダイレクトメッセージ）とグループチャットの両方で、誰がボットと対話できるかを細かくコントロールできます。

## 必要なもの

- Telegram Bot Token
- `openclaw` CLI
- 設定ファイル（JSON5 形式）

## クイックスタート

まずは、最も一般的な DM とグループの制御方法を見ていきましょう。

### DM のポリシー設定

`channels.telegram.dmPolicy` を使用して、個人チャットでのアクセス権を管理します。以下の 4 つのオプションから選択してください：

- `pairing` (デフォルト): ペアリングされたユーザーのみ許可
- `allowlist`: 指定したリストに含まれるユーザーのみ許可
- `open`: 全員に許可（`allowFrom` に `"*"` を含める必要があります）
- `disabled`: DM を完全に無効化

ユーザーを特定するための ID は、`channels.telegram.allowFrom` に記述します。数値 ID またはユーザー名を使用でき、`telegram:` や `tg:` といったプレフィックスも自動的に処理されます。

### グループポリシーと許可リスト

グループチャットでは、2 つの独立したコントロールが可能です。

1. **許可するグループの制限** (`channels.telegram.groups`)
   - `groups` の設定がない場合：すべてのグループで動作します。
   - `groups` を設定した場合：許可リストとして機能し、特定の ID または `"*"` を指定したグループのみで動作します。

2. **グループ内での送信者の制限** (`channels.telegram.groupPolicy`)
   - `open`: 全員がボットと対話可能
   - `allowlist` (デフォルト): 許可されたユーザーのみ
   - `disabled`: グループ内での対話を無効化

グループ内のフィルターには `groupAllowFrom` を使用します。これが設定されていない場合は、DM 用の `allowFrom` 設定が適用されます。

特定のグループでのみ、全メンバーにボットの使用を許可する設定例は以下の通りです：

```json
{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

メンションによる動作設定

デフォルトでは、グループ内での返信にはメンションが必要です。

ボットが反応するトリガーは以下の通りです：

ネイティブの @botusername メンション
設定で定義されたパターン：
- agents.list[].groupChat.mentionPatterns
- messages.groupChat.mentionPatterns

また、セッションごとに以下のコマンドで動作を切り替えることもできます。これらは一時的な状態として保存されます：

/activation always: 常に反応
/activation mention: メンション時のみ反応

設定を永続化したい場合は、以下のように設定ファイルに記述します：

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

トラブルシューティング

設定に必要な Telegram のユーザー ID やグループ ID が分からない場合は、以下の方法で確認してください。

Telegram ユーザー ID を見つける

サードパーティのボットを使わない、より安全な方法が推奨されます：

ボットに DM を送る
openclaw logs --follow を実行する
ログ内の from.id を確認する

公式の Bot API を使用する方法：

curl "https://api.telegram.org/bot\<bot_token\>/getUpdates"

サードパーティのツール（プライバシー面で注意が必要）：

@userinfobot または @getidsbot を使用

グループ ID を取得する

グループのメッセージを @userinfobot や @getidsbot に転送する
openclaw logs --follow を実行中にグループで発言し、chat.id を読み取る
Bot API の getUpdates エンドポイントを確認する

設定で困ったことがあれば、AI Setup Assistant に聞いてみてください。

次のステップ

複数のチャットやスレッドが混在する中で、メッセージを正確にさばくのは大変ですよね。特に Telegram のような複雑な構造を持つプラットフォームでは、セッションの管理やルーティングが正しく行われないと、ボットの応答が混乱する原因になります。

この記事では、Telegram における Runtime behavior（実行時の挙動）がどのように整理されているかを解説します。開発者が一から複雑なロジックを組まなくても、確実に応答を返せる仕組みが整っています。

必要なもの

Telegram Bot API の基礎知識
OpenClaw の実行環境
agents.defaults.maxConcurrent の設定値（並行処理の調整用）

クイックスタート

最短で挙動を理解するための 4 つのステップです。

Gateway の起動: Telegram は常に Gateway プロセスによって管理されます。
ルーティングの確認: 受信したメッセージは、自動的に元のチャネルへ返信されるよう設計されています。
セッションの分離: グループやフォーラムのスレッドごとにセッションが独立していることを確認してください。
並行処理の設定: agents.defaults.maxConcurrent を使用して、全体の負荷を調整します。

Runtime behavior の詳細

プロセスとルーティング

Telegram は Gateway プロセスによって所有されます。ルーティングは決定論的（deterministic）であり、Telegram から受信したメッセージへの返信は、必ず Telegram へ戻ります。モデルが勝手に送信チャネルを選択することはありません。

受信したメッセージは、リプライのメタデータやメディアのプレースホルダーを含む「共有チャネルエンベロープ」に正規化されます。これにより、内部処理がスムーズになります。

セッションの隔離

グループセッションは、グループ ID ごとに隔離されています。フォーラム形式のトピックについては、セッションキーに :topic:<threadId> が付与されるため、トピック間の混線を防ぐことができます。

DM（ダイレクトメッセージ）で message_thread_id が含まれる場合、OpenClaw はスレッドを認識したセッションキーでルーティングを行い、返信時にもスレッド ID を保持します。

Long Polling と並行処理

Long Polling には grammY runner を使用しており、チャットごと、あるいはスレッドごとにシーケンス制御が行われます。全体の並行処理数は、agents.defaults.maxConcurrent の設定に従って制御されます。

サポートされない機能

Telegram Bot API の制約により、以下の機能は利用できません。

既読確認: sendReadReceipts はサポートされていないため、設定しても適用されません。

トラブルシューティング

`sendReadReceipts` を設定しても既読にならない

これは不具合ではありません。Telegram Bot API 自体に既読確認の機能がないため、このパラメータは無視されます。

特定のスレッドに返信が届かない

フォーラム形式の場合、message_thread_id が正しく渡されているか確認してください。OpenClaw はこれを使用してスレッドを識別しますが、ID が欠落すると正しいトピックに返信できない可能性があります。

さらに詳しい設定や、個別のユースケースについて質問がある場合は、AI Setup Assistant を活用してください。

次のステップ

Telegram ボットを開発していると、ユーザー体験を一段上のレベルに引き上げたいと感じることがありますよね。単にメッセージを返すだけでなく、入力中の「…」というアニメーションを効果的に見せたり、独自のメニューボタンを配置したり、あるいはステッカーを自在に操ったりしたいものです。

しかし、これらのネイティブ機能を API で一つずつ実装するのは意外と手間がかかります。OpenClaw では、これらの Telegram 特有の機能を設定ファイルだけで簡単に制御できるよう設計されています。この記事では、Telegram チャンネルで利用できる高度な機能を網羅的に紹介します。

必要なもの

このガイドの内容を試すには、以下の準備が必要です。

OpenClaw の基本セットアップが完了していること
有効な Telegram ボットトークン
device-pair プラグイン（デバイスペアリング機能を使用する場合のみ）
ボットのトピック機能が有効化されていること（グループ内でトピックを使用する場合）

クイックスタート

まずは、最も人気のある機能である「ドラフトストリーミング」と「カスタムコマンド」を 5 分で設定してみましょう。

ストリーミングの有効化: デフォルトで partial モードが有効ですが、より細かく制御したい場合は channels.telegram.streamMode を設定します。
コマンドの登録: customCommands を設定ファイルに追加して、ボットのメニューをカスタマイズします。
インラインボタンの許可: inlineButtons のスコープを allowlist や all に設定して、インタラクティブな操作を可能にします。

{
  channels: {
    telegram: {
      streamMode: "partial",
      customCommands: [
        { command: "generate", description: "画像を生成します" },
      ],
      capabilities: {
        inlineButtons: "allowlist",
      },
    }
  }
}

主要機能リファレンス

1. Telegram DM でのドラフトストリーミング

OpenClaw は、Telegram のドラフトバブル（sendMessageDraft）を使用して、返信の途中経過をストリーミング表示できます。

要件:
- channels.telegram.streamMode が "off" 以外（デフォルトは "partial"）
- プライベートチャット（DM）であること
- インバウンドのアップデートに message_thread_id が含まれていること
- ボットのトピックが有効であること（getMe().has_topics_enabled）

モードの種類:

off: ストリーミングなし
partial: テキストの一部を頻繁に更新（デフォルト）
block: channels.telegram.draftChunk を使用したチャンク単位の更新

思考プロセスの表示: /reasoning stream コマンドを使用すると、生成中の思考プロセスをドラフトバブルに表示し、最終的な回答のみを確定メッセージとして送信します。

2. フォーマットと HTML フォールバック

送信メッセージは Telegram の parse_mode: "HTML" を使用します。

Markdown 風のテキストは Telegram セーフな HTML に変換されます。
モデルが生成した生の HTML はエスケープされ、解析エラーを防ぎます。
万が一 HTML 解析に失敗した場合は、自動的にプレーンテキストとして再試行します。
リンクプレビューを無効にするには、channels.telegram.linkPreview: false を設定してください。

3. ネイティブコマンドとカスタムコマンド

ボットのメニューボタン（/）に表示されるコマンドは、起動時に setMyCommands で登録されます。

カスタムコマンドの追加例:

{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

コマンド名は自動的に小文字化され、先頭の / は削除されます。
カスタムコマンドはメニュー表示用であり、実際の動作（ロジック）はプラグインやスキル側で実装する必要があります。

4. インラインボタン

インラインキーボードの表示範囲を制御できます。

設定例:

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

スコープ: off, dm, group, all, allowlist（デフォルト）

メッセージアクションの例:

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "オプションを選択してください:",
  buttons: [
    [
      { text: "はい", callback_data: "yes" },
      { text: "いいえ", callback_data: "no" },
    ],
    [{ text: "キャンセル", callback_data: "cancel" }],
  ],
}

5. メディア（オーディオ、ビデオ、ステッカー）

Telegram 特有のメディア形式をサポートしています。

オーディオ: 通常はファイルとして送信されますが、[[audio_as_voice]] タグを返信に含めるか、アクションで asVoice: true を指定するとボイスメッセージとして送信されます。
ビデオ: ビデオノート（丸い動画）を送信する場合は asVideoNote: true を使用します。
ステッカー:
- WEBP 形式の静止ステッカーをサポート（ vision API で内容を記述し、キャッシュします）。
- action: "sticker" で送信、action: "sticker-search" でキャッシュ内を検索可能です。

6. フォーラムトピックとスレッド

Telegram のフォーラム（トピック）機能をフルサポートしています。

各トピックは個別のセッションキー（:topic:<threadId>）を持ち、文脈が混ざりません。
一般（General）トピック（threadId=1）は、Telegram API の仕様に合わせて特殊な処理が行われます。
トピックの設定は、グループ全体の設定を継承しつつ、個別に上書き可能です。

7. 長期ポーリング（Long Polling） vs Webhook

デフォルトは長期ポーリングですが、Webhook モードも利用可能です。

channels.telegram.webhookUrl と channels.telegram.webhookSecret を設定してください。
デフォルトでは 0.0.0.0:8787 でリスナーが待機します。

トラブルシューティング

`setMyCommands failed` エラーが出る

このエラーは通常、ボットが api.telegram.org へのアウトバウンド DNS または HTTPS 通信をブロックされている場合に発生します。ネットワーク環境やプロキシの設定を確認してください。

フォーラムの一般トピックで返信が失敗する

Telegram は sendMessage API で message_thread_id=1（一般トピック）を明示的に指定するとエラーを返します。OpenClaw はこの仕様を考慮して自動的に ID を省略しますが、カスタム実装を行う際は注意が必要です。

ステッカーが処理されない

アニメーションステッカー（TGS）やビデオステッカー（WEBM）は現在スキップされます。静止画の WEBP ステッカーのみが処理対象です。

制限事項と CLI

テキスト制限: channels.telegram.textChunkLimit はデフォルトで 4000 文字です。
メディア制限: channels.telegram.mediaMaxMb（デフォルト 5MB）を超えるファイルは処理されません。
CLI 送信: 数値のチャット ID または @username を指定してメッセージを送信できます。

openclaw message send --channel telegram --target 123456789 --message "こんにちは"
openclaw message send --channel telegram --target @username --message "こんにちは"

設定の詳細やトラブルシューティングで困ったときは、AI Setup Assistant に相談してみてください。

次のステップ

Pairing: iOS アプリとの連携方法
/tools/reactions: リアクション機能の詳細設定

---
title: Telegram 連携のトラブルシューティングガイド
description: Telegram ボットが反応しない、メッセージが見えない、ネットワークが不安定といった一般的な問題の解決方法を解説します。
---

ボットをデプロイして設定も完了したはずなのに、いざ動かしてみると無反応だったり、特定のメッセージだけ無視されたりすることはありませんか？期待通りに動かない原因は、多くの場合、Telegram 側のプライバシー設定やネットワークの挙動に隠れています。

ここでは、開発中によく遭遇する問題とその解決策をまとめました。

## 必要なもの

作業を始める前に、以下の準備ができているか確認してください。

- Telegram ボットの `botToken`（BotFather から取得）
- `openclaw` CLI がインストールされている環境
- Node.js （バージョン 22 以上を使用している場合は注意が必要です）
- `api.telegram.org` へのネットワーク接続

## クイックスタート

まずは最短で動作確認を行うためのステップです。

1. **設定の確認**: `requireMention=false` に設定している場合、Telegram のプライバシーモードを無効にする必要があります。
2. **ステータスチェック**: 以下のコマンドを実行して、現在のチャンネルの状態を確認します。
   ```bash
   openclaw channels status

疎通確認: グループ内で /activation always を実行し、セッションが正しく開始されるかテストします。

トラブルシューティング

メンションのないグループメッセージに反応しない

requireMention=false に設定している場合、Telegram のプライバシーモードが「メッセージの完全な可視化」を許可している必要があります。
- BotFather で /setprivacy を実行し、Disable に設定してください。
- 設定変更後、ボットを一度グループから削除し、再度追加してください。
openclaw channels status を実行すると、設定上はメッセージを受け取るはずなのに受け取れていない場合に警告が表示されます。
openclaw channels status --probe を使用すると、特定のグループ ID に対して明示的なチェックが可能です（ワイルドカード "*" の場合はチェックできません）。
クイックテストとして /activation always を試してください。

グループメッセージが全く表示されない

channels.telegram.groups の設定が存在する場合、そのグループがリストに含まれているか、あるいは "*" が含まれているか確認してください。
ボットがそのグループのメンバーであることを確認してください。
ログを確認して、スキップされた理由を特定します：
Terminal window
```
 openclaw logs --follow
```

コマンドが一部、または全く機能しない

送信者の ID が承認されているか確認してください（ペアリング設定、または allowFrom の設定）。
グループポリシーが open であっても、コマンドの実行権限チェックは適用されます。
setMyCommands failed というエラーが出る場合は、通常 api.telegram.org への DNS 解決や HTTPS 接続に問題があります。

ポーリングまたはネットワークの不安定さ

Node 22 以降でカスタム fetch やプロキシを使用している場合、AbortSignal の型不一致により即座に処理が中断されることがあります。
一部のホストでは api.telegram.org が優先的に IPv6 で解決されます。IPv6 の外部接続が不安定な場合、Telegram API との通信が断続的に失敗する原因となります。
以下のコマンドで DNS の応答を確認してください：

dig +short api.telegram.org A
dig +short api.telegram.org AAAA

より詳細な情報は、Channel troubleshooting を参照してください。

Telegram config reference pointers

設定の詳細は以下のリファレンスを確認してください。

Configuration reference - Telegram

特に重要なフィールドは以下の通りです：

起動・認証: enabled, botToken, tokenFile, accounts.*
アクセス制御: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*
コマンド・メニュー: commands.native, customCommands
スレッド・返信: replyToMode
ストリーミング: streamMode, draftChunk, blockStreaming
フォーマット・配信: textChunkLimit, chunkMode, linkPreview, responsePrefix
メディア・ネットワーク: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
Webhook: webhookUrl, webhookSecret, webhookPath
アクション・機能: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
リアクション: reactionNotifications, reactionLevel
履歴・書き込み: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

解決しない場合は、AI Setup Assistant に相談してください。

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。

Telegram (Bot API) のセットアップガイド

必要なもの

クイックスタート

1. BotFather でトークンを作成する

2. トークンと DM ポリシーを設定する

3. Gateway を起動して DM を承認する

4. ボットをグループに追加する

トラブルシューティング

次のステップ

メンションによる動作設定

トラブルシューティング

Telegram ユーザー ID を見つける

グループ ID を取得する

次のステップ

必要なもの

クイックスタート

Runtime behavior の詳細

プロセスとルーティング

セッションの隔離

Long Polling と並行処理

サポートされない機能

トラブルシューティング

sendReadReceipts を設定しても既読にならない

特定のスレッドに返信が届かない

次のステップ

必要なもの

クイックスタート

主要機能リファレンス

1. Telegram DM でのドラフトストリーミング

2. フォーマットと HTML フォールバック

3. ネイティブコマンドとカスタムコマンド

4. インラインボタン

5. メディア（オーディオ、ビデオ、ステッカー）

6. フォーラムトピックとスレッド

7. 長期ポーリング（Long Polling） vs Webhook

トラブルシューティング

setMyCommands failed エラーが出る

フォーラムの一般トピックで返信が失敗する

ステッカーが処理されない

制限事項と CLI

次のステップ

トラブルシューティング

メンションのないグループメッセージに反応しない

グループメッセージが全く表示されない

コマンドが一部、または全く機能しない

ポーリングまたはネットワークの不安定さ

Telegram config reference pointers

次のステップ

まだ解決しませんか？

`sendReadReceipts` を設定しても既読にならない

`setMyCommands failed` エラーが出る