Twitch (プラグイン)

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

プラグインが必要

Twitchはプラグインとして提供され、コアインストールにはバンドルされていません。

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

openclaw plugins install @openclaw/twitch

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

openclaw plugins install ./extensions/twitch

詳細：プラグイン

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

  1. ボット用の専用Twitchアカウントを作成します（または既存のアカウントを使用）。
  2. 認証情報を生成：Twitch Token Generator
    • Bot Tokenを選択
    • スコープchat:readとchat:writeが選択されていることを確認
    • Client IDとAccess Tokenをコピー
  3. Twitch ユーザーIDを検索：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. トークンを設定：
    • 環境変数：OPENCLAW_TWITCH_ACCESS_TOKEN=...（デフォルトアカウントのみ）
    • または設定：channels.twitch.accessToken
    • 両方設定されている場合、設定が優先されます（環境変数フォールバックはデフォルトアカウントのみ）。
  5. ゲートウェイを起動します。

⚠️ 重要： 不正なユーザーがボットをトリガーするのを防ぐため、アクセス制御（allowFromまたはallowedRoles）を追加してください。requireMentionはデフォルトでtrueです。

最小限の設定：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",              // ボットのTwitchアカウント
      accessToken: "oauth:abc123...",    // OAuth Access Token（またはOPENCLAW_TWITCH_ACCESS_TOKEN環境変数を使用）
      clientId: "xyz789...",             // Token GeneratorからのClient ID
      channel: "vevisk",                 // 参加するTwitchチャネルのチャット（必須）
      allowFrom: ["123456789"]           // （推奨）あなたのTwitchユーザーIDのみ - https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ から取得
    }
  }
}

これは何か

  • ゲートウェイが所有する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"],       // （推奨）あなたのTwitchユーザーIDのみ
      allowedRoles: ["moderator"]     // またはロールで制限
    }
  }
}

利用可能なロール： "moderator"、"owner"、"vip"、"subscriber"、"all"。

なぜユーザーID？ ユーザー名は変更可能で、なりすましを許します。ユーザーIDは永続的です。

Twitch ユーザーIDを検索：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/（TwitchユーザーネームをIDに変換）

トークン更新（オプション）

Twitch Token Generatorからのトークンは自動的に更新できません - 期限切れ時に再生成してください。

自動トークン更新の場合、Twitch Developer Consoleで独自のTwitchアプリケーションを作成し、設定に追加します：

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

ボットは期限切れ前にトークンを自動的に更新し、更新イベントをログに記録します。

マルチアカウントサポート

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

例（2つのチャネルで1つのボットアカウント）：

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

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

アクセス制御

ロールベースの制限

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

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

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

許可リスト + ロールの組み合わせ

allowFromのユーザーはロールチェックをバイパスします：

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

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

デフォルトでは、requireMentionはtrueです。無効にしてすべてのメッセージに応答するには：

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

トラブルシューティング

まず、診断コマンドを実行：

openclaw doctor
openclaw channels status --probe

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

アクセス制御を確認： テストのために一時的に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が提供されていることを確認

設定

アカウント設定：

  • 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": "こんにちはTwitch！",
    "to": "#mychannel"
  }
}

安全性と運用

  • トークンをパスワードのように扱う - トークンをgitにコミットしない
  • 自動トークン更新を使用 長時間実行するボット用
  • ユーザーID許可リストを使用 アクセス制御にユーザー名の代わりに
  • ログを監視 トークン更新イベントと接続ステータス用
  • トークンのスコープを最小限に - chat:readとchat:writeのみをリクエスト
  • 行き詰まったら：他のプロセスがセッションを所有していないことを確認した後、ゲートウェイを再起動

制限

  • メッセージあたり500文字（単語境界で自動チャンク化）
  • Markdownはチャンク化前に削除されます
  • レート制限なし（Twitchの組み込みレート制限を使用）
← ドキュメントに戻る