Conecta OpenClaw a Twitch: Configuración rápida en 5 minutos

¿Alguna vez has intentado conectar un bot a Twitch y te has perdido entre tokens de OAuth y configuraciones de IRC? Es frustrante cuando solo quieres que tu bot responda mensajes y termine funcionando como un dolor de cabeza técnico. OpenClaw simplifica esto para que puedas integrar tu bot en el chat de Twitch sin complicaciones innecesarias.

Twitch (plugin)

Soporte para el chat de Twitch a través de una conexión IRC. OpenClaw se conecta como un usuario de Twitch (cuenta de bot) para recibir y enviar mensajes en los canales.

Plugin requerido

Twitch se distribuye como un plugin y no viene incluido en la instalación core.

Instala a través de la CLI (npm registry):

openclaw plugins install @openclaw/twitch

Instalación local (cuando ejecutas desde un repositorio git):

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

Detalles: Plugins

Configuración rápida (principiantes)

1. Crea una cuenta de Twitch dedicada para el bot (o usa una cuenta existente).
2. Genera credenciales: Twitch Token Generator
   • Selecciona Bot Token
   • Verifica que los scopes chat:read y chat:write estén seleccionados
   • Copia el Client ID y el Access Token
3. Busca tu ID de usuario de Twitch: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. Configura el token:
   • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (solo para la cuenta por defecto)
   • O en config: channels.twitch.accessToken
   • Si ambos están configurados, la config tiene prioridad (el fallback de env es solo para la cuenta por defecto).
5. Inicia el Gateway.

⚠️ Importante: Añade control de acceso (allowFrom o allowedRoles) para evitar que usuarios no autorizados activen el bot. requireMention tiene el valor true por defecto.

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 esto

• Un canal de Twitch que pertenece al Gateway.
• Routing determinista: las respuestas siempre vuelven a Twitch.
• Cada cuenta se mapea a una session key aislada agent:<agentId>:twitch:<accountName>.
• username es la cuenta del bot (quien se autentica), channel es la sala de chat a la que se une.

Configuración (detallada)

Generar credenciales

Usa Twitch Token Generator:

• Selecciona Bot Token
• Verifica que los scopes chat:read y chat:write estén seleccionados
• Copia el Client ID y el Access Token

No necesitas registrar la aplicación manualmente. Los tokens expiran después de varias horas.

Configurar el bot

Variable de entorno (solo cuenta por defecto):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

O mediante configuración:

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

Si configuras tanto la variable de entorno como la configuración, la configuración tiene prioridad.

Control de acceso (recomendado)

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

Te recomiendo usar allowFrom para una lista de permitidos estricta. Usa allowedRoles si prefieres un acceso basado en roles.

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

¿Por qué usar IDs de usuario? Los nombres de usuario pueden cambiar, lo que permitiría la suplantación de identidad. Los IDs de usuario son permanentes.

Busca tu ID de usuario de Twitch: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (Convierte tu nombre de usuario de Twitch a ID).

Refresco de tokens (opcional)

Los tokens de Twitch Token Generator no se pueden refrescar automáticamente; debes regenerarlos cuando expiren.

Para el refresco automático de tokens, crea tu propia aplicación de Twitch en el Twitch Developer Console y añádela a la configuración:

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

El bot refresca automáticamente los tokens antes de que expiren y registra los eventos de refresco.

Soporte para múltiples cuentas

Usa channels.twitch.accounts con tokens por cuenta. Consulta gateway/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",
        },
      },
    },
  },
}

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

Control de acceso

Restricciones basadas en roles

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

Allowlist por User ID (más seguro)

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

Acceso basado en roles (alternativa)

allowFrom es una lista de permitidos estricta. Cuando se configura, solo se permiten esos IDs de usuario. Si quieres acceso basado en roles, deja allowFrom sin configurar y define allowedRoles en su lugar:

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

Desactivar requisito de @mención

Por defecto, requireMention es true. Para desactivarlo 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

Revisa el control de acceso: Asegúrate de que tu ID de usuario esté en allowFrom, o elimina temporalmente allowFrom y configura allowedRoles: ["all"] para probar.

Verifica que el bot esté en el canal: El bot debe unirse al canal especificado en channel.

Problemas con el token

Errores de “Failed to connect” o de autenticación:

• Verifica que accessToken sea el valor del OAuth access token (normalmente empieza con el prefijo oauth:)
• Comprueba que el token tenga los scopes chat:read y chat:write
• Si usas el refresco de tokens, verifica que clientSecret y refreshToken estén configurados

El refresco de tokens no funciona

Revisa los logs para ver eventos de refresco:

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 proporcionar el clientSecret
• Asegúrate de proporcionar el refreshToken

Configuración (Config)

Configuración de cuenta:

• username - Nombre de usuario del bot
• accessToken - OAuth access token con chat:read y chat:write
• clientId - Twitch Client ID (del Token Generator o de tu app)
• channel - Canal al que unirse (requerido)
• enabled - Habilitar esta cuenta (por defecto: true)
• clientSecret - Opcional: Para refresco automático de tokens
• refreshToken - Opcional: Para refresco automático de tokens
• expiresIn - Expiración del token en segundos
• obtainmentTimestamp - Timestamp de obtención del token
• allowFrom - Lista de permitidos de IDs de usuario
• allowedRoles - Control de acceso basado en roles ("moderator" | "owner" | "vip" | "subscriber" | "all")
• requireMention - Requiere @mención (por defecto: true)

Opciones del proveedor:

• channels.twitch.enabled - Habilitar/deshabilitar el inicio del canal
• channels.twitch.username - Nombre de usuario del bot (configuración simplificada de cuenta única)
• channels.twitch.accessToken - OAuth access token (configuración simplificada de cuenta única)
• channels.twitch.clientId - Twitch Client ID (configuración simplificada de cuenta única)
• channels.twitch.channel - Canal al que unirse (configuración simplificada de cuenta única)
• channels.twitch.accounts.<accountName> - Configuración multi-cuenta (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 herramientas

El agent 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

• Trata los tokens como contraseñas - Nunca subas tokens a git.
• Usa el refresco automático de tokens para bots que se ejecuten por largo tiempo.
• Usa listas de permitidos por ID de usuario en lugar de nombres de usuario para el control de acceso.
• Monitorea los logs para ver eventos de refresco de tokens y el estado de la conexión.
• Limita el alcance de los tokens - Solo solicita chat:read y chat:write.
• Si te bloqueas: Reinicia el Gateway tras confirmar que ningún otro proceso es dueño de la sesión.

Límites

• 500 caracteres por mensaje (se divide automáticamente en fragmentos por palabras).
• El Markdown se elimina antes de fragmentar el mensaje.
• Sin rate limiting propio (utiliza los límites de velocidad integrados de Twitch).

Relacionado

• Channels Overview — todos los canales soportados
• Pairing — autenticación por DM y flujo de emparejamiento
• Groups — comportamiento en chats grupales y filtrado por mención
• Channel Routing — enrutamiento de sesiones para mensajes
• Security — modelo de acceso y endurecimiento de seguridad

Siguientes pasos

• Configura tu primer bot siguiendo la Guía de Configuración.
• Explora cómo gestionar múltiples plataformas en la sección de Canales.

AI Setup Assistant