OpenClawのTelegramセットアップ

Telegramボットは最も手早く立ち上げられるチャネルです。セットアップ全体が、BotFatherから得る1つのトークンと、それを保存する1つのコマンドで済むからです。ここでは、クイックセットアップの手順、トークンの優先順位のルール、設定ファイルではなくTelegram側にある設定、そしてロングポーリングとwebhookのどちらをトランスポートに選ぶかを順に説明します。

クイックセットアップ

• BotFatherの2つの手順は、どちらもOpenClawに貼り付けるトークンの取得で終わります。1つはチャットでの手順で、BotFatherアカウントと会話し、ハンドルが正確に一致していることを確認し、新規ボット作成のコマンドを実行してトークンを保存します。もう1つはBotFatherのウェブアプリでの手順で、どのTelegramクライアントでも動作し、UI上でボットを作成してトークンをコピーできます。
• 最も手早く設定する方法は、Telegramチャネルとトークンを指定してchannels addコマンドを実行することで、トークンが設定に自動で書き込まれます。代わりに手で編集する場合は、チャネルを有効化し、ボットトークン、pairingのDMポリシー、メンションを必須とするワイルドカードのグループエントリーを含むTelegramブロックを書きます。ボットトークンの環境変数はデフォルトアカウント専用のフォールバックで、名前付きアカウントではトークンキーまたはトークンファイルを使う必要があります。
• デフォルトのホットリロードにより、実行中のgatewayが新しいチャネル設定を適用し、channels statusのプローブでTelegramの準備ができたかを確認できます。gatewayがオフラインなら、管理サービスとして、またはターミナルで起動します。サービスの環境を変更した場合は、読み込むために再起動が必要です。
• ボットに何かメッセージを送ると、ペアリングリクエストが作成されます。これはpairing listコマンドで表示され、approveコマンドで承認でき、コードは1時間で期限切れになります。次にボットをグループに追加するには、許可リスト用のあなたの数値のユーザーIDと、groupsマップの下のキーとなるグループのチャットIDが必要です。チャットIDはログ、転送されたメッセージのIDを教えてくれるボット、またはBot APIのupdatesから読み取り、グループが許可されたらwhoamiコマンドで確認します。負の値のスーパーグループIDはgroupsの下に置き、グループの送信者リストには決して入れません。

Telegramではopenclaw channels login telegramは使いません。

トークンとTelegram側の設定

トークンの解決はアカウントを考慮して行われます。トークンファイルはボットトークンのキーより優先され、ボットトークンのキーは環境変数より優先されます。設定は常に環境変数に勝ち、環境変数が解決されるのはデフォルトアカウントの場合だけです。起動に成功すると、OpenClawはボットのアイデンティティを最大24時間キャッシュするため、再起動時に余分なgetMe呼び出しを省けます。トークンを変更または削除すると、このキャッシュはクリアされます。Telegram側では、ボットはデフォルトでプライバシーモードになっており、受け取れるグループメッセージが制限されます。すべてのグループメッセージを見るには、プライバシー設定のコマンドでプライバシーモードを無効にするか、ボットをグループの管理者にします。プライバシーモードを切り替えたら、Telegramに変更を反映させるため、各グループでボットを削除して再追加してください。管理者ステータスはグループの設定で管理し、管理者のボットはすべてのグループメッセージを受け取るため、グループで常に応答させる運用に向いています。BotFatherで役立つ切り替え設定は、グループへの追加を許可または拒否するグループ参加の設定と、グループでの可視性を決めるプライバシー設定で、どちらもBotFatherのウェブアプリでも利用できます。

ロングポーリングかwebhookか

• デフォルトはロングポーリングです。webhookモードにはwebhookのURLとwebhookのシークレットが必要で、任意でパス（デフォルトはtelegram-webhookのルート）、ホスト（デフォルトはループバック）、ポート（デフォルトは8787）を指定でき、IPを直接使う構成やドメインのない構成では、自己署名PEM用の証明書パスも指定できます。リスナーはヘルスチェック用にヘルスのルートを予約しているため、webhookのパスには別のルートを使う必要があります。そのルートを使っている既存の構成は移動が必要で、URLとリバースプロキシのマッピングを更新し、ステータスプローブでリスナーの変更を確認します。
• ロングポーリングモードでは、OpenClawはアップデートが永続的な受信キューにコミットされた後に再開位置を保存するため、ハンドラーが失敗してもそのキューから再試行できます。ローカルのリスナーはデフォルトでポート8787のループバックにバインドされ、外部から受信するには、その前段にリバースプロキシを置くか、意図的にワイルドカードのホストを設定します。
• webhookモードでは、リクエストのガード、Telegramのシークレットトークン、JSONボディを検証し、空の200を返す前にアップデートを永続キューにコミットします。永続的な受け入れに成功したことは配信受理ヘッダーで示され、このヘッダーはヘルス、ルーティング、認証、検証、ストレージエラーの各レスポンスには付きません。そのため、リバースプロキシはタイミングから受理を推測するのではなく、このヘッダーを必須にできます。永続的な書き込みの後、アップデートはチャットごと、トピックごとのレーンを持つコアの受信ドレインを通じて取得・処理され、エージェントのターンが遅くても、Telegramへの配信確認応答が引き止められることはありません。

このセットアップはTelegramでのOpenClawの記事の一部で、誰がボットにアクセスできるかについて次に決めるべきことはOpenClawのTelegramアクセス制御の記事で解説しています。

セットアップでつまずきやすい点

Telegramのセットアップの失敗は、ほぼすべてが次の3つのどれかです。デフォルトアカウントにしか使えない環境変数で名前付きアカウントのトークンを渡している、グループIDをgroupsマップではなく送信者リストに入れている、あるいはメンション必須をオフにしたままプライバシーモードをオンにしている。これらの症状はOpenClawのTelegramトラブルシューティングの記事で順に取り上げています。初めてのチャネルなら、5分で最初のチャネルを接続するガイドをご覧ください。

Dialiでは

Dialiでは、Telegramチャネルはダッシュボードから接続し、ランタイム設定はそこから生成されてリリースのたびに置き換えられます。そのため、あなたの側に残るのは、この記事の冒頭にあるBotFatherの手順だけです。DialiでのこのチャネルについてはDialiでのTelegramのページを、接続されたすべてのチャネルに共通する境界についてはDialiのセキュリティのページをご覧ください。

• BotFatherからトークンを1つ。書き込みはCLIが行います。
• ペアリングコードは1時間で期限切れ。グループIDはgroupsの下へ。
• デフォルトはロングポーリング。webhookにはシークレットと空いているルートが必要です。