Twitch (plugin)

Suporte a chat da Twitch via conexão IRC. O OpenClaw conecta como um usuário da Twitch (conta de bot) para receber e enviar mensagens em canais.

Plugin necessário

O Twitch é distribuído como plugin e não vem incluso na instalação padrão.

Instale via CLI (registro npm):

openclaw plugins install @openclaw/twitch

Checkout local (ao rodar a partir de um repositório git):

openclaw plugins install ./extensions/twitch

Detalhes: Plugins

Configuração rápida (iniciante)

  1. Crie uma conta dedicada na Twitch para o bot (ou use uma conta existente).
  2. Gere as credenciais: Twitch Token Generator
    • Selecione Bot Token
    • Verifique se os escopos chat:read e chat:write estão selecionados
    • Copie o Client ID e o Access Token
  3. Encontre seu user ID da Twitch: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. Configure o token:
    • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (apenas conta padrão)
    • Ou config: channels.twitch.accessToken
    • Se ambos estiverem definidos, a config tem precedência (o env é fallback apenas para a conta padrão).
  5. Inicie o gateway.

Aviso: Adicione controle de acesso (allowFrom ou allowedRoles) para impedir que usuários não autorizados acionem o bot. requireMention é true por padrão.

Configuração 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/
    },
  },
}

O que é

  • Um canal da Twitch gerenciado pelo Gateway.
  • Roteamento determinístico: respostas sempre retornam para a Twitch.
  • Cada conta é mapeada a uma chave de sessão isolada agent:<agentId>:twitch:<accountName>.
  • username é a conta do bot (quem se autentica); channel é qual sala de chat participar.

Setup (detalhado)

Gerar credenciais

Use o Twitch Token Generator:

  • Selecione Bot Token
  • Verifique se os escopos chat:read e chat:write estão selecionados
  • Copie o Client ID e o Access Token

Não é necessário registrar um app manualmente. Os tokens expiram após algumas horas.

Configurar o bot

Variável de ambiente (apenas conta padrão):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Ou config:

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

Se ambos (env e config) estiverem definidos, a config tem precedência.

Controle de acesso (recomendado)

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

Prefira allowFrom para uma lista de permitidos rígida. Use allowedRoles caso prefira controle baseado em cargo.

Cargos disponíveis: "moderator", "owner", "vip", "subscriber", "all".

Por que user IDs? Nomes de usuário podem ser alterados, permitindo personificação. User IDs são permanentes.

Encontre seu user ID da Twitch: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Converta seu nome de usuário da Twitch em ID)

Renovação de token (opcional)

Tokens do Twitch Token Generator não podem ser renovados automaticamente — gere novos quando expirarem.

Para renovação automática de tokens, crie seu próprio aplicativo na Twitch pelo Twitch Developer Console e adicione à config:

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

O bot renova os tokens automaticamente antes da expiração e registra eventos de renovação nos logs.

Suporte a múltiplas contas

Use channels.twitch.accounts com tokens por conta. Consulte gateway/configuration para o padrão compartilhado.

Exemplo (uma conta de bot em dois canais):

{
  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 conta precisa do seu próprio token (um token por canal).

Controle de acesso

Restrições baseadas em cargo

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

Lista de permitidos por User ID (mais seguro)

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

Acesso baseado em cargo (alternativa)

allowFrom é uma lista de permitidos rígida. Quando definida, apenas esses user IDs têm acesso. Se você quer controle baseado em cargo, deixe allowFrom vazio e configure allowedRoles:

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

Desabilitar requisito de @menção

Por padrão, requireMention é true. Para desabilitar e responder a todas as mensagens:

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

Solução de problemas

Primeiro, execute os comandos de diagnóstico:

openclaw doctor
openclaw channels status --probe

Bot não responde às mensagens

Verifique o controle de acesso: Certifique-se de que seu user ID está em allowFrom, ou remova temporariamente allowFrom e defina allowedRoles: ["all"] para testar.

Verifique se o bot está no canal: O bot precisa entrar no canal especificado em channel.

Problemas com token

“Failed to connect” ou erros de autenticação:

  • Verifique se accessToken é o valor do token OAuth (normalmente começa com o prefixo oauth:)
  • Confirme que o token possui os escopos chat:read e chat:write
  • Se estiver usando renovação de token, verifique se clientSecret e refreshToken estão definidos

Renovação de token não funciona

Verifique os logs para eventos de renovação:

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

Se você vir “token refresh disabled (no refresh token)”:

  • Certifique-se de que clientSecret está configurado
  • Certifique-se de que refreshToken está configurado

Config

Configuração da conta:

  • username - Nome de usuário do bot
  • accessToken - Token de acesso OAuth com chat:read e chat:write
  • clientId - Client ID da Twitch (do Token Generator ou do seu app)
  • channel - Canal para entrar (obrigatório)
  • enabled - Habilitar esta conta (padrão: true)
  • clientSecret - Opcional: para renovação automática de token
  • refreshToken - Opcional: para renovação automática de token
  • expiresIn - Expiração do token em segundos
  • obtainmentTimestamp - Timestamp de obtenção do token
  • allowFrom - Lista de permitidos por user ID
  • allowedRoles - Controle de acesso baseado em cargo ("moderator" | "owner" | "vip" | "subscriber" | "all")
  • requireMention - Exigir @menção (padrão: true)

Opções do provedor:

  • channels.twitch.enabled - Habilitar/desabilitar inicialização do canal
  • channels.twitch.username - Nome de usuário do bot (config simplificada de conta única)
  • channels.twitch.accessToken - Token de acesso OAuth (config simplificada de conta única)
  • channels.twitch.clientId - Client ID da Twitch (config simplificada de conta única)
  • channels.twitch.channel - Canal para entrar (config simplificada de conta única)
  • channels.twitch.accounts.<accountName> - Config de múltiplas contas (todos os campos de conta acima)

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

Ações de ferramenta

O agente pode chamar twitch com ação:

  • send - Enviar uma mensagem para um canal

Exemplo:

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

Segurança e operações

  • Trate tokens como senhas — nunca faça commit de tokens no git
  • Use renovação automática de token para bots de longa duração
  • Use listas de permitidos por user ID em vez de nomes de usuário para controle de acesso
  • Monitore os logs para eventos de renovação de token e status de conexão
  • Limite os escopos do token — solicite apenas chat:read e chat:write
  • Se travar: reinicie o gateway após confirmar que nenhum outro processo possui a sessão

Limites

  • 500 caracteres por mensagem (fragmentação automática em limites de palavra)
  • Markdown é removido antes da fragmentação
  • Sem rate limiting próprio (usa os limites nativos da Twitch)
arrow_back
Anterior
Tlon
Próximo
Whatsapp
arrow_forward