インテグレーション10 分で読めます

OpenClaw Telegram 連携完全ガイド

Telegram ボットを作成して OpenClaw に接続する方法を学びます。ボット作成、設定、コマンド、グループチャット設定を網羅した完全チュートリアル。

OpenClaw Guides

Tutorial Authors

2025-02-04

概要

Telegram 連携により、専用の Telegram ボットを通じて OpenClaw と対話できます。OpenClaw はデフォルトでロングポーリングに grammY フレームワークを使用し、本番デプロイ向けにオプションで Webhook もサポートしています。

前提条件

OpenClaw がインストールされ実行中であること
Telegram アカウント

ステップ1：Telegram ボットを作成

BotFather と会話

Telegram を開き @BotFather を検索
チャットを開始して /newbot を送信
プロンプトに従います：

You: /newbot

BotFather: Alright, a new bot. How are we going to call it?
           Please choose a name for your bot.

You: My OpenClaw Assistant

BotFather: Good. Now let's choose a username for your bot.
           It must end in `bot`. Like this, for example:
           TetrisBot or tetris_bot.

You: myopenclaw_bot

BotFather: Done! Congratulations on your new bot. You will find it at
           t.me/myopenclaw_bot. You can now add a description, about
           section and profile picture for your bot.

           Use this token to access the HTTP API:
           123456789:ABCdefGHIjklMNOpqrsTUVwxyz

           Keep your token secure and store it safely.

ボットトークンを保存してください -- 次のステップで必要になります。

プライバシーモードを無効化（グループでの使用推奨）

グループチャットでボットを使用する予定がある場合、すべてのメッセージを読めるようにプライバシーモードを無効化します：

/setprivacy
@myopenclaw_bot
Disable

プライバシーモードを変更した後、変更を有効にするには既存のグループからボットを削除して再追加する必要があります。代替として、ボットをグループ管理者に昇格させることもできます -- 管理者ボットは常にすべてのメッセージを受信します。

ステップ2：OpenClaw を設定

トークンの保存

ボットトークンは2つの方法で保存できます。設定ファイルは環境変数より優先されます。

オプション A -- 環境変数：

bash

# ~/.openclaw/.env に追加
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz

オプション B -- 設定ファイルに直接記述：

json5

// ~/.openclaw/openclaw.json
{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

最小構成

~/.openclaw/openclaw.json を編集：

json5

{
  channels: {
    telegram: {
      // 環境変数 TELEGRAM_BOT_TOKEN からトークンを取得、または botToken を直接設定
    }
  }
}

これだけで十分です -- Telegram チャンネルが設定されると、OpenClaw は自動的にロングポーリングを開始します。

ステップ3：ボットをテスト

Telegram を開き、ボットのユーザー名を検索
/start でチャットを開始
メッセージを送信してテスト

アクセス制御 -- DM ポリシー

dmPolicy を使用して、プライベートチャットでボットにメッセージを送れるユーザーを制御します：

| ポリシー | 動作 | |--------|----------| | "pairing"（デフォルト） | 不明な送信者にはペアリングコード（有効期限付き）が発行され、CLI で承認します | | "allowlist" | allowFrom に含まれるユーザー ID / @ユーザー名のみメッセージ可能 | | "open" | 誰でもボットにメッセージを送信可能 | | "disabled" | DM を完全に無効化 |

ペアリングモード（デフォルト）

新しいユーザーがボットにメッセージを送ると、ペアリングコードを受け取ります。以下で承認します：

bash

# 保留中のペアリングリクエストを一覧表示
openclaw pairing list telegram

# 特定のコードを承認
openclaw pairing approve telegram <CODE>

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

allowlist モード

json5

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

open モード

json5

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

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

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

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

json5

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

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

json5

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

グループポリシー

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

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

json5

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

メンション要件

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

json5

{
  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 メッセージに分割されます：

json5

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

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

メディア処理

メディアサイズ制限

json5

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

スタンプ

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

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

json5

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

履歴とコンテキスト

json5

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

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

json5

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

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

ストリーミング

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

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

block モードの設定：

json5

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

Webhook モード（本番環境）

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

json5

{
  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 | モデルの表示/切り替え |

カスタムコマンド

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

json5

{
  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" | 両方 + 送信者フィルタリング（デフォルト） |

ネットワークとプロキシ

json5

{
  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 プロキシ
    }
  }
}

トラブルシューティング

ボットが応答しない

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

bash

curl "https://api.telegram.org/bot<TOKEN>/getMe"

OpenClaw のログを確認：

bash

openclaw logs --follow

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

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

IPv6 ルーティングの失敗

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

bash

dig api.telegram.org AAAA

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

bash

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

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

json5

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

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

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

`setMyCommands` の失敗

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

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

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

概要

前提条件

ステップ1：Telegram ボットを作成

BotFather と会話

プライバシーモードを無効化（グループでの使用推奨）

ステップ2：OpenClaw を設定

トークンの保存

最小構成

ステップ3：ボットをテスト

アクセス制御 -- DM ポリシー

ペアリングモード（デフォルト）

allowlist モード

open モード

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

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

グループポリシー

メンション要件

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

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

HTML パースモード

テキストチャンキング

メディア処理

メディアサイズ制限

スタンプ

履歴とコンテキスト

ストリーミング

Webhook モード（本番環境）

コマンド

ネイティブコマンド

カスタムコマンド

インラインボタン

ネットワークとプロキシ

トラブルシューティング

ボットが応答しない

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

IPv6 ルーティングの失敗

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

setMyCommands の失敗

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

次のステップ

`setMyCommands` の失敗