OpenClaw Telegram チャンネル
メッセージング
簡単
grammY Bot API フレームワークを使用して OpenClaw を Telegram に接続します。@BotFather で Telegram ボットを作成し、トークンを取得すれば、数分で AI アシスタントが Telegram で稼働します。デフォルトではロングポーリングを使用し、オプションで Webhook モードも利用可能です。最も簡単にセットアップできるチャンネルの一つで、インラインボタン、ステッカー、リアクション、グループチャットなど豊富な機能をサポートします。
基本情報
難易度簡単
カテゴリメッセージング
対応機能数6 / 6
Telegram 対応機能
テキストメッセージ
対応
メディア・ファイル
対応
リアクション
対応
スレッド
対応
音声メッセージ
対応
グループチャット
対応
Telegram 前提条件
- Telegram アカウント
- @BotFather からの Bot Token（@BotFather に /newbot を送信）
- OpenClaw Gateway が稼働・設定済み
- サーバーに Node.js 18+ がインストール済み
Telegram クイックセットアップ
1
@BotFather でボットを作成
Telegram を開き、@BotFather を検索して /newbot を送信します。プロンプトに従ってボットに名前を付け、API トークンを取得します。このトークンを大切に保管してください——設定時に必要です。
2
Telegram チャンネル設定を追加
~/.openclaw/openclaw.json に Telegram チャンネルの設定を追加します。@BotFather から取得したボットトークンを botToken フィールドに貼り付けます。dmPolicy（pairing、allowlist、または open）を設定して、AI アシスタントと会話できるユーザーを制御します。
3
Gateway を起動してテスト
Gateway プロセスを起動します。Telegram でボットを検索してメッセージを送信します。デフォルトの pairing ポリシーを使用している場合、'openclaw pairing approve telegram <code>' で送信者を承認します。OpenClaw が AI アシスタントを通じて応答するはずです。
Telegram 設定例
config.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
"dmPolicy": "pairing"
}
}
}Telegram 詳細ドキュメント
アーキテクチャ概要
OpenClaw は grammY フレームワークを通じて Telegram に接続します——モダンで TypeScript ファーストな Telegram Bot API ライブラリです。ボットはデフォルトでロングポーリングを使用し、Telegram サーバーに定期的に新しい更新を問い合わせます。追加設定なしですぐに動作します。
また、本番環境のデプロイには Webhook モードに切り替えることもできます。Webhook モードでは、Telegram がサーバーエンドポイントに直接更新をプッシュするため、より効率的で低レイテンシーです。
ロングポーリングは NAT やファイアウォールの背後でも設定不要で動作します。Webhook モードにはパブリックにアクセス可能な HTTPS エンドポイントが必要です。
ボットトークンは TELEGRAM_BOT_TOKEN 環境変数、または設定ファイルの channels.telegram.botToken フィールドに保存できます。
@BotFather でボットを作成する
BotFather は Telegram 公式のボット作成・管理ツールです。手順は以下の通りです：
1. Telegram を開き、@BotFather を検索
2. /newbot を送信して作成プロセスを開始
3. ボットの表示名を選択（例：「My AI Assistant」）
4. 'bot' で終わるユーザー名を選択（例："my_ai_assistant_bot"）
5. BotFather が API トークンを返します——安全に保管してください
作成後、BotFather コマンドでさらにカスタマイズできます：
• /setdescription — プロフィールに表示される説明を設定
• /setabouttext — 「概要」セクションのテキストを設定
• /setuserpic — プロフィール画像をアップロード
• /setprivacy — グループメッセージのプライバシーモードを切り替え
ボットトークンは秘密にしてください。トークンを持っている人は誰でもボットを制御できます。漏洩した場合は、BotFather で /revoke を使用して新しいトークンを生成してください。
DM ポリシー
DM（ダイレクトメッセージ）ポリシーは、AI アシスタントとプライベートチャットできるユーザーを制御します。OpenClaw は3つのポリシーをサポートします：
• pairing（デフォルト）— 新しいユーザーはペアリングフローを通過する必要があります。メッセージを送信するとペアリングコード（有効期限1時間）を受け取り、CLI で承認または拒否します。承認後は自由にチャットできます。
• allowlist — allowFrom リストに明示的に記載された数値ユーザー ID のみがボットにメッセージを送れます。それ以外はサイレントに無視されます。
• open — ボットにメッセージを送った誰もが応答を受けます。本番環境では注意して使用してください。
openclaw.json
{
"channels": {
"telegram": {
"dmPolicy": "pairing",
"allowFrom": [123456789, 987654321]
}
}
}ユーザーの Telegram 数値 ID を確認するには、@userinfobot を使用するか、ユーザーがメッセージを送信した時の Gateway ログを確認できます。
グループチャット管理
OpenClaw は Telegram グループチャットをサポートし、2つの独立した仕組みで柔軟なアクセス制御を提供します：
1. グループ許可リスト — 許可するグループを決定します。すべてのグループか、channels.telegram.groups にリストされたグループのみか。
2. グループポリシー — 許可されたグループ内の送信者権限を制御：
• open — グループメンバー誰でもボットをトリガーできる
• allowlist — 承認された送信者のみが対話可能
• disabled — グループメッセージを完全に無視
デフォルトでは、ボットはグループで @メンション が必要です。この動作を変更できます：
• /activation always コマンド（セッション限定）ですべてのメッセージに応答
• 設定で requireMention: false を設定して永続的にすべてに応答
openclaw.json
{
"channels": {
"telegram": {
"groupPolicy": "open",
"requireMention": false,
"groups": ["-1001234567890"]
}
}
}フォーラムスタイルのグループ（トピック）では、OpenClaw はスレッド ID を使用して各トピックを分離し、トピックごとの設定オーバーライドを適用できます。
ボットが管理者でなくてもグループ内のすべてのメッセージを見るには、BotFather で /setprivacy を使ってプライバシーモードを無効にし、ボットをグループから削除して再追加する必要があります。
メッセージフォーマットとストリーミング
OpenClaw はメッセージのフォーマットと配信に複数のオプションを提供します：
フォーマット：送信テキストは Telegram の HTML パーサーを使用し、Markdown スタイルから自動変換されます。HTML パースに失敗した場合、プレーンテキストとして再試行されます。
ストリーミング：ドラフトバブルは DM でスレッドトピックが有効な場合、部分的な返信ストリーミングをサポートします。2つのモードが利用可能：
• partial（デフォルト）— AI が生成する際に単一メッセージを段階的に更新
• block — 完全なブロックとしてチャンク更新を送信
テキストはデフォルトで 4,000 文字でチャンクされます（Telegram の制限）。chunkMode: "newline" を有効にすると、ハードスプリットの代わりに段落境界で分割されます。
openclaw.json
{
"channels": {
"telegram": {
"streamMode": "partial",
"chunkMode": "newline"
}
}
}インラインボタン
OpenClaw は Telegram のインタラクティブなインラインキーボードボタンをサポートします。有効にすると、AI はメッセージの下にボタンを表示してユーザーがクリックできます。ボタンをクリックすると、コールバックデータがフォーマットされたメッセージとしてエージェントに返されます。
利用可能なモード：
• off — ボタン無効（デフォルト）
• dm — プライベートチャットのみで有効
• group — グループチャットのみで有効
• all — すべてで有効
• allowlist — 送信者認証で制限
openclaw.json
{
"channels": {
"telegram": {
"capabilities": {
"inlineButtons": "all"
}
}
}
}ステッカーとメディア
OpenClaw は Telegram のステッカーとメディアファイルを処理します：
ステッカー：静的ステッカーはダウンロードされ、ビジョン分析で処理されます。生成された説明はキャッシュされ、API 呼び出しの繰り返しを防ぎます。アニメーションやビデオステッカーは処理をスキップします。エージェントは保存されたファイル ID を使ってステッカーを送信でき、説明、絵文字、セット名でキャッシュされたステッカーを検索できます。
メディア：メディアのアップロード/ダウンロードはデフォルトで 5 MB が上限です。ボットは画像、ドキュメント、オーディオファイル、ビデオの送受信をサポートします。
エージェント設定で sticker アクションを有効にすると、ファイル ID やキャッシュ検索でステッカーを送信できるようになります。
リアクション
OpenClaw は Telegram のリアクションシステムをサポートし、絵文字リアクションの受信と送信の両方に対応します：
受信したリアクションはシステムイベントを生成し、エージェントコンテキストに追加されます。通知をトリガーするリアクションを設定できます：
• off — リアクション通知なし
• own — ボットメッセージへのリアクションのみ
• all — チャット内のすべてのリアクション
ボットもリアクションを送信できます。リアクション機能レベルを設定：
• off — リアクションなし
• ack — 処理中の確認リアクション（デフォルト）
• minimal — 基本的なリアクション
• extensive — 完全な絵文字範囲
openclaw.json
{
"channels": {
"telegram": {
"reactionNotifications": "own",
"reactionLevel": "ack"
}
}
}コマンドとツール
ネイティブボットコマンド（/status、/reset など）は Telegram のボットコマンドメニューに自動登録され、ユーザーが簡単に見つけられます。カスタムコマンドは設定で追加できますが、メニューエントリとしてのみ機能します。
エージェントはツールアクションもサポートします：
• 特定のチャットにメッセージを送信
• メッセージに絵文字でリアクション
• メッセージの削除
• [[reply_to:<id>]] タグを使って特定のメッセージに返信
エージェントの返信で [[reply_to_current]] を使用すると、ユーザーの現在のメッセージに直接返信できます。
返信に [[audio_as_voice]] を含めるか、ツール呼び出しで asVoice: true を設定すると、ボイスノート形式を強制できます。
Webhook モード
本番環境のデプロイでは、ロングポーリングよりも Webhook モードが推奨されます。Webhook モードでは、Telegram がサーバーに直接更新をプッシュし、レイテンシーとリソース使用量を削減します。
Webhook を有効にするには、設定で webhookUrl と webhookSecret を設定します。ローカルエンドポイントはデフォルトで 0.0.0.0:8787 にバインドされます。
openclaw.json
{
"channels": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram/webhook",
"webhookSecret": "your-random-secret-string"
}
}
}ポーリングから Webhook モードに切り替えると、Gateway は起動時に自動的に Telegram に Webhook URL を登録します。
Webhook モードにはパブリックにアクセス可能な HTTPS エンドポイントが必要です。サーバーに有効な SSL 証明書があることを確認してください。
Telegram 設定リファレンス
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Telegram チャンネルを有効または無効にする |
| botToken | string | "" | @BotFather からの Telegram Bot API トークン。TELEGRAM_BOT_TOKEN 環境変数も使用可能 |
| dmPolicy | string | "pairing" | ボットに DM できるユーザーを制御。オプション：pairing、allowlist、open |
| allowFrom | number[] | [] | ボットにメッセージを送れる Telegram 数値ユーザー ID（dmPolicy が allowlist の場合） |
| groupPolicy | string | "disabled" | グループチャットポリシー。オプション：disabled、open、allowlist |
| groups | string[] | [] | 許可されたグループチャット ID のリスト。空で groupPolicy が disabled でない場合、すべてのグループを許可 |
| requireMention | boolean | true | グループでボットが @メンション を必要とするかどうか |
| streamMode | string | "partial" | AI 応答のストリーミングモード。オプション：partial（段階的更新）、block（チャンク送信） |
| chunkMode | string | "split" | 長い応答の処理方法。オプション：split（ハード文字制限）、newline（段落分割） |
| webhookUrl | string | "" | Webhook モードの HTTPS URL。設定するとポーリングから Webhook に切り替え |
| webhookSecret | string | "" | Webhook 検証用のシークレットトークン |
| reactionNotifications | string | "off" | 通知をトリガーするリアクション。オプション：off、own、all |
| reactionLevel | string | "ack" | ボットのリアクション機能。オプション：off、ack、minimal、extensive |
| capabilities.inlineButtons | string | "off" | インラインボタンモード。オプション：off、dm、group、all、allowlist |
| configWrites | boolean | true | スーパーグループアップグレード時にチャット ID を自動移行。false で無効化 |
enabled
Type: booleanDefault: true
Telegram チャンネルを有効または無効にする
botToken
Type: stringDefault: ""
@BotFather からの Telegram Bot API トークン。TELEGRAM_BOT_TOKEN 環境変数も使用可能
dmPolicy
Type: stringDefault: "pairing"
ボットに DM できるユーザーを制御。オプション：pairing、allowlist、open
allowFrom
Type: number[]Default: []
ボットにメッセージを送れる Telegram 数値ユーザー ID（dmPolicy が allowlist の場合）
groupPolicy
Type: stringDefault: "disabled"
グループチャットポリシー。オプション：disabled、open、allowlist
groups
Type: string[]Default: []
許可されたグループチャット ID のリスト。空で groupPolicy が disabled でない場合、すべてのグループを許可
requireMention
Type: booleanDefault: true
グループでボットが @メンション を必要とするかどうか
streamMode
Type: stringDefault: "partial"
AI 応答のストリーミングモード。オプション：partial（段階的更新）、block（チャンク送信）
chunkMode
Type: stringDefault: "split"
長い応答の処理方法。オプション：split（ハード文字制限）、newline（段落分割）
webhookUrl
Type: stringDefault: ""
Webhook モードの HTTPS URL。設定するとポーリングから Webhook に切り替え
webhookSecret
Type: stringDefault: ""
Webhook 検証用のシークレットトークン
reactionNotifications
Type: stringDefault: "off"
通知をトリガーするリアクション。オプション：off、own、all
reactionLevel
Type: stringDefault: "ack"
ボットのリアクション機能。オプション：off、ack、minimal、extensive
capabilities.inlineButtons
Type: stringDefault: "off"
インラインボタンモード。オプション：off、dm、group、all、allowlist
configWrites
Type: booleanDefault: true
スーパーグループアップグレード時にチャット ID を自動移行。false で無効化
Telegram よくある質問
Telegram トラブルシューティング
グループでメンションなしにボットが応答しない
Telegram ボットはデフォルトでプライバシーモードが有効です。有効な場合、ボットは @メンション されたメッセージまたはスラッシュコマンドで始まるメッセージのみを受信します。
BotFather でプライバシーモードを無効にします：@BotFather に /setprivacy を送信し、ボットを選択して 'Disable' を選びます。その後、ボットをグループから削除して再追加します。また、OpenClaw 設定で requireMention: false を設定してください（すべてのメッセージに応答させたい場合）。
ボットがメッセージに応答しない
ボットトークンが正しくない、Gateway が実行されていない、またはネットワーク接続の問題がある可能性があります。
Telegram Bot API で直接テストしてトークンが正しいか確認します：curl https://api.telegram.org/bot<token>/getMe。Gateway ログで接続エラーを確認します。IPv6 ルーティングの問題でサイレントに失敗する場合は、api.telegram.org の IPv4 解決を強制するか、dig コマンドで DNS が動作するアドレスを返すか確認します。
Webhook が更新を受信しない
Webhook URL がパブリックにアクセスできない、SSL 証明書が無効、または Webhook が正しく登録されていない。
Webhook URL がインターネットからアクセス可能であることを確認します（curl でテスト）。SSL 証明書が有効で自己署名でないことを確認します。Webhook ステータスを確認：curl https://api.telegram.org/bot<token>/getWebhookInfo。Gateway を再起動して Webhook を再登録します。
メッセージが切り詰められるまたは正しく分割されない
Telegram には 4,096 文字のメッセージ制限があります。長い AI 応答は自動的にチャンクされます。
chunkMode を 'newline' に設定して、ハード文字制限の代わりに段落境界で分割します。設定で最大テキストチャンクサイズを調整することもできます。