Twitch (plugin)

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

Plugin requerido

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

Instalar vía CLI (registro npm):

openclaw plugins install @openclaw/twitch

Checkout local (cuando se ejecuta desde un repositorio git):

openclaw plugins install ./extensions/twitch

Detalles: Plugins

Configuración rápida (principiante)

  1. Crea una cuenta dedicada de Twitch 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. Encuentra tu ID de usuario de Twitch: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. Configura el token:
    • Variable de entorno: OPENCLAW_TWITCH_ACCESS_TOKEN=... (solo cuenta predeterminada)
    • O en configuración: channels.twitch.accessToken
    • Si ambos están configurados, la configuración tiene prioridad (la variable de entorno es solo respaldo para la cuenta predeterminada).
  5. Inicia el gateway.

Advertencia: Añade control de acceso (allowFrom o allowedRoles) para evitar que usuarios no autorizados activen el bot. requireMention es true de forma predeterminada.

Configuración mínima:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Cuenta de Twitch del bot
      accessToken: "oauth:abc123...", // Token de acceso OAuth (o usa la variable OPENCLAW_TWITCH_ACCESS_TOKEN)
      clientId: "xyz789...", // Client ID del Token Generator
      channel: "vevisk", // Chat del canal de Twitch al que unirse (requerido)
      allowFrom: ["123456789"], // (recomendado) Solo tu ID de usuario de Twitch
    },
  },
}

Qué es

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

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 se necesita registro manual de la app. Los tokens expiran después de varias horas.

Configurar el bot

Variable de entorno (solo cuenta predeterminada):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

O configuración:

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

Si ambos están configurados, la configuración tiene prioridad.

Control de acceso (recomendado)

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (recomendado) Solo tu ID de usuario de Twitch
    },
  },
}

Prefiere allowFrom para una lista de acceso estricta. Usa allowedRoles en su lugar si quieres acceso basado en roles.

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

¿Por qué IDs de usuario? Los nombres de usuario pueden cambiar, permitiendo suplantación. Los IDs de usuario son permanentes.

Encuentra tu ID de usuario de Twitch: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/

Renovación de token (opcional)

Los tokens de Twitch Token Generator no se pueden renovar automáticamente - regenera cuando expiren.

Para renovación automática de tokens, crea tu propia aplicación de Twitch en la Consola de Desarrollo de Twitch y añade a la configuración:

{
  channels: {
    twitch: {
      clientSecret: "tu_client_secret",
      refreshToken: "tu_refresh_token",
    },
  },
}

El bot renueva automáticamente los tokens antes de que expiren y registra los eventos de renovación.

Soporte multi-cuenta

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

Lista de acceso por ID de usuario (más seguro)

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

Acceso basado en roles (alternativa)

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

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

Desactivar requisito de @mención

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

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

Resolución de problemas

Primero, ejecuta los comandos de diagnóstico:

openclaw doctor
openclaw channels status --probe

El bot no responde a los mensajes

Verifica el control de acceso: Asegúrate de que tu ID de usuario esté en allowFrom, o temporalmente elimina 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 de token

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

  • Verifica que accessToken sea el valor del token de acceso OAuth (normalmente comienza con el prefijo oauth:)
  • Verifica que el token tenga los scopes chat:read y chat:write
  • Si usas renovación de token, verifica que clientSecret y refreshToken estén configurados

La renovación de token no funciona

Verifica los logs por eventos de renovació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 clientSecret esté proporcionado
  • Asegúrate de que refreshToken esté proporcionado

Configuración

Configuración de cuenta:

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

Opciones del proveedor:

  • channels.twitch.enabled - Habilitar/deshabilitar inicio del canal
  • channels.twitch.username - Nombre de usuario del bot (configuración simplificada de cuenta única)
  • channels.twitch.accessToken - Token de acceso OAuth (configuración simplificada de cuenta única)
  • channels.twitch.clientId - Client ID de Twitch (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 arriba)

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 agente puede llamar a twitch con la acción:

  • send - Enviar un mensaje a un canal

Ejemplo:

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

Seguridad y operaciones

  • Trata los tokens como contraseñas - Nunca hagas commit de tokens en git
  • Usa renovación automática de tokens para bots de larga duración
  • Usa listas de acceso por ID de usuario en lugar de nombres de usuario para control de acceso
  • Monitoriza los logs por eventos de renovación de token y estado de conexión
  • Limita los scopes de los tokens - Solo solicita chat:read y chat:write
  • Si te atascas: Reinicia el gateway después de confirmar que ningún otro proceso posee la sesión

Límites

  • 500 caracteres por mensaje (auto-fragmentado en límites de palabras)
  • El Markdown se elimina antes de la fragmentación
  • Sin límite de velocidad propio (usa los límites de velocidad integrados de Twitch)
arrow_back
Anterior
Tlon
Siguiente
Whatsapp
arrow_forward