Canal Twitch do OpenClaw
Mensagens
Fácil
Conecte o OpenClaw ao chat da Twitch via IRC, permitindo que seu assistente de IA interaja com os espectadores em tempo real. Instale o plugin da Twitch, configure um OAuth token com escopos de chat, e seu bot poderá entrar em canais, responder a menções e gerenciar conversas com controle de acesso baseado em cargos.
Info rápida
DificuldadeFácil
CategoriaMensagens
Recursos suportados2 / 6
Twitch Recursos suportados
Mensagens de texto
Suportado
Mídia e arquivos
Não suportado
Reações
Não suportado
Threads
Não suportado
Mensagens de voz
Não suportado
Chat em grupo
Suportado
Twitch Pré-requisitos
- Uma conta Twitch para usar como identidade do bot
- Um OAuth Access Token com escopos chat:read e chat:write
- Um Client ID do Twitch Developer Console
- OpenClaw Gateway instalado e em execução
- O plugin da Twitch instalado via 'openclaw plugins install @openclaw/twitch'
Twitch Configuração rápida
1
Instalar o plugin da Twitch
Execute 'openclaw plugins install @openclaw/twitch' para adicionar suporte à Twitch. Alternativamente, instale a partir de um caminho local com 'openclaw plugins install ./extensions/twitch'.
2
Obter seu OAuth token e Client ID
Acesse twitchtokengenerator.com e selecione 'Bot Token' com escopos chat:read e chat:write. Copie o access token. Também obtenha seu Client ID no Twitch Developer Console (dev.twitch.tv/console).
3
Configurar e iniciar
Adicione a configuração do canal Twitch em ~/.openclaw/openclaw.json com seu username, accessToken, clientId e canal de destino. Inicie o Gateway com 'openclaw start' e envie uma mensagem mencionando o bot no canal da Twitch para verificar.
Twitch Exemplo de configuração
config.json
{
"channels": {
"twitch": {
"enabled": true,
"username": "mybotname",
"accessToken": "oauth:abc123...",
"clientId": "your-client-id",
"channel": "targetchannel",
"allowFrom": ["123456789"]
}
}
}Twitch Documentação Detalhada
Visão Geral da Arquitetura
O OpenClaw se conecta ao chat da Twitch usando o protocolo IRC. O Gateway se autentica com seu OAuth token, entra no canal especificado e fica aguardando mensagens.
Quando um espectador envia uma mensagem que aciona o bot (via @menção por padrão), o Gateway a encaminha para seu agente de IA. A resposta é enviada de volta ao mesmo canal da Twitch, automaticamente dividida em blocos de 500 caracteres por mensagem para cumprir os limites da Twitch.
Cada conta é mapeada para uma chave de sessão única (agent:<agentId>:twitch:<accountName>), de modo que múltiplas contas podem operar de forma independente sob o mesmo Gateway. O Markdown é automaticamente removido antes do envio, pois o chat da Twitch não o renderiza.
As respostas são roteadas de forma determinística de volta ao canal da Twitch de onde se originaram.
Mensagens que excedem 500 caracteres são automaticamente divididas nos limites de palavras.
Obtendo Suas Credenciais
Você precisa de três credenciais para se conectar: um OAuth access token, um Client ID e o nome de usuário do bot.
1. Acesse twitchtokengenerator.com e selecione 'Bot Token'.
2. Autorize o token com escopos chat:read e chat:write.
3. Copie o access token gerado (começa com 'oauth:').
4. Para o Client ID, acesse o Twitch Developer Console em dev.twitch.tv/console, registre uma aplicação e copie o Client ID dela.
O access token também pode ser fornecido via variável de ambiente OPENCLAW_TWITCH_ACCESS_TOKEN. Se tanto a variável de ambiente quanto o valor no arquivo de configuração estiverem definidos, o arquivo de configuração tem precedência.
terminal
# Environment variable (default account only)
export OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...Nunca faça commit do seu access token no controle de versão. Use variáveis de ambiente ou um gerenciador de segredos.
Tokens do twitchtokengenerator.com expiram após várias horas. Configure atualização automática para bots de longa execução.
Atualização Automática de Token
Tokens do Twitch Token Generator expiram após algumas horas. Para bots em produção, configure a atualização automática de token para evitar interrupções.
1. Registre uma aplicação no Twitch Developer Console (dev.twitch.tv/console).
2. Anote o Client Secret e use o fluxo OAuth Authorization Code para obter um refresh token.
3. Adicione clientSecret e refreshToken à configuração da sua conta.
O bot atualizará automaticamente o token antes de expirar e registrará os eventos de atualização para monitoramento.
openclaw.json
{
"channels": {
"twitch": {
"accessToken": "oauth:abc123...",
"clientId": "your-client-id",
"clientSecret": "your-client-secret",
"refreshToken": "your-refresh-token"
}
}
}Sem atualização automática, você precisará substituir manualmente o token cada vez que ele expirar.
Controle de Acesso com IDs de Usuário
Nomes de usuário da Twitch podem ser alterados, o que cria um risco de falsificação de identidade. O OpenClaw recomenda fortemente o uso de IDs numéricos de usuário para controle de acesso em vez de nomes de usuário.
O campo allowFrom aceita um array de IDs permanentes de usuário da Twitch. Apenas usuários cujos IDs estão nessa lista podem interagir com o bot. Todos os outros são silenciosamente ignorados.
Você pode consultar o ID numérico de um usuário usando a API da Twitch ou ferramentas de terceiros como twitchinsights.net.
openclaw.json
{
"channels": {
"twitch": {
"allowFrom": ["123456789", "987654321"]
}
}
}IDs de usuário são permanentes e imunes a mudanças de nome. Sempre prefira IDs em vez de nomes de usuário por questão de segurança.
Controle de Acesso Baseado em Cargos
Em vez de (ou além de) uma lista de permissão explícita por ID de usuário, você pode restringir o acesso por cargos do chat da Twitch. O campo allowedRoles aceita um array de nomes de cargos.
Cargos disponíveis:
• moderator — Moderadores do canal
• owner — O dono do canal (broadcaster)
• vip — Usuários VIP
• subscriber — Assinantes do canal
• all — Todos no canal (use com cautela)
Quando allowedRoles está definido, apenas usuários com pelo menos um cargo correspondente podem interagir com o bot.
openclaw.json
{
"channels": {
"twitch": {
"allowedRoles": ["moderator", "vip"]
}
}
}Definir allowedRoles como ['all'] permite que todos os espectadores interajam com o bot, o que pode consumir uma quantidade significativa de cota de IA em canais movimentados.
Requisito de Menção
Por padrão, o bot só responde quando explicitamente @mencionado no chat (requireMention: true). Isso evita que o bot responda a todas as mensagens em um canal movimentado.
Você pode desativar esse comportamento definindo requireMention como false, o que faz o bot responder a todas as mensagens de usuários permitidos. Isso é útil para canais dedicados ao bot ou transmissões com pouco tráfego.
openclaw.json
{
"channels": {
"twitch": {
"requireMention": false
}
}
}Mantenha requireMention ativado em canais movimentados para evitar sobrecarregar o bot com todas as mensagens do chat.
Configuração Multi-Conta
O OpenClaw suporta a execução de múltiplas contas de bot da Twitch simultaneamente. Cada conta requer seu próprio OAuth token e é mapeada para um único canal.
Use o padrão accounts.<name> para configurar múltiplas contas. Cada conta pode ter controle de acesso independente, requisitos de menção e configurações de atualização de token.
openclaw.json
{
"channels": {
"twitch": {
"accounts": {
"gaming-bot": {
"username": "gamingbot",
"accessToken": "oauth:token1...",
"clientId": "client-id-1",
"channel": "gamingchannel",
"allowedRoles": ["subscriber"]
},
"mod-bot": {
"username": "modbot",
"accessToken": "oauth:token2...",
"clientId": "client-id-2",
"channel": "modchannel",
"allowFrom": ["111222333"]
}
}
}
}
}Ações de Ferramentas do Agente
Agentes de IA podem enviar mensagens proativamente para canais da Twitch usando a ação de ferramenta twitch. Isso permite que agentes enviem notificações, alertas ou mensagens agendadas sem um acionamento do usuário.
A ação requer uma mensagem e um canal de destino (prefixado com #).
agent-action.json
{
"action": "twitch",
"params": {
"message": "Hello Twitch!",
"to": "#mychannel"
}
}Ações de ferramentas respeitam os mesmos limites de taxa que mensagens regulares do chat.
Limites de Taxa e Restrições de Mensagens
A Twitch aplica limites de taxa rígidos em mensagens de chat. O OpenClaw utiliza os limites de taxa nativos da Twitch — não há camada adicional de limitação.
Contas padrão (não verificadas):
• 20 mensagens por 30 segundos (sem mod/VIP)
• 100 mensagens por 30 segundos (mod/VIP/broadcaster)
Contas de bot verificadas:
• 7.500 mensagens por 30 segundos
Todas as contas são limitadas a 1 mensagem por segundo por canal. Mensagens que excedem o limite são silenciosamente descartadas pela Twitch.
O comprimento máximo de mensagem é 500 caracteres. Respostas mais longas são automaticamente divididas nos limites de palavras.
Se o seu bot exceder os limites de taxa, a Twitch descarta silenciosamente as mensagens sem nenhum erro. Monitore a atividade do seu bot em canais movimentados.
Twitch Referência de Configuração
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Ativar ou desativar o canal Twitch |
| username | string | "" | Nome da conta Twitch usada pelo bot |
| accessToken | string | "" | OAuth token com escopos chat:read e chat:write (deve começar com 'oauth:') |
| clientId | string | "" | Client ID do Twitch Developer Console |
| channel | string | "" | Canal Twitch de destino para entrar (obrigatório) |
| clientSecret | string | "" | Client secret para atualização automática de token |
| refreshToken | string | "" | Refresh token para renovação automática de token |
| expiresIn | number | — | Duração de expiração do token em segundos |
| obtainmentTimestamp | number | — | Timestamp (ms) de quando o token atual foi obtido |
| allowFrom | string[] | [] | Lista de permissão de IDs de usuário da Twitch para restrição de acesso rígida |
| allowedRoles | string[] | [] | Controle de acesso baseado em cargos (moderator, owner, vip, subscriber, all) |
| requireMention | boolean | true | Se o bot requer uma @menção para responder |
| accounts.<id>.username | string | "" | Nome de usuário do bot para uma conta específica no modo multi-conta |
| accounts.<id>.accessToken | string | "" | OAuth token para uma conta específica |
| accounts.<id>.channel | string | "" | Canal de destino para uma conta específica |
enabled
Type: booleanDefault: true
Ativar ou desativar o canal Twitch
username
Type: stringDefault: ""
Nome da conta Twitch usada pelo bot
accessToken
Type: stringDefault: ""
OAuth token com escopos chat:read e chat:write (deve começar com 'oauth:')
clientId
Type: stringDefault: ""
Client ID do Twitch Developer Console
channel
Type: stringDefault: ""
Canal Twitch de destino para entrar (obrigatório)
clientSecret
Type: stringDefault: ""
Client secret para atualização automática de token
refreshToken
Type: stringDefault: ""
Refresh token para renovação automática de token
expiresIn
Type: numberDefault: —
Duração de expiração do token em segundos
obtainmentTimestamp
Type: numberDefault: —
Timestamp (ms) de quando o token atual foi obtido
allowFrom
Type: string[]Default: []
Lista de permissão de IDs de usuário da Twitch para restrição de acesso rígida
allowedRoles
Type: string[]Default: []
Controle de acesso baseado em cargos (moderator, owner, vip, subscriber, all)
requireMention
Type: booleanDefault: true
Se o bot requer uma @menção para responder
accounts.<id>.username
Type: stringDefault: ""
Nome de usuário do bot para uma conta específica no modo multi-conta
accounts.<id>.accessToken
Type: stringDefault: ""
OAuth token para uma conta específica
accounts.<id>.channel
Type: stringDefault: ""
Canal de destino para uma conta específica
Twitch Perguntas Frequentes
Twitch Solução de Problemas
Bot não responde — não responde às mensagens
A lista allowFrom pode não incluir seu ID de usuário, ou o bot não está detectando a @menção.
Verifique se seu ID de usuário da Twitch (não o nome de usuário) está no array allowFrom. Para testes, tente definir allowedRoles como ['all']. Verifique se você está @mencionando o bot corretamente se requireMention estiver como true.
Falha na autenticação ao iniciar
O OAuth token é inválido, expirou ou não possui os escopos necessários.
Certifique-se de que o token começa com 'oauth:' e possui os escopos chat:read e chat:write. Gere um novo token em twitchtokengenerator.com. Verifique os logs do Gateway para mensagens de erro específicas.
A atualização de token não está funcionando
O clientSecret ou refreshToken está ausente ou incorreto.
Certifique-se de que tanto clientSecret quanto refreshToken estão fornecidos na configuração. O client secret deve corresponder à aplicação registrada em dev.twitch.tv/console. Verifique os logs para detalhes de erro na atualização de token.
Mensagens estão sendo silenciosamente descartadas
O bot está excedendo os limites de taxa da Twitch.
Reduza a frequência de mensagens. Contas padrão são limitadas a 20 mensagens por 30 segundos (100 para mods). Considere solicitar o status de bot verificado para limites mais altos. Verifique se o bot está gerando respostas muito longas que resultam em muitas mensagens fragmentadas.
Bot conecta mas não entra no canal
O nome do canal pode estar incorreto ou a conta foi banida do canal.
Verifique se o nome do canal está correto (minúsculo, sem o prefixo #). Verifique os logs do Gateway para erros de JOIN. Certifique-se de que a conta do bot não está banida ou em timeout no canal de destino.