Telegram は OpenClaw がネイティブにサポートするチャンネルの一つで、基盤には grammY フレームワークを使用しています。Telegram のグループとチャンネル機能は非常に強力で、ネイティブの Bot API、きめ細かな権限制御、豊富なメッセージフォーマットを備えています。本記事では、OpenClaw の Telegram グループシーンにおける高度な設定オプションを詳しく紹介します。
Telegram グループの種類
Telegram にはいくつかの異なるグループタイプがあり、それぞれの違いを理解すると Bot を適切に設定できます。
通常グループ：最大 200 人の小規模グループです。Bot はすべてのメッセージを受信できます（Privacy Mode がオフの場合）。または、コマンドと @メンションのメッセージのみ受信します。
スーパーグループ（Supergroup）：最大 200,000 人の大規模グループで、より多くの管理機能をサポートします。ほとんどのコミュニティが使用するグループタイプです。
チャンネル（Channel）：一方向のブロードキャストチャンネルです。Bot は管理者としてメッセージを投稿できますが、通常はインタラクティブな AI 対話には使用されません。
Privacy Mode とメッセージ受信
Telegram Bot はデフォルトで Privacy Mode が有効になっており、グループ内では以下のメッセージのみ受信できます。/ で始まるコマンド、直接 @メンションした Bot のメッセージ、Bot が送信したメッセージへの返信、およびサービスメッセージ（メンバーの参加/退出など）です。
Bot がグループ内のすべてのメッセージを受信できるようにしたい場合は、BotFather で Privacy Mode を無効にする必要があります。/setprivacy コマンドを送信して Bot を選択し、Disabled に設定します。変更後、Bot をグループから一度削除して再追加しないと反映されないことに注意してください。
openclaw.json でグループの動作を設定します。
{
"channels": {
"telegram": {
"enabled": true,
"token": "your-bot-token",
"groups": {
"privacyMode": false,
"triggerMode": "command_and_mention",
"commands": ["/ask", "/chat", "/help"]
}
}
}
}
コマンドシステム
Telegram のコマンドシステムは Bot とのインタラクションの標準的な方法です。OpenClaw では複数のコマンドを定義でき、各コマンドに異なる動作をバインドできます。
{
"channels": {
"telegram": {
"groups": {
"commands": {
"/ask": {
"description": "AIに質問する",
"behavior": "single_response"
},
"/chat": {
"description": "マルチターン会話を開始",
"behavior": "conversation"
},
"/reset": {
"description": "会話コンテキストをリセット",
"behavior": "reset_context"
}
}
}
}
}
}
single_response モードでは Bot は一度だけ返信し、conversation モードでは Bot はそのユーザーの後続メッセージを継続的に追跡します（タイムアウトまたは手動リセットまで）。BotFather で /setcommands を使用してこれらのコマンドを登録することを推奨します。そうすると、ユーザーが / を入力した際にコマンドリストと説明が表示されます。
グループ権限制御
OpenClaw は Telegram グループの多層的な権限制御を提供しています。
{
"channels": {
"telegram": {
"groups": {
"allowedGroups": [-1001234567890, -1009876543210],
"userAllowlist": [123456789, 987654321],
"adminOnly": false,
"requirePairing": false
}
}
}
}
グループホワイトリスト（allowedGroups）：Telegram グループの chat_id を使用して、Bot が特定のグループでのみ動作するように制限します。Chat ID は負の数で、Bot がグループメッセージを受信することで取得できます。
ユーザーホワイトリスト（userAllowlist）：特定のユーザー ID のみがグループ内で AI をトリガーできるように制限します。他のユーザーのメッセージは無視されます。
管理者のみ（adminOnly）：true に設定すると、グループの管理者のみが AI 機能を使用できます。
DM ペアリング（requirePairing）：ユーザーが先に Bot と DM でペアリング検証を完了することを要求します。
これらのオプションは組み合わせて使用できます。例えば、特定のグループ内のペアリング済みユーザーのみが Bot を使用できるように設定できます。
インラインモード
Telegram Bot はインラインモード（Inline Mode）をサポートしており、ユーザーは任意のチャットで @botname 質問 という方法で AI を呼び出せます。Bot をグループに追加する必要はありません。BotFather でインラインモードを有効にした後、OpenClaw で設定します。
{
"channels": {
"telegram": {
"inlineMode": {
"enabled": true,
"cacheTime": 30
}
}
}
}
インラインモードの返信はインラインクエリ結果として表示され、ユーザーが選択すると結果が現在の会話に送信されます。
マルチボット管理
大規模コミュニティでは、それぞれ異なる役割を担う複数の AI Bot をデプロイする必要がある場合があります。OpenClaw は同一インスタンスで複数の Telegram Bot の実行をサポートしています。
{
"channels": {
"telegram": [
{
"name": "general-assistant",
"token": "bot-token-1",
"model": "gpt-4"
},
{
"name": "code-helper",
"token": "bot-token-2",
"model": "claude-sonnet"
}
]
}
}
各 Bot は異なる token とモデル設定を使用し、同じグループ内で共存できます。ユーザーは異なる Bot を @メンションすることで、異なる AI アシスタントを呼び出します。
メッセージフォーマットと Markdown
Telegram は MarkdownV2 と HTML の 2 つのメッセージフォーマットをサポートしています。OpenClaw はデフォルトで MarkdownV2 を使用して AI の返信をフォーマットし、太字、斜体、コードブロック、リンクなどをサポートします。AI の返信に複雑なフォーマットが含まれる場合、OpenClaw は自動的にエスケープ文字を処理して Telegram が正しくレンダリングできるようにします。
設定で HTML フォーマットやプレーンテキストに切り替えることもできます。
{
"channels": {
"telegram": {
"parseMode": "MarkdownV2"
}
}
}
レート制限とキュー
Telegram Bot API にはレート制限があります。1 秒あたり最大 30 件のメッセージ、同一グループでは 1 分あたり最大 20 件のメッセージです。OpenClaw にはこれらの制限を処理するメッセージキュー機構が組み込まれています。トラフィックの多いグループでは、返信にわずかな遅延が生じることがありますが、これは正常な動作です。
トラブルシューティング
Bot がグループ内で応答しない場合は、以下の手順でトラブルシューティングを行います。Bot がグループに追加されていることを確認します。Privacy Mode の設定がトリガーモードと一致していることを確認します。グループ ID がホワイトリストに含まれていることを確認します（ホワイトリストを設定している場合）。OpenClaw のログにエラー情報がないか確認します。openclaw channels status コマンドを使用すると、すべてのチャンネルの接続状態を素早く確認できます。