Twitch

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

Plugin incluso

Twitch viene distribuito come Plugin incluso nelle versioni correnti di OpenClaw, quindi le normali build pacchettizzate non richiedono un’installazione separata.

Se usi una build precedente o un’installazione personalizzata che esclude Twitch, installa direttamente il pacchetto npm:

registro npm
Checkout locale

openclaw plugins install @openclaw/twitch

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

Usa il pacchetto senza vincoli per seguire l’attuale tag di rilascio ufficiale. Fissa una versione esatta solo quando hai bisogno di un’installazione riproducibile. Dettagli: Plugins

Configurazione rapida (principiante)

Assicurati che il Plugin sia disponibile

Le versioni pacchettizzate correnti di OpenClaw lo includono già. Le installazioni precedenti/personalizzate possono aggiungerlo manualmente con i comandi sopra.

Crea un account bot Twitch

Crea un account Twitch dedicato per il bot (oppure usa un account esistente).

Genera le credenziali

Usa Twitch Token Generator:

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

Trova il tuo ID utente Twitch

Usa https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ per convertire un nome utente in un ID utente Twitch.

Configura il token

Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (solo account predefinito)
Oppure configurazione: channels.twitch.accessToken

Se entrambi sono impostati, la configurazione ha la precedenza (il fallback env vale solo per l’account predefinito).

Avvia il Gateway

Avvia il Gateway con il canale configurato.

Aggiungi il controllo degli accessi (allowFrom o allowedRoles) per impedire a utenti non autorizzati di attivare il bot. Il valore predefinito di requireMention è true.

Configurazione minima:

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

Che cos’è

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

Configurazione (dettagliata)

Genera le credenziali

Usa Twitch Token Generator:

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

Non è necessaria alcuna registrazione manuale dell’app. I token scadono dopo diverse ore.

Configura il bot

Variabile env (solo account predefinito)
Configurazione

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

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

Se sono impostati sia env sia configurazione, la configurazione ha la precedenza.

Controllo degli accessi (consigliato)

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

Preferisci allowFrom per una allowlist rigida. Usa invece allowedRoles se vuoi un accesso basato sui ruoli. Ruoli disponibili: "moderator", "owner", "vip", "subscriber", "all".

Perché gli ID utente? I nomi utente possono cambiare, consentendo l’impersonificazione. Gli ID utente sono permanenti.Trova il tuo ID utente Twitch: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (Converti il tuo nome utente Twitch in ID)

Aggiornamento del token (opzionale)

I token di Twitch Token Generator non possono essere aggiornati automaticamente: rigenerali quando scadono. Per l’aggiornamento automatico del token, crea la tua applicazione Twitch in Twitch Developer Console e aggiungi alla configurazione:

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

Il bot aggiorna automaticamente i token prima della scadenza e registra gli eventi di aggiornamento.

Supporto multi-account

Usa channels.twitch.accounts con token per account. Consulta Configurazione 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",
        },
      },
    },
  },
}

Ogni account richiede il proprio token (un token per canale).

Controllo degli accessi

Allowlist di ID utente (più sicura)
Basato sui ruoli
Disabilita il requisito @mention

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

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

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

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

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

Risoluzione dei problemi

Per prima cosa, 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 ID utente sia in allowFrom, oppure rimuovi temporaneamente allowFrom e imposta allowedRoles: ["all"] per provare.
Controlla che il bot sia nel canale: il bot deve unirsi al canale specificato in channel.

Problemi con il token

Errori “Failed to connect” o di autenticazione:

Verifica che accessToken sia il valore del token di accesso OAuth (in genere inizia con il prefisso oauth:)
Controlla che il token abbia gli scope chat:read e chat:write
Se usi l’aggiornamento del token, verifica che clientSecret e refreshToken siano impostati

L'aggiornamento del token non funziona

Controlla nei log gli eventi di aggiornamento:

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

Configurazione dell’account

username

string

Nome utente del bot.

accessToken

string

Token di accesso OAuth con chat:read e chat:write.

clientId

string

Twitch Client ID (da Token Generator o dalla tua app).

channel

string

obbligatorio

Canale a cui unirsi.

enabled

boolean

predefinito:"true"

Abilita questo account.

clientSecret

string

Opzionale: per l’aggiornamento automatico del token.

refreshToken

string

Opzionale: per l’aggiornamento automatico del token.

expiresIn

number

Scadenza del token in secondi.

obtainmentTimestamp

number

Timestamp di ottenimento del token.

allowFrom

string[]

Allowlist di ID utente.

allowedRoles

Array<"moderator" | "owner" | "vip" | "subscriber" | "all">

Controllo degli accessi basato sui ruoli.

requireMention

boolean

predefinito:"true"

Richiede @mention.

Opzioni del provider

channels.twitch.enabled - Abilita/disabilita l’avvio del canale
channels.twitch.username - Nome utente del bot (configurazione semplificata per account singolo)
channels.twitch.accessToken - Token di accesso OAuth (configurazione semplificata per account singolo)
channels.twitch.clientId - Twitch Client ID (configurazione semplificata per account singolo)
channels.twitch.channel - Canale a cui unirsi (configurazione semplificata per account singolo)
channels.twitch.accounts.<accountName> - Configurazione 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 degli strumenti

L’agente può chiamare twitch con l’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 committare mai token in git.
Usa l’aggiornamento automatico del token per bot a lunga esecuzione.
Usa allowlist di ID utente invece dei nomi utente per il controllo degli accessi.
Monitora i log per gli eventi di aggiornamento del token e lo stato della connessione.
Limita al minimo gli scope dei token — Richiedi solo chat:read e chat:write.
Se sei bloccato: riavvia il Gateway dopo aver confermato che nessun altro processo possieda la sessione.

Limiti

500 caratteri per messaggio (suddivisi automaticamente ai confini delle parole).
Il Markdown viene rimosso prima della suddivisione.
Nessun rate limiting (usa i limiti di frequenza integrati di Twitch).

Correlati

Routing dei canali — routing di sessione per i messaggi
Panoramica dei canali — tutti i canali supportati
Gruppi — comportamento delle chat di gruppo e gating delle mention
Pairing — autenticazione DM e flusso di pairing
Sicurezza — modello di accesso e rafforzamento

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Plugin incluso

Configurazione rapida (principiante)

Che cos’è

Configurazione (dettagliata)

Genera le credenziali

Configura il bot

Controllo degli accessi (consigliato)

Aggiornamento del token (opzionale)

Supporto multi-account

Controllo degli accessi

Risoluzione dei problemi

Configurazione

Configurazione dell’account

Opzioni del provider

Azioni degli strumenti

Sicurezza e operazioni

Limiti

Correlati

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Documentation Index

​Plugin incluso

​Configurazione rapida (principiante)

​Che cos’è

​Configurazione (dettagliata)

​Genera le credenziali

​Configura il bot

​Controllo degli accessi (consigliato)

​Aggiornamento del token (opzionale)

​Supporto multi-account

​Controllo degli accessi

​Risoluzione dei problemi

​Configurazione

​Configurazione dell’account

​Opzioni del provider

​Azioni degli strumenti

​Sicurezza e operazioni

​Limiti

​Correlati

Plugin incluso

Configurazione rapida (principiante)

Che cos’è

Configurazione (dettagliata)

Genera le credenziali

Configura il bot

Controllo degli accessi (consigliato)

Aggiornamento del token (opzionale)

Supporto multi-account

Controllo degli accessi

Risoluzione dei problemi

Configurazione

Configurazione dell’account

Opzioni del provider

Azioni degli strumenti

Sicurezza e operazioni

Limiti

Correlati