OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Developer and self-hosted

Twitch

Compatibilidad con el chat de Twitch a través de su interfaz de chat (IRC) mediante el cliente Twurple. OpenClaw inicia sesión como una cuenta de bot de Twitch, se une a un canal por cada cuenta configurada y responde en ese canal.

Instalación

Twitch se distribuye como Plugin oficial; no forma parte de la instalación principal.

Registro de npm

bash
openclaw plugins install @openclaw/twitch

Copia de trabajo local

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

plugins install registra y habilita el Plugin. Seleccionar Twitch durante openclaw onboard o openclaw channels add lo instala cuando es necesario. Use el nombre del paquete sin versión para seguir la versión actual; fije una versión exacta solo para instalaciones reproducibles. Requiere OpenClaw 2026.4.10 o posterior.

Detalles: Plugins

Configuración rápida

  • Instalar el Plugin

    Consulte Instalación arriba.

  • Crear una cuenta de bot de Twitch

    Cree una cuenta de Twitch dedicada para el bot (o use una cuenta existente).

  • Generar credenciales

    Use Twitch Token Generator:

    • Seleccione Bot Token
    • Verifique que estén seleccionados los ámbitos chat:read y chat:write
    • Copie Client ID y Access Token

  • Buscar su ID de usuario de Twitch

    Use https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ para convertir un nombre de usuario en un ID de usuario de Twitch.

  • Configurar el token

    • Variable de entorno: OPENCLAW_TWITCH_ACCESS_TOKEN=... (solo para la cuenta predeterminada)
    • O configuración: channels.twitch.accessToken

    Si se establecen ambos, la configuración tiene prioridad (la variable de entorno solo se usa como alternativa para la cuenta predeterminada).

  • Iniciar el Gateway

    bash
    openclaw gateway run

    • Configuración mínima:

    json5
    {  channels: {    twitch: {      enabled: true,      username: "openclaw", // Cuenta de Twitch del bot (se autentica)      accessToken: "oauth:abc123...", // Token de acceso OAuth (o use la variable de entorno OPENCLAW_TWITCH_ACCESS_TOKEN)      clientId: "xyz789...", // ID de cliente de Token Generator      channel: "yourchannel", // Chat del canal de Twitch al que se unirá (obligatorio)      allowFrom: ["123456789"], // (recomendado) Solo su ID de usuario de Twitch    },  },}

    Qué es

    • Un canal de Twitch administrado por el Gateway.
    • Enrutamiento determinista: las respuestas siempre vuelven al canal de Twitch del que provino el mensaje.
    • Cada canal al que se une se asigna a una clave de sesión de grupo aislada agent:<agentId>:twitch:group:<channel>.
    • username es la cuenta del bot (la que se autentica) y channel es la sala de chat a la que se unirá. Cada entrada de cuenta se une exactamente a un canal.
    • Los tokens funcionan con o sin el prefijo oauth:; OpenClaw normaliza ambos formatos (el asistente de configuración espera el formato oauth:).

    Renovación del token (opcional)

    OpenClaw no puede renovar los tokens de Twitch Token Generator; genérelos de nuevo cuando caduquen (duran unas horas y no requieren registrar una aplicación).

    Para renovarlos automáticamente, cree su propia aplicación en Twitch Developer Console y añada:

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

    Si ambos están establecidos, el Plugin usa un proveedor de autenticación con renovación que renueva los tokens antes de que caduquen y registra cada renovación. Sin refreshToken, registra token refresh disabled (no refresh token); sin clientSecret, recurre a un token estático (sin renovación).

    Compatibilidad con varias cuentas

    Use channels.twitch.accounts con credenciales para cada cuenta. Consulte Configuración para conocer el patrón compartido.

    Ejemplo (una cuenta de bot en dos canales):

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

    Control de acceso

    allowFrom es una lista estricta de ID de usuario de Twitch permitidos. Cuando se establece, se ignora allowedRoles; deje allowFrom sin establecer para usar en su lugar el acceso basado en roles.

    Roles disponibles: "moderator", "owner", "vip", "subscriber", "all".

    Lista de ID de usuario permitidos (más segura)

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

    Basado en roles

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

    Deshabilitar el requisito de @mención

    De forma predeterminada, requireMention es true. Para responder a todos los mensajes permitidos:

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

    Solución de problemas

    Primero, ejecute los comandos de diagnóstico:

    bash
    openclaw doctoropenclaw channels status --probe
    El bot no responde a los mensajes
    • Compruebe el control de acceso: Asegúrese de que su ID de usuario esté en allowFrom, o quite temporalmente allowFrom y establezca allowedRoles: ["all"] para realizar una prueba.
    • Compruebe la condición de mención: Con requireMention: true (valor predeterminado), los mensajes deben incluir una @mención al nombre de usuario del bot.
    • Compruebe que el bot esté en el canal: El bot solo se une al canal indicado en channel.
    Problemas con el token

    Errores de autenticación o "Failed to connect":

    • Verifique que accessToken sea el valor del token de acceso OAuth (el prefijo oauth: es opcional)
    • Compruebe que el token tenga los ámbitos chat:read y chat:write
    • Si usa la renovación del token, verifique que clientSecret y refreshToken estén establecidos
    La renovación del token no funciona

    Compruebe si hay eventos de renovación en los registros:

    text
    Using env token source for mybotAccess token refreshed for user 123456 (expires in 14400s)

    Si ve token refresh disabled (no refresh token):

    • Asegúrese de proporcionar clientSecret
    • Asegúrese de proporcionar refreshToken

    Configuración

    Configuración de la cuenta

    usernamestringrequired

    Nombre de usuario del bot (la cuenta que se autentica).

    accessTokenstringrequired

    Token de acceso OAuth con chat:read y chat:write (mediante configuración o variable de entorno para la cuenta predeterminada).

    clientIdstringrequired

    ID de cliente de Twitch (de Token Generator o de su aplicación). Es opcional en el esquema, pero obligatorio para conectarse.

    channelstringrequired

    Canal al que se unirá.

    enabledbooleandefault: true

    Habilita esta cuenta.

    clientSecretstring

    Opcional: para la renovación automática del token.

    refreshTokenstring

    Opcional: para la renovación automática del token.

    expiresInnumber

    Caducidad del token en segundos (seguimiento de la renovación).

    obtainmentTimestampnumber

    Marca de tiempo en la que se obtuvo el token (seguimiento de la renovación).

    allowFromstring[]

    Lista de ID de usuario permitidos. Cuando se establece, se ignoran los roles.

    allowedRoles'Array<"moderator"
    requireMentionbooleandefault: true

    Requiere una @mención para activar el bot.

    responsePrefixstring

    Sustitución del prefijo de las respuestas salientes para esta cuenta.

    Opciones del proveedor

    • channels.twitch.enabled - Habilita o deshabilita el inicio del canal
    • channels.twitch.username / accessToken / clientId / channel - Configuración simplificada de una sola cuenta (cuenta default implícita; tiene prioridad sobre accounts.default)
    • channels.twitch.accounts.<accountName> - Configuración de varias cuentas (todos los campos de cuenta anteriores)
    • channels.twitch.defaultAccount - Nombre de la cuenta predeterminada
    • channels.twitch.markdown.tables - Modo de representación de tablas Markdown (off | bullets | code | block)

    Ejemplo completo:

    json5
    {  channels: {    twitch: {      enabled: true,      username: "openclaw",      accessToken: "oauth:abc123...",      clientId: "xyz789...",      channel: "yourchannel",      clientSecret: "secret123...",      refreshToken: "refresh456...",      allowFrom: ["123456789"],      accounts: {        second: {          username: "mybot",          accessToken: "oauth:def456...",          clientId: "uvw012...",          channel: "your_channel",          enabled: true,          expiresIn: 14400,          obtainmentTimestamp: 1706092800000,          allowedRoles: ["moderator"],        },      },    },  },}

    Acciones de herramientas

    El agente puede enviar mensajes de Twitch mediante la acción send de la herramienta de mensajes:

    json5
    {  channel: "twitch",  action: "send",  to: "#mychannel",  message: "Hello Twitch!",}

    to es opcional y usa de forma predeterminada el channel configurado para la cuenta.

    Seguridad y operaciones

    • Trate los tokens como contraseñas: nunca confirme tokens en git.
    • Use la renovación automática del token para bots que se ejecuten durante mucho tiempo.
    • Use listas de ID de usuario permitidos en lugar de nombres de usuario para controlar el acceso.
    • Supervise los registros para consultar los eventos de renovación del token y el estado de la conexión.
    • Limite al mínimo los ámbitos de los tokens: solicite únicamente chat:read y chat:write.
    • Si no logra avanzar: reinicie el Gateway después de confirmar que ningún otro proceso controle la sesión.

    Límites

    • 500 caracteres por mensaje; las respuestas más largas se dividen respetando los límites entre palabras.
    • Markdown se elimina antes del envío (el chat de Twitch usa texto sin formato; los saltos de línea se convierten en espacios).
    • OpenClaw no añade limitación de frecuencia propia; el cliente de chat Twurple gestiona los límites de frecuencia de Twitch.

    Contenido relacionado

    Was this useful?
    On this page

    On this page