OpenClaw Twitch連携ガイド：5分でチャットボットを導入

Twitchのチャットボットを動かそうとして、IRCの接続設定や認証トークンの管理で苦労したことはありませんか？OpenClawを使えば、Twitchとの連携を驚くほどスムーズに進めることができます。

ここでは、Twitchプラグインを使ってボットをチャットに参加させる方法を詳しく解説します。

Twitch (plugin)

IRC接続を介したTwitchチャットのサポートを提供します。OpenClawはTwitchユーザー（ボットアカウント）として接続し、チャンネル内でメッセージの送受信を行います。

プラグインが必要です

Twitch機能はプラグインとして提供されており、コア・インストールには含まれていません。

CLI（npmレジストリ）経由でインストールする場合：

openclaw plugins install @openclaw/twitch

ローカルチェックアウト（gitリポジトリから実行している場合）：

openclaw plugins install ./path/to/local/twitch-plugin

詳細はこちら： Plugins

クイックセットアップ（初心者向け）

ボット用の専用Twitchアカウントを作成します（既存のアカウントでも構いません）。
クレデンシャルを生成します： Twitch Token Generator
- Bot Token を選択してください
- chat:read と chat:write のスコープが選択されていることを確認します
- Client ID と Access Token をコピーします
あなたのTwitchユーザーIDを確認します： https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
トークンを設定します：
- 環境変数： OPENCLAW_TWITCH_ACCESS_TOKEN=... （デフォルトアカウントのみ）
- または設定ファイル： channels.twitch.accessToken
- 両方が設定されている場合は、設定ファイルが優先されます（環境変数はデフォルトアカウントのみのフォールバックです）。
Gateway を起動します。

⚠️ 重要: 未権限のユーザーがボットを起動できないように、アクセス制御（allowFrom または allowedRoles）を追加することをおすすめします。requireMention はデフォルトで true になっています。

最小構成の設定例：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Bot's Twitch account
      accessToken: "oauth:abc123...", // OAuth Access Token (or use OPENCLAW_TWITCH_ACCESS_TOKEN env var)
      clientId: "xyz789...", // Client ID from Token Generator
      channel: "vevisk", // Which Twitch channel's chat to join (required)
      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

Twitchプラグインの概要

Gateway が所有するひとつのTwitchチャンネルとして動作します。
決定論的なルーティング：返信は常にTwitchに返されます。
各アカウントは、独立したセッションキー agent:<agentId>:twitch:<accountName> にマッピングされます。
username は認証を行うボットのアカウント、 channel は参加するチャットルームを指します。

セットアップ（詳細）

クレデンシャルの生成

Twitch Token Generator を使用します：

Bot Token を選択
chat:read と chat:write のスコープが選択されていることを確認
Client ID と Access Token をコピー

手動でのアプリケーション登録は不要です。トークンは数時間で期限切れになります。

ボットの設定

環境変数（デフォルトアカウントのみ）：

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

または設定ファイル：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "vevisk",
    },
  },
}

環境変数と設定ファイルの両方が指定されている場合、設定ファイルが優先されます。

アクセス制御（推奨）

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
    },
  },
}

厳格な許可リストを作成するには allowFrom を使用してください。ロールベースのアクセスが必要な場合は、代わりに allowedRoles を使用します。

利用可能なロール: "moderator", "owner", "vip", "subscriber", "all"。

なぜユーザーIDを使うのか？ ユーザー名は変更可能であり、なりすましのリスクがあるからです。ユーザーIDは永続的で変わりません。

TwitchユーザーIDの確認はこちら： https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/

トークンのリフレッシュ（オプション）

Twitch Token Generator で取得したトークンは自動リフレッシュができません。期限が切れたら再生成してください。

トークンの自動リフレッシュを行いたい場合は、Twitch Developer Console で独自のTwitchアプリケーションを作成し、設定に追加してください：

{
  channels: {
    twitch: {
      clientSecret: "your_client_secret",
      refreshToken: "your_refresh_token",
    },
  },
}

ボットは期限が切れる前に自動的にトークンをリフレッシュし、そのイベントをログに記録します。

マルチアカウント対応

複数のアカウントを使用する場合は、channels.twitch.accounts でアカウントごとのトークンを設定します。共通のパターンについては gateway/configuration を参照してください。

例（1つのボットアカウントで2つのチャンネルに参加する場合）：

{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "vevisk",
        },
        channel2: {
          username: "openclaw",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel",
        },
      },
    },
  },
}

注意: 各アカウントには独自のトークンが必要です（1チャンネルにつき1トークン）。

アクセス制御

ロールベースの制限

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator", "vip"],
        },
      },
    },
  },
}

ユーザーIDによる許可リスト（最も安全）

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowFrom: ["123456789", "987654321"],
        },
      },
    },
  },
}

ロールベースアクセスの代替案

allowFrom は厳格な許可リストです。これが設定されている場合、指定されたユーザーIDのみが許可されます。ロールベースのアクセスにしたい場合は、 allowFrom を未設定のままにし、 allowedRoles を設定してください：

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator"],
        },
      },
    },
  },
}

@メンション要件の無効化

デフォルトでは requireMention は true です。これを無効にしてすべてのメッセージに反応させるには、以下のように設定します：

{
  channels: {
    twitch: {
      accounts: {
        default: {
          requireMention: false,
        },
      },
    },
  },
}

トラブルシューティング

まず、診断コマンドを実行してみてください：

openclaw doctor
openclaw channels status --probe

ボットがメッセージに反応しない

アクセス制御を確認: あなたのユーザーIDが allowFrom に含まれているか確認してください。テストのために一時的に allowFrom を削除し、 allowedRoles: ["all"] に設定してみるのも有効です。

ボットがチャンネルにいるか確認: ボットは channel で指定されたチャンネルに参加している必要があります。

トークンの問題

“Failed to connect” または認証エラー:

accessToken が OAuth アクセストークンの値（通常 oauth: プレフィックスで始まります）であることを確認してください。
トークンに chat:read と chat:write のスコープがあるか確認してください。
トークンリフレッシュを使用している場合は、 clientSecret と refreshToken が正しく設定されているか確認してください。

トークンのリフレッシュが機能しない

ログでリフレッシュイベントを確認してください:

Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)

“token refresh disabled (no refresh token)” と表示される場合：

clientSecret が提供されているか確認してください。
refreshToken が提供されているか確認してください。

設定（Config）

アカウント設定:

username - ボットのユーザー名
accessToken - chat:read と chat:write 権限を持つ OAuth アクセストークン
clientId - Twitch Client ID（Token Generator または自作アプリから取得）
channel - 参加するチャンネル（必須）
enabled - このアカウントを有効にする（デフォルト: true）
clientSecret - オプション: 自動トークンリフレッシュ用
refreshToken - オプション: 自動トークンリフレッシュ用
expiresIn - トークンの有効期限（秒）
obtainmentTimestamp - トークン取得時のタイムスタンプ
allowFrom - ユーザーIDの許可リスト
allowedRoles - ロールベースのアクセス制御 ("moderator" | "owner" | "vip" | "subscriber" | "all")
requireMention - @メンションを必須にする（デフォルト: true）

プロバイダーオプション:

channels.twitch.enabled - チャンネル起動の有効/無効
channels.twitch.username - ボットのユーザー名（簡易的な単一アカウント設定用）
channels.twitch.accessToken - OAuth アクセストークン（簡易的な単一アカウント設定用）
channels.twitch.clientId - Twitch Client ID（簡易的な単一アカウント設定用）
channels.twitch.channel - 参加するチャンネル（簡易的な単一アカウント設定用）
channels.twitch.accounts.<accountName> - マルチアカウント設定（上記のアカウントフィールドをすべて使用可能）

フル設定の例：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "vevisk",
      clientSecret: "secret123...",
      refreshToken: "refresh456...",
      allowFrom: ["123456789"],
      allowedRoles: ["moderator", "vip"],
      accounts: {
        default: {
          username: "mybot",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "your_channel",
          enabled: true,
          clientSecret: "secret123...",
          refreshToken: "refresh456...",
          expiresIn: 14400,
          obtainmentTimestamp: 1706092800000,
          allowFrom: ["123456789", "987654321"],
          allowedRoles: ["moderator"],
        },
      },
    },
  },
}

ツールアクション

エージェントは twitch を呼び出して以下のアクションを実行できます：

send - チャンネルにメッセージを送信する

例：

{
  action: "twitch",
  params: {
    message: "Hello Twitch!",
    to: "#mychannel",
  },
}

セキュリティと運用

トークンはパスワードと同様に扱う - 決して git にコミットしないでください。
長時間稼働させるボットには自動トークンリフレッシュを使用する ことをおすすめします。
アクセス制御にはユーザー名ではなくユーザーIDの許可リストを使用 してください。
トークンのリフレッシュイベントや接続ステータスを確認するためにログを監視 してください。
トークンのスコープは最小限に - chat:read と chat:write のみを取得するようにします。
動作が不安定な場合: 他のプロセスがセッションを所有していないことを確認した上で、 Gateway を再起動してください。

制限事項

メッセージあたり 500文字 まで（単語の境界で自動的に分割されます）。
分割前に Markdown は削除されます。
レート制限機能はありません（Twitch内蔵のレート制限が適用されます）。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。