Twitch (Plugin)

Twitch Chat-Unterstützung über IRC-Verbindung. OpenClaw verbindet sich als Twitch-Benutzer (Bot-Account), um Nachrichten in Channels 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 du aus einem Git-Repo arbeitest):

openclaw plugins install ./extensions/twitch

Details: Plugins

Schnelleinrichtung (Einsteiger)

  1. Erstelle einen dedizierten Twitch-Account für den Bot (oder nutze einen bestehenden Account).
  2. Generiere Zugangsdaten: Twitch Token Generator
    • Wähle Bot Token
    • Stelle sicher, dass 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 Default-Account)
    • Oder config: channels.twitch.accessToken
    • Wenn beides gesetzt ist, hat die Config Vorrang (Env-Fallback gilt nur für Default-Account).
  5. Starte das Gateway.

⚠️ Wichtig: Füge Zugriffskontrolle hinzu (allowFrom oder allowedRoles), um zu verhindern, dass unbefugte Benutzer den Bot auslösen. 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 (oder nutze OPENCLAW_TWITCH_ACCESS_TOKEN env var)
      clientId: "xyz789...", // Client ID vom Token Generator
      channel: "vevisk", // Welchem Twitch-Channel-Chat beitreten (erforderlich)
      allowFrom: ["123456789"], // (empfohlen) Nur deine Twitch User ID - hole sie von https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

Was es ist

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

Einrichtung (detailliert)

Zugangsdaten generieren

Nutze den Twitch Token Generator:

  • Wähle Bot Token
  • Stelle sicher, dass 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 mehreren Stunden ab.

Bot konfigurieren

Env var (nur Default-Account):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Oder Config:

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

Wenn sowohl Env als auch Config gesetzt sind, hat die Config Vorrang.

Zugriffskontrolle (empfohlen)

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

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

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

Warum User IDs? Benutzernamen können sich ändern und ermöglichen Impersonation. User IDs sind permanent.

Finde deine Twitch User ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (Konvertiere deinen Twitch-Benutzernamen zur ID)

Token Refresh (optional)

Tokens vom Twitch Token Generator können nicht automatisch erneuert werden - generiere sie neu, wenn sie ablaufen.

Für automatisches Token Refresh erstelle deine eigene Twitch-Anwendung in der Twitch Developer Console und füge zur Config hinzu:

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

Der Bot erneuert Tokens automatisch vor Ablauf und loggt Refresh-Events.

Multi-Account-Unterstützung

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

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 braucht 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 harte Allowlist. Wenn gesetzt, sind nur diese User IDs erlaubt. Wenn du rollenbasierten Zugriff möchtest, lass allowFrom ungesetzt und konfiguriere stattdessen allowedRoles:

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

@mention-Anforderung deaktivieren

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

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

Troubleshooting

Führe zuerst Diagnose-Befehle aus:

openclaw doctor
openclaw channels status --probe

Bot antwortet nicht auf Nachrichten

Prüfe Zugriffskontrolle: Stelle sicher, dass deine User ID in allowFrom ist, oder entferne temporär allowFrom und setze allowedRoles: ["all"] zum Testen.

Prüfe, ob der Bot im Channel ist: Der Bot muss dem Channel beitreten, der in channel angegeben ist.

Token-Probleme

“Failed to connect” oder Authentifizierungsfehler:

  • Überprüfe, dass accessToken der OAuth Access Token-Wert ist (beginnt typischerweise mit oauth:-Präfix)
  • Prüfe, dass das Token die Scopes chat:read und chat:write hat
  • Wenn du Token Refresh nutzt, überprüfe, dass clientSecret und refreshToken gesetzt sind

Token Refresh funktioniert nicht

Prüfe Logs auf Refresh-Events:

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

Config

Account Config:

  • username - Bot-Benutzername
  • accessToken - OAuth Access Token mit chat:read und chat:write
  • clientId - Twitch Client ID (vom Token Generator oder deiner App)
  • channel - Channel zum Beitreten (erforderlich)
  • enabled - Diesen Account aktivieren (Standard: true)
  • clientSecret - Optional: Für automatisches Token Refresh
  • refreshToken - Optional: Für automatisches Token Refresh
  • expiresIn - Token-Ablauf in Sekunden
  • obtainmentTimestamp - Token-Erhalt-Zeitstempel
  • 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-Benutzername (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 zum Beitreten (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 Actions

Der Agent kann twitch mit folgender Action aufrufen:

  • send - Sende eine Nachricht an einen Channel

Beispiel:

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

Sicherheit & Betrieb

  • Behandle Tokens wie Passwörter - Committe niemals Tokens in Git
  • Nutze automatisches Token Refresh für langlebige Bots
  • Nutze User ID Allowlists statt Benutzernamen für Zugriffskontrolle
  • Überwache Logs auf Token-Refresh-Events und Verbindungsstatus
  • Minimiere Token-Scopes - Fordere nur chat:read und chat:write an
  • Bei Problemen: 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 Rate Limiting (nutzt Twitchs eingebaute Rate Limits)