Twitch

Soporte de chat de Twitch mediante conexión IRC. OpenClaw se conecta como usuario de Twitch (cuenta de bot) para recibir y enviar mensajes en los canales.

Complemento incluido

Note

Twitch se distribuye como un complemento incluido en las versiones actuales de OpenClaw, por lo que las compilaciones empaquetadas normales no necesitan una instalación separada.

Si está en una versión antigua o una instalación personalizada que excluye Twitch, instale el paquete npm directamente:

registro npmCopia local

bash openclaw plugins install @openclaw/twitch

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

Use el paquete básico para seguir la etiqueta oficial de lanzamiento actual. Fije una versión exacta solo cuando necesite una instalación reproducible.

Detalles: Plugins

Configuración rápida (principiante)

1. Asegurarse de que el complemento esté disponible

   Las versiones empaquetadas actuales de OpenClaw ya lo incluyen. Las instalaciones antiguas/personalizadas pueden añadirlo manualmente con los comandos anteriores.

2. Crear una cuenta de bot de Twitch

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

3. Generar credenciales

   Use Twitch Token Generator:

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

4. 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.

5. Configurar el token

   • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (solo cuenta predeterminada)
   • O configuración: channels.twitch.accessToken

   Si ambos están configurados, la configuración tiene prioridad (la alternativa de env es solo para la cuenta predeterminada).

6. Iniciar la puerta de enlace

   Inicie la puerta de enlace con el canal configurado.

Warning

Añada control de acceso (

allowFrom

o

allowedRoles

) para evitar que usuarios no autorizados activen el bot.

requireMention

es por defecto

true

.

Configuración mínima:

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

Qué es

• Un canal de Twitch propiedad de la Gateway.
• Enrutamiento determinista: las respuestas siempre vuelven a Twitch.
• Cada cuenta se asigna a una clave de sesión aislada agent:<agentId>:twitch:<accountName>.
• username es la cuenta del bot (quién se autentica), channel es a qué sala de chat unirse.

Configuración (detallada)

Generar credenciales

Use Twitch Token Generator:

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

Note

No es necesario registrar la aplicación manualmente. Los tokens caducan después de varias horas.

Configurar el bot

Variable de entorno (solo cuenta predeterminada)Configuración

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

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

Si se configuran tanto las variables de entorno como el archivo de configuración, la configuración tiene prioridad.

Control de acceso (recomendado)

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

Prefiera allowFrom para una lista de permitidos estricta. Use allowedRoles en su lugar si desea un control de acceso basado en roles.

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

Note

¿Por qué ID de usuario? Los nombres de usuario pueden cambiar, lo que permite la suplantación. Los ID de usuario son permanentes.

Encuentre su ID de usuario de Twitch: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (Convierta su nombre de usuario de Twitch a ID)

Actualización de token (opcional)

Los tokens de Twitch Token Generator no se pueden actualizar automáticamente; regenérelos cuando caduquen.

Para la actualización automática de tokens, cree su propia aplicación de Twitch en Twitch Developer Console y agréguela a la configuración:

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

El bot actualiza automáticamente los tokens antes de que caduquen y registra los eventos de actualización.

Soporte multicuenta

Use channels.twitch.accounts con tokens por cuenta. Consulte Configuration para ver el patrón compartido.

Ejemplo (una cuenta de bot en dos canales):

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

Note

Cada cuenta necesita su propio token (un token por canal).

Control de acceso

Lista de permitidos de ID de usuario (más segura)Basado en rolesDesactivar requisito de @mención

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

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

allowFrom es una lista de permitidos estricta. Cuando se establece, solo se permiten esos IDs de usuario. Si deseas un acceso basado en roles, deja allowFrom sin establecer y configura allowedRoles en su lugar.

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

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

Solución de problemas

Primero, ejecuta los comandos de diagnóstico:

openclaw doctor
openclaw channels status --probe

El bot no responde a los mensajes

• Verificar el control de acceso: Asegúrate de que tu ID de usuario esté en allowFrom, o elimina temporalmente allowFrom y establece allowedRoles: ["all"] para probar.
• Verificar que el bot esté en el canal: El bot debe unirse al canal especificado en channel.

Problemas con el token

“Fallo al conectar” o errores de autenticación:

• Verifica que accessToken sea el valor del token de acceso OAuth (generalmente comienza con el prefijo oauth:)
• Verifica que el token tenga los alcances chat:read y chat:write
• Si usas la actualización del token, verifica que clientSecret y refreshToken estén establecidos

La actualización del token no funciona

Revisa los registros en busca de eventos de actualización:

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

Si ves “token refresh disabled (no refresh token)”:

• Asegúrate de que se proporcione clientSecret
• Asegúrate de que se proporcione refreshToken

Configuración

Configuración de cuenta

Nombre de usuario del bot. Token de acceso OAuth con `chat:read` y `chat:write`. ID de cliente de Twitch (del generador de tokens o tu aplicación). Canal al que unirse. Habilitar esta cuenta. Opcional: para la actualización automática del token. Opcional: para la actualización automática del token. Expiración del token en segundos. Marca de tiempo de obtención del token. Lista de permitidos de ID de usuario. Control de acceso basado en roles. Requerir mención (@).

Opciones del proveedor

• channels.twitch.enabled - Habilitar/deshabilitar el inicio del canal
• channels.twitch.username - Nombre de usuario del bot (config simplificada de una sola cuenta)
• channels.twitch.accessToken - Token de acceso OAuth (config simplificada de una sola cuenta)
• channels.twitch.clientId - ID de cliente de Twitch (config simplificada de una sola cuenta)
• channels.twitch.channel - Canal al que unirse (config simplificada de una sola cuenta)
• channels.twitch.accounts.<accountName> - Configuración multicuenta (todos los campos de cuenta anteriores)

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

Acciones de herramienta

El agente puede llamar a twitch con la acción:

• send - Enviar un mensaje a un canal

Ejemplo:

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

Seguridad y operaciones

• Trate los tokens como contraseñas — Nunca confíe tokens a git.
• Use la actualización automática de tokens para bots de larga duración.
• Use listas de permitidos de ID de usuario en lugar de nombres de usuario para el control de acceso.
• Monitoree los registros para ver eventos de actualización de tokens y el estado de la conexión.
• Limite el alcance de los tokens al mínimo — Solicite solo chat:read y chat:write.
• Si se bloquea: Reinicie la puerta de enlace después de confirmar que ningún otro proceso es dueño de la sesión.

Límites

• 500 caracteres por mensaje (divididos automáticamente en los límites de las palabras).
• Se elimina el Markdown antes de dividir.
• Sin límite de velocidad (usa los límites de velocidad integrados de Twitch).

Relacionado

• Enrutamiento de canales — enrutamiento de sesión para mensajes
• Descripción general de canales — todos los canales compatibles
• Grupos — comportamiento del chat de grupo y restricción de menciones
• Emparejamiento — autenticación de mensajes directos y flujo de emparejamiento
• Seguridad — modelo de acceso y endurecimiento