OpenClaw Telegram 連携完全ガイド

ペアリングコードは1時間後に期限切れになります。

allowlist モード

{
  channels: {
    telegram: {
      dmPolicy: "allowlist",
      allowFrom: [123456789, "@trusted_user"]
    }
  }
}

open モード

{
  channels: {
    telegram: {
      dmPolicy: "open"
    }
  }
}

グループチャットサポート

グループアクセスを有効化

groups オブジェクトにグループ ID を追加します。すべてのグループを許可するには "*" を使用します：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {},           // デフォルト設定の特定グループ
        "-1009876543210": {             // オーバーライド設定の特定グループ
          groupPolicy: "open",
          requireMention: false,
          systemPrompt: "You are a helpful coding assistant."
        }
      }
    }
  }
}

またはすべてのグループを許可：

{
  channels: {
    telegram: {
      groups: "*"
    }
  }
}

グループポリシー

グループ内でボットと対話できるユーザーを制御します：

| 設定 | 説明 | |---------|-------------| | groupPolicy: "open" | グループメンバー全員がボットにメッセージ可能 | | groupPolicy: "allowlist" | groupAllowFrom に含まれる送信者のみ対話可能 | | groupPolicy: "disabled" | ボットはグループメッセージをすべて無視 |

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: [123456789, "@allowed_user"]
    }
  }
}

メンション要件

デフォルトでは、ボットはグループ内で @メンション を必要とします。グループごとに変更できます：

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          requireMention: false   // ボットはすべてのメッセージに応答
        }
      }
    }
  }
}

またはグループチャットでセッション限定コマンド /activation always を使用します。

グループごとのオーバーライド

各グループエントリは以下のフィールドをサポートします：

| フィールド | 説明 | |-------|-------------| | groupPolicy | グローバルグループポリシーをオーバーライド | | requireMention | @メンションが必要かどうか | | skills | このグループで利用可能なスキル | | allowFrom | このグループの送信者許可リスト | | systemPrompt | このグループのカスタムシステムプロンプト | | enabled | この特定のグループを有効/無効化 |

メッセージ形式とチャンキング

HTML パースモード

OpenClaw は Telegram の HTML パースモード（Markdown ではない）を使用してメッセージを送信します。LLM からの Markdown は自動的に HTML セーフタグに変換されます。Telegram が HTML を拒否した場合、プレーンテキストとして再送信されます。

テキストチャンキング

長いメッセージは複数の Telegram メッセージに分割されます：

{
  channels: {
    telegram: {
      textChunkLimit: 4000,    // メッセージあたりの最大文字数（デフォルト：4000）
      chunkMode: "newline"     // "length"（デフォルト）または "newline"
    }
  }
}

• "length" -- 文字数制限で分割
• "newline" -- 文字数制限を適用する前に段落の境界で分割

メディア処理

メディアサイズ制限

{
  channels: {
    telegram: {
      mediaMaxMb: 5    // 最大ファイルサイズ（MB）（デフォルト：5）
    }
  }
}

スタンプ

• 静止スタンプ （WEBP）はビジョンで処理され、LLM に説明が渡されます
• アニメーション/ビデオスタンプ はスキップされます
• スタンプの説明は ~/.openclaw/telegram/sticker-cache.json にキャッシュされ、冗長なビジョン呼び出しを回避します

ボットがスタンプを 送信 できるようにするには：

{
  channels: {
    telegram: {
      actions: {
        sticker: true    // デフォルト：false
      }
    }
  }
}

履歴とコンテキスト

{
  channels: {
    telegram: {
      historyLimit: 50,        // グループコンテキスト（デフォルト：50）
      dmHistoryLimit: 100      // DM コンテキスト
    }
  }
}

ユーザーごとの DM オーバーライド：

{
  channels: {
    telegram: {
      dms: {
        "123456789": {
          historyLimit: 200
        }
      }
    }
  }
}

0 に設定すると履歴が無効になります。

ストリーミング

OpenClaw はプライベートチャット（フォーラムトピック有効時）でドラフトベースのストリーミングをサポートしています：

| 設定 | 説明 | |---------|-------------| | streamMode: "off" | ストリーミング無効（デフォルト） | | streamMode: "partial" | ドラフトメッセージへの連続更新 | | streamMode: "block" | ドラフトメッセージへのチャンク更新 |

block モードの設定：

{
  channels: {
    telegram: {
      streamMode: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"
      }
    }
  }
}

Webhook モード（本番環境）

本番デプロイでは、ロングポーリングの代わりに Webhook を使用します：

{
  channels: {
    telegram: {
      webhookUrl: "https://your-domain.com/telegram-webhook",
      webhookSecret: "your-random-secret-string",
      webhookPath: "/telegram-webhook"    // ローカルパス、デフォルト：/telegram-webhook
    }
  }
}

Webhook リスナーは 0.0.0.0:8787 にバインドされます。 webhookUrl が設定されると、OpenClaw は自動的にポーリングから Webhook モードに切り替わります。

コマンド

ネイティブコマンド

OpenClaw は起動時にこれらのコマンドを Telegram のボットメニューに登録します：

| コマンド | 説明 | |---------|-------------| | /start | ウェルカムメッセージ | | /status | ボットのステータスを表示 | | /reset | 会話をリセット | | /model | モデルの表示/切り替え |

カスタムコマンド

設定でメニューエントリを追加します（メニュー表示のみ -- 別途ハンドラーがない限り実行されません）：

{
  channels: {
    telegram: {
      customCommands: [
        { command: "weather", description: "Get weather forecast" },
        { command: "translate", description: "Translate text" }
      ]
    }
  }
}

コマンド名は小文字の a-z0-9_ 、1〜32文字である必要があります。先頭の / は自動的に除去されます。ネイティブコマンドをオーバーライドすることはできません。

インラインボタン

インラインボタンの利用可能範囲を制御します：

| 設定 | スコープ | |---------|-------| | capabilities.inlineButtons: "off" | 無効 | | capabilities.inlineButtons: "dm" | DM のみ | | capabilities.inlineButtons: "group" | グループのみ | | capabilities.inlineButtons: "all" | DM とグループの両方 | | capabilities.inlineButtons: "allowlist" | 両方 + 送信者フィルタリング（デフォルト） |

ネットワークとプロキシ

{
  channels: {
    telegram: {
      timeoutSeconds: 500,        // Bot API リクエストタイムアウト（デフォルト：500）
      network: {
        autoSelectFamily: false   // Happy Eyeballs を無効化（Node 22 でデフォルト有効）
      },
      proxy: "socks5://127.0.0.1:1080"   // Bot API 用の SOCKS/HTTP プロキシ
    }
  }
}

トラブルシューティング

ボットが応答しない

1. トークンが正しいか確認：

curl "https://api.telegram.org/bot/getMe"

2. OpenClaw のログを確認：

openclaw logs --follow

グループでメッセージが届かない

• プライバシーモードが無効化されている（ /setprivacy → Disable）か、ボットが管理者である必要があります
• /activation always （セッション限定）でテストし、設定の requireMention: false で永続化します

IPv6 ルーティングの失敗

IPv6 ルーティングが失敗すると、ボットが無応答になる場合があります。 api.telegram.org の DNS を確認します：

dig api.telegram.org AAAA

IPv6 送信を有効化するか、IPv4 を強制して修正します：

# /etc/hosts に追加
149.154.167.220  api.telegram.org

またはネットワーク設定を使用：

{
  channels: {
    telegram: {
      network: {
        autoSelectFamily: false
      }
    }
  }
}

ロングポーリングの中断（Node 22以降）

Node 22 は AbortSignal インスタンスの処理がより厳格です。OpenClaw を最新バージョンにアップグレードするか、Node 20 にダウングレードしてください。

setMyCommands の失敗

api.telegram.org へのアウトバウンド HTTPS/DNS がブロックされている可能性があります。ファイアウォールルールを確認してください。

セキュリティベストプラクティス

1. ボットトークンは絶対に共有しない -- 漏洩した場合は BotFather で直ちに無効化してください
2. DM アクセス制御にはペアリングまたは allowlist を使用
3. グループポリシーを設定 してグループ内で対話できるユーザーを制御
4. ユーザー ID は安全に取得 -- openclaw logs --follow または Bot API の getUpdates エンドポイントを使用し、サードパーティの ID ボットは避けてください
5. 本番デプロイではシークレット付きの Webhook を使用

次のステップ

• WhatsApp 連携ガイド
• Discord 連携ガイド
• 公式 Telegram チャンネルドキュメント