OpenClaw mit Twitch verbinden: In 5 Minuten zum Bot

Jeder, der schon mal versucht hat, einen Bot stabil mit Twitch zu verbinden, kennt das Problem: IRC-Verbindungen, OAuth-Tokens, die plötzlich ablaufen, und die ständige Sorge, dass der Bot im Chat Unsinn macht oder von Fremden übernommen wird. Es ist oft ein unnötiges Hin und Her zwischen Dokumentationen und Token-Generatoren.

Wenn du deinen Agenten direkt in deinen Twitch-Stream bringen willst, ohne dich mit den Details des IRC-Protokolls herumzuschlagen, ist dieses Plugin genau das Richtige für dich. Ich empfehle dir, direkt auf User IDs statt auf Usernamen zu setzen, um die Sicherheit zu erhöhen.

Twitch (Plugin)

Twitch-Chat-Unterstützung über eine IRC-Verbindung. OpenClaw verbindet sich als Twitch-Nutzer (Bot-Account), um Nachrichten in Channels zu empfangen und zu senden.

Plugin erforderlich

Twitch wird als Plugin geliefert und ist nicht in der Standardinstallation enthalten.

Installation über das CLI (npm Registry):

openclaw plugins install @openclaw/twitch

Lokaler Checkout (wenn du aus einem Git-Repo arbeitest):

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

Details: Plugins

Schnelle Einrichtung (Anfänger)

1. Erstelle einen eigenen Twitch-Account für den Bot (oder nutze einen bestehenden).
2. Generiere die Zugangsdaten: Twitch Token Generator
   • Wähle Bot Token
   • Überprüfe, ob die Scopes chat:read und chat:write ausgewählt sind
   • Kopiere die Client ID und das Access Token
3. Finde deine Twitch User ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. Konfiguriere das Token:
   • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (nur für den Default-Account)
   • Oder Config: channels.twitch.accessToken
   • Wenn beides gesetzt ist, hat die Config Vorrang (Env-Fallback gilt nur für den Default-Account).
5. Starte das Gateway.

⚠️ Wichtig: Füge eine Zugriffskontrolle (allowFrom oder allowedRoles) hinzu, um zu verhindern, dass unbefugte Nutzer den Bot triggern. requireMention ist standardmäßig auf true gesetzt.

Minimale Config:

{
  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/
    },
  },
}

Was es ist

• Ein Twitch-Channel, der dem Gateway gehört.
• Deterministisches Routing: Antworten gehen immer zurück an Twitch.
• Jeder Account wird auf einen isolierten Session-Key gemappt: agent:<agentId>:twitch:<accountName>.
• username ist der Account des Bots (der sich authentifiziert), channel ist der Chatraum, dem beigetreten wird.

Einrichtung (im Detail)

Zugangsdaten generieren

Nutze den Twitch Token Generator:

• Wähle Bot Token
• Überprüfe, ob die Scopes chat:read und chat:write ausgewählt sind
• Kopiere die Client ID und das Access Token

Keine manuelle App-Registrierung nötig. Tokens laufen nach einigen Stunden ab.

Bot konfigurieren

Env-Variable (nur Default-Account):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Oder Config:

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

Falls sowohl Env als auch Config gesetzt sind, gewinnt die Config.

Zugriffskontrolle (empfohlen)

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

Nutze bevorzugt allowFrom für eine strikte Allowlist. Verwende stattdessen allowedRoles, wenn du rollenbasierten Zugriff möchtest.

Verfügbare Rollen: "moderator", "owner", "vip", "subscriber", "all".

Warum User IDs? Usernamen können sich ändern, was Identitätsdiebstahl ermöglicht. User IDs sind permanent.

Finde deine Twitch User ID hier: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/

Token-Refresh (optional)

Tokens vom Twitch Token Generator können nicht automatisch erneuert werden – generiere sie neu, wenn sie abgelaufen sind.

Für automatischen Token-Refresh erstellst du eine eigene Twitch-App in der Twitch Developer Console und fügst dies zur Config hinzu:

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

Der Bot erneuert Tokens automatisch vor dem Ablauf und loggt diese Ereignisse.

Unterstützung für mehrere Accounts

Nutze channels.twitch.accounts mit Tokens pro Account. Siehe gateway/configuration für das gemeinsame Muster.

Beispiel (ein Bot-Account in zwei Channels):

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

Hinweis: Jeder Account benötigt sein eigenes Token (ein Token pro Channel).

Zugriffskontrolle

Rollenbasierte Einschränkungen

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

Allowlist nach User ID (am sichersten)

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

Rollenbasierter Zugriff (Alternative)

allowFrom ist eine strikte Allowlist. Wenn sie gesetzt ist, sind nur diese User IDs erlaubt. Wenn du rollenbasierten Zugriff willst, lass allowFrom weg und konfiguriere stattdessen allowedRoles:

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

@mention Anforderung deaktivieren

Standardmäßig ist requireMention auf true. Um das zu deaktivieren und auf alle Nachrichten zu reagieren:

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

Fehlerbehebung

Führe zuerst Diagnose-Befehle aus:

openclaw doctor
openclaw channels status --probe

Bot reagiert nicht auf Nachrichten

Zugriffskontrolle prüfen: Stelle sicher, dass deine User ID in allowFrom steht, oder entferne allowFrom testweise und setze allowedRoles: ["all"].

Channel-Beitritt prüfen: Der Bot muss dem in channel angegebenen Kanal beitreten.

Token-Probleme

“Failed to connect” oder Authentifizierungsfehler:

• Prüfe, ob accessToken der OAuth-Token-Wert ist (beginnt meist mit oauth:)
• Prüfe, ob das Token die Scopes chat:read und chat:write hat
• Falls du Token-Refresh nutzt, prüfe clientSecret und refreshToken

Token-Refresh funktioniert nicht

Logs nach Refresh-Events prüfen:

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

Falls du “token refresh disabled (no refresh token)” siehst:

• Stelle sicher, dass clientSecret vorhanden ist
• Stelle sicher, dass refreshToken vorhanden ist

Konfiguration

Account-Konfiguration:

• username – Bot-Username
• accessToken – OAuth Access Token mit chat:read und chat:write
• clientId – Twitch Client ID (vom Token Generator oder deiner App)
• channel – Channel, dem beigetreten wird (erforderlich)
• enabled – Diesen Account aktivieren (Standard: true)
• clientSecret – Optional: Für automatischen Token-Refresh
• refreshToken – Optional: Für automatischen Token-Refresh
• expiresIn – Token-Ablauf in Sekunden
• obtainmentTimestamp – Zeitstempel des Token-Erhalts
• allowFrom – User ID Allowlist
• allowedRoles – Rollenbasierte Zugriffskontrolle ("moderator" | "owner" | "vip" | "subscriber" | "all")
• requireMention – @mention erforderlich (Standard: true)

Provider-Optionen:

• channels.twitch.enabled – Channel-Start aktivieren/deaktivieren
• channels.twitch.username – Bot-Username (vereinfachte Single-Account Config)
• channels.twitch.accessToken – OAuth Access Token (vereinfachte Single-Account Config)
• channels.twitch.clientId – Twitch Client ID (vereinfachte Single-Account Config)
• channels.twitch.channel – Channel, dem beigetreten wird (vereinfachte Single-Account Config)
• channels.twitch.accounts.<accountName> – Multi-Account Config (alle Account-Felder oben)

Vollständiges Beispiel:

{
  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"],
        },
      },
    },
  },
}

Tool-Aktionen

Der Agent kann twitch mit folgender Aktion aufrufen:

• send – Sendet eine Nachricht in einen Channel

Beispiel:

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

Sicherheit & Betrieb

• Behandle Tokens wie Passwörter – Checke Tokens niemals in Git ein.
• Nutze automatischen Token-Refresh für Bots, die lange laufen sollen.
• Nutze User ID Allowlists statt Usernamen für die Zugriffskontrolle.
• Überwache die Logs auf Token-Refresh-Events und den Verbindungsstatus.
• Schränke Token-Scopes ein – Fordere nur chat:read und chat:write an.
• Wenn nichts mehr geht: Starte das Gateway neu, nachdem du sichergestellt hast, dass kein anderer Prozess die Session blockiert.

Limits

• 500 Zeichen pro Nachricht (automatisches Chunking an Wortgrenzen)
• Markdown wird vor dem Chunking entfernt
• Kein Rate Limiting (nutzt die eingebauten Rate Limits von Twitch)

Verwandte Themen

• Channels Übersicht — alle unterstützten Kanäle
• Pairing — DM-Authentifizierung und Pairing-Flow
• Gruppen — Verhalten in Gruppen-Chats und Mention-Gating
• Channel Routing — Session-Routing für Nachrichten
• Sicherheit — Zugriffsmodell und Härtung

AI Setup Assistant

Nächste Schritte

• Channels Übersicht
• Sicherheit