Twitch (plugin)

Supporto chat Twitch tramite connessione IRC. OpenClaw si connette come utente Twitch (account bot) per ricevere e inviare messaggi nei canali.

Plugin necessario

Twitch e distribuito come plugin e non e incluso nell’installazione core.

Installa da CLI (registro npm):

openclaw plugins install @openclaw/twitch

Da checkout locale (se stai lavorando da un repo git):

openclaw plugins install ./extensions/twitch

Dettagli: Plugin

Setup rapido (principianti)

  1. Crea un account Twitch dedicato per il bot (o usa un account esistente).
  2. Genera le credenziali: Twitch Token Generator
    • Seleziona Bot Token
    • Verifica che gli scope chat:read e chat:write siano selezionati
    • Copia il Client ID e l’Access Token
  3. Trova il tuo Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. Configura il token:
    • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (solo account predefinito)
    • Oppure config: channels.twitch.accessToken
    • Se entrambi sono impostati, il config ha la precedenza (env fallback solo per l’account predefinito).
  5. Avvia il gateway.

Attenzione: Aggiungi il controllo degli accessi (allowFrom o allowedRoles) per impedire a utenti non autorizzati di attivare il bot. requireMention e true per impostazione predefinita.

Configurazione minimale:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Account Twitch del bot
      accessToken: "oauth:abc123...", // OAuth Access Token (o usa la variabile env OPENCLAW_TWITCH_ACCESS_TOKEN)
      clientId: "xyz789...", // Client ID dal Token Generator
      channel: "vevisk", // Chat del canale Twitch da unirsi (obbligatorio)
      allowFrom: ["123456789"], // (consigliato) Solo il tuo Twitch user ID - ottienilo da https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

Cos’e

  • Un canale Twitch gestito dal Gateway.
  • Routing deterministico: le risposte tornano sempre a Twitch.
  • Ogni account mappa a una chiave di sessione isolata agent:<agentId>:twitch:<accountName>.
  • username e l’account del bot (chi si autentica), channel e la chat room a cui unirsi.

Setup (dettagliato)

Generare le credenziali

Usa Twitch Token Generator:

  • Seleziona Bot Token
  • Verifica che gli scope chat:read e chat:write siano selezionati
  • Copia il Client ID e l’Access Token

Non serve registrare manualmente un’app. I token scadono dopo diverse ore.

Configurare il bot

Variabile env (solo account predefinito):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Oppure config:

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

Se entrambi env e config sono impostati, il config ha la precedenza.

Controllo degli accessi (consigliato)

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (consigliato) Solo il tuo Twitch user ID
    },
  },
}

Preferisci allowFrom per un’allowlist rigida. Usa allowedRoles in alternativa se vuoi accesso basato sui ruoli.

Ruoli disponibili: "moderator", "owner", "vip", "subscriber", "all".

Perche gli user ID? Gli username possono cambiare, consentendo impersonificazione. Gli user ID sono permanenti.

Trova il tuo Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Converti il tuo username Twitch in ID)

Rinnovo token (opzionale)

I token da Twitch Token Generator non possono essere rinnovati automaticamente — rigenerali quando scadono.

Per il rinnovo automatico dei token, crea la tua applicazione Twitch su Twitch Developer Console e aggiungi al config:

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

Il bot rinnova automaticamente i token prima della scadenza e registra gli eventi di rinnovo.

Supporto multi-account

Usa channels.twitch.accounts con token per account. Vedi gateway/configuration per il pattern condiviso.

Esempio (un account bot in due canali):

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

Nota: Ogni account necessita del proprio token (un token per canale).

Controllo degli accessi

Restrizioni basate sui ruoli

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

Allowlist per User ID (piu sicuro)

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

Accesso basato sui ruoli (alternativa)

allowFrom e un’allowlist rigida. Quando impostata, solo quegli user ID sono consentiti. Se vuoi accesso basato sui ruoli, lascia allowFrom non impostato e configura allowedRoles invece:

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

Disabilitare il requisito @menzione

Per impostazione predefinita, requireMention e true. Per disabilitare e rispondere a tutti i messaggi:

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

Risoluzione problemi

Prima, esegui i comandi diagnostici:

openclaw doctor
openclaw channels status --probe

Il bot non risponde ai messaggi

Controlla il controllo degli accessi: Assicurati che il tuo user ID sia in allowFrom, o rimuovi temporaneamente allowFrom e imposta allowedRoles: ["all"] per testare.

Controlla che il bot sia nel canale: Il bot deve unirsi al canale specificato in channel.

Problemi con i token

“Failed to connect” o errori di autenticazione:

  • Verifica che accessToken sia il valore del token OAuth access (tipicamente inizia con il prefisso oauth:)
  • Controlla che il token abbia gli scope chat:read e chat:write
  • Se usi il rinnovo token, verifica che clientSecret e refreshToken siano impostati

Rinnovo token non funzionante

Controlla i log per eventi di rinnovo:

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

Se vedi “token refresh disabled (no refresh token)”:

  • Assicurati che clientSecret sia fornito
  • Assicurati che refreshToken sia fornito

Configurazione

Config account:

  • username - Username del bot
  • accessToken - Token OAuth access con chat:read e chat:write
  • clientId - Twitch Client ID (dal Token Generator o dalla tua app)
  • channel - Canale da unirsi (obbligatorio)
  • enabled - Abilita questo account (predefinito: true)
  • clientSecret - Opzionale: per il rinnovo automatico dei token
  • refreshToken - Opzionale: per il rinnovo automatico dei token
  • expiresIn - Scadenza token in secondi
  • obtainmentTimestamp - Timestamp di ottenimento del token
  • allowFrom - Allowlist user ID
  • allowedRoles - Controllo accessi basato sui ruoli ("moderator" | "owner" | "vip" | "subscriber" | "all")
  • requireMention - Richiedi @menzione (predefinito: true)

Opzioni del provider:

  • channels.twitch.enabled - Abilita/disabilita l’avvio del canale
  • channels.twitch.username - Username del bot (config account singolo semplificato)
  • channels.twitch.accessToken - Token OAuth access (config account singolo semplificato)
  • channels.twitch.clientId - Twitch Client ID (config account singolo semplificato)
  • channels.twitch.channel - Canale da unirsi (config account singolo semplificato)
  • channels.twitch.accounts.<accountName> - Config multi-account (tutti i campi account sopra)

Esempio completo:

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

Azioni strumento

L’agent puo chiamare twitch con azione:

  • send - Invia un messaggio a un canale

Esempio:

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

Sicurezza e operazioni

  • Tratta i token come password — Non fare mai il commit dei token su git
  • Usa il rinnovo automatico dei token per bot a lunga esecuzione
  • Usa allowlist di user ID invece degli username per il controllo degli accessi
  • Monitora i log per eventi di rinnovo token e stato della connessione
  • Riduci gli scope dei token al minimo — Richiedi solo chat:read e chat:write
  • Se sei bloccato: Riavvia il gateway dopo aver confermato che nessun altro processo possiede la sessione

Limiti

  • 500 caratteri per messaggio (segmentazione automatica ai confini di parola)
  • Il Markdown viene rimosso prima della segmentazione
  • Nessun rate limiting (usa i rate limit integrati di Twitch)
arrow_back
Precedente
Tlon
Successivo
Whatsapp
arrow_forward