Twitch (Plugin)

Twitch-Chat-Unterstützung via IRC-Verbindung. OpenClaw verbindet sich als Twitch-Benutzer (Bot-Konto), um Nachrichten in Kanälen zu empfangen und zu senden.

Plugin erforderlich

Twitch wird als Plugin ausgeliefert und ist nicht in der Kerninstallation enthalten.

Installation über CLI (npm-Registry):

openclaw plugins install @openclaw/twitch

Lokaler Checkout (wenn aus einem Git-Repo ausgeführt):

openclaw plugins install ./extensions/twitch

Details: Plugins

Schnelleinrichtung (Einsteiger)

  1. Erstelle ein dediziertes Twitch-Konto für den Bot (oder verwende ein bestehendes Konto).
  2. Generiere Zugangsdaten: Twitch Token Generator
    • Wähle Bot Token
    • Überprüfe, dass die Scopes chat:read und chat:write ausgewählt sind
    • Kopiere die Client ID und den Access Token
  3. Finde deine Twitch-Benutzer-ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. Konfiguriere den Token:
    • Umgebungsvariable: OPENCLAW_TWITCH_ACCESS_TOKEN=... (nur Standardkonto)
    • Oder Konfiguration: channels.twitch.accessToken
    • Wenn beides gesetzt ist, hat die Konfiguration Vorrang (Umgebungsvariable als Fallback nur für das Standardkonto).
  5. Starte das Gateway.

Warnung: Füge eine Zugriffssteuerung hinzu (allowFrom oder allowedRoles), um zu verhindern, dass unautorisierte Benutzer den Bot auslösen. requireMention ist standardmäßig true.

Minimale Konfiguration:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Twitch-Konto des Bots
      accessToken: "oauth:abc123...", // OAuth Access Token (oder OPENCLAW_TWITCH_ACCESS_TOKEN Umgebungsvariable)
      clientId: "xyz789...", // Client ID vom Token Generator
      channel: "vevisk", // Welchem Twitch-Kanal-Chat beitreten (erforderlich)
      allowFrom: ["123456789"], // (empfohlen) Nur deine Twitch-Benutzer-ID - hole sie von https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

Was es ist

  • Ein Twitch-Kanal, der vom Gateway betrieben wird.
  • Deterministisches Routing: Antworten gehen immer zurück zu Twitch.
  • Jedes Konto bildet einen isolierten Session-Schlüssel ab: agent:<agentId>:twitch:<accountName>.
  • username ist das Konto des Bots (wer sich authentifiziert), channel ist welchem Chatraum beigetreten wird.

Einrichtung (detailliert)

Zugangsdaten generieren

Verwende den Twitch Token Generator:

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

Keine manuelle App-Registrierung nötig. Tokens verfallen nach mehreren Stunden.

Bot konfigurieren

Umgebungsvariable (nur Standardkonto):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Oder Konfiguration:

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

Wenn sowohl Umgebungsvariable als auch Konfiguration gesetzt sind, hat die Konfiguration Vorrang.

Zugriffssteuerung (empfohlen)

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (empfohlen) Nur deine Twitch-Benutzer-ID
    },
  },
}

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

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

Warum Benutzer-IDs? Benutzernamen können geändert werden, was Identitätsdiebstahl ermöglicht. Benutzer-IDs sind dauerhaft.

Finde deine Twitch-Benutzer-ID: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Twitch-Benutzernamen in ID konvertieren)

Token-Aktualisierung (optional)

Tokens vom Twitch Token Generator können nicht automatisch aktualisiert werden - generiere sie bei Ablauf neu.

Für automatische Token-Aktualisierung erstelle deine eigene Twitch-Anwendung in der Twitch Developer Console und füge sie zur Konfiguration hinzu:

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

Der Bot aktualisiert Tokens automatisch vor dem Ablauf und protokolliert Aktualisierungsereignisse.

Multi-Account-Unterstützung

Verwende channels.twitch.accounts mit Pro-Konto-Tokens. Siehe gateway/configuration für das gemeinsame Muster.

Beispiel (ein Bot-Konto in zwei Kanälen):

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

Hinweis: Jedes Konto braucht seinen eigenen Token (ein Token pro Kanal).

Zugriffssteuerung

Rollenbasierte Einschränkungen

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

Allowlist nach Benutzer-ID (sicherste Option)

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

Rollenbasierter Zugriff (Alternative)

allowFrom ist eine strikte Allowlist. Wenn gesetzt, sind nur diese Benutzer-IDs erlaubt. Wenn du rollenbasierten Zugriff möchtest, lasse allowFrom ungesetzt und konfiguriere stattdessen allowedRoles:

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

@Mention-Anforderung deaktivieren

Standardmäßig ist requireMention auf true gesetzt. Um sie zu deaktivieren und auf alle Nachrichten zu antworten:

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

Fehlerbehebung

Führe zuerst die Diagnosebefehle aus:

openclaw doctor
openclaw channels status --probe

Bot antwortet nicht auf Nachrichten

Zugriffssteuerung prüfen: Stelle sicher, dass deine Benutzer-ID in allowFrom enthalten ist, oder entferne allowFrom vorübergehend und setze allowedRoles: ["all"] zum Testen.

Prüfen, ob der Bot im Kanal ist: Der Bot muss dem in channel angegebenen Kanal beitreten.

Token-Probleme

„Failed to connect” oder Authentifizierungsfehler:

  • Überprüfe, ob accessToken der OAuth-Access-Token-Wert ist (beginnt üblicherweise mit dem Präfix oauth:)
  • Prüfe, ob der Token die Scopes chat:read und chat:write hat
  • Bei Verwendung von Token-Aktualisierung überprüfe, ob clientSecret und refreshToken gesetzt sind

Token-Aktualisierung funktioniert nicht

Logs auf Aktualisierungsereignisse prüfen:

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

Wenn du „token refresh disabled (no refresh token)” siehst:

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

Konfiguration

Konto-Konfiguration:

  • username - Bot-Benutzername
  • accessToken - OAuth Access Token mit chat:read und chat:write
  • clientId - Twitch Client ID (vom Token Generator oder deiner App)
  • channel - Kanal, dem beigetreten wird (erforderlich)
  • enabled - Dieses Konto aktivieren (Standard: true)
  • clientSecret - Optional: Für automatische Token-Aktualisierung
  • refreshToken - Optional: Für automatische Token-Aktualisierung
  • expiresIn - Token-Ablauf in Sekunden
  • obtainmentTimestamp - Zeitstempel des Token-Erhalts
  • allowFrom - Benutzer-ID-Allowlist
  • allowedRoles - Rollenbasierte Zugriffssteuerung ("moderator" | "owner" | "vip" | "subscriber" | "all")
  • requireMention - @Mention erforderlich (Standard: true)

Provider-Optionen:

  • channels.twitch.enabled - Kanal-Start aktivieren/deaktivieren
  • channels.twitch.username - Bot-Benutzername (vereinfachte Einzelkonto-Konfiguration)
  • channels.twitch.accessToken - OAuth Access Token (vereinfachte Einzelkonto-Konfiguration)
  • channels.twitch.clientId - Twitch Client ID (vereinfachte Einzelkonto-Konfiguration)
  • channels.twitch.channel - Kanal zum Beitreten (vereinfachte Einzelkonto-Konfiguration)
  • channels.twitch.accounts.<accountName> - Multi-Account-Konfiguration (alle oben genannten Kontofelder)

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 Aktion aufrufen:

  • send - Eine Nachricht an einen Kanal senden

Beispiel:

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

Sicherheit & Betrieb

  • Behandle Tokens wie Passwörter - Committe Tokens niemals in Git
  • Verwende automatische Token-Aktualisierung für dauerlaufende Bots
  • Verwende Benutzer-ID-Allowlists statt Benutzernamen für Zugriffssteuerung
  • Überwache Logs auf Token-Aktualisierungsereignisse und Verbindungsstatus
  • Minimale Token-Scopes - Fordere nur chat:read und chat:write an
  • Bei Blockade: Starte das Gateway neu, nachdem du bestätigt hast, dass kein anderer Prozess die Session besitzt

Limits

  • 500 Zeichen pro Nachricht (automatisch an Wortgrenzen aufgeteilt)
  • Markdown wird vor dem Aufteilen entfernt
  • Kein eigenes Rate-Limiting (verwendet Twitchs eingebaute Rate-Limits)
arrow_back
Zurück
Tlon
Weiter
Whatsapp
arrow_forward