OpenClaw Manual OpenClaw

OpenClaw Twitch Channel

Messaging
Easy

Connect OpenClaw to Twitch chat via IRC, enabling your AI assistant to interact with viewers in real time. Install the Twitch plugin, configure an OAuth token with chat scopes, and your bot can join channels, respond to mentions, and manage conversations with role-based access control.

Quick Info
Difficulty Easy
Category Messaging
Features Supported 2 / 6

Twitch Supported Features

Text Messages

Supported

Media & Files

Not Supported

Reactions

Not Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Supported

Twitch Prerequisites

  • A Twitch account to use as the bot identity
  • An OAuth Access Token with chat:read and chat:write scopes
  • A Client ID from the Twitch Developer Console
  • OpenClaw Gateway installed and running
  • The Twitch plugin installed via 'openclaw plugins install @openclaw/twitch'

Twitch Quick Setup

1

Install the Twitch plugin

Run 'openclaw plugins install @openclaw/twitch' to add Twitch support. Alternatively, install from a local path with 'openclaw plugins install ./extensions/twitch'.

2

Get your OAuth token and Client ID

Visit twitchtokengenerator.com and select 'Bot Token' with chat:read and chat:write scopes. Copy the access token. Also obtain your Client ID from the Twitch Developer Console (dev.twitch.tv/console).

3

Configure and launch

Add the Twitch channel configuration to ~/.openclaw/openclaw.json with your username, accessToken, clientId, and target channel. Start the Gateway with 'openclaw start' and send a message mentioning the bot in the Twitch channel to verify.

Twitch Configuration Example

config.json 
{
  "channels": {
    "twitch": {
      "enabled": true,
      "username": "mybotname",
      "accessToken": "oauth:abc123...",
      "clientId": "your-client-id",
      "channel": "targetchannel",
      "allowFrom": ["123456789"]
    }
  }
}

Twitch Deep Dive

Architecture Overview

OpenClaw connects to Twitch chat using the IRC protocol. The Gateway authenticates with your OAuth token, joins the specified channel, and listens for messages. When a viewer sends a message that triggers the bot (via @mention by default), the Gateway forwards it to your AI agent. The response is sent back to the same Twitch channel, automatically chunked at 500 characters per message to comply with Twitch's limits. Each account maps to a unique session key (agent:<agentId>:twitch:<accountName>), so multiple accounts can operate independently under the same Gateway. Markdown is automatically stripped before sending, as Twitch chat does not render it.
Replies are deterministically routed back to the Twitch channel they originated from.
Messages exceeding 500 characters are automatically split at word boundaries.

Getting Your Credentials

You need three credentials to connect: an OAuth access token, a Client ID, and the bot's username. 1. Go to twitchtokengenerator.com and select 'Bot Token'. 2. Authorize the token with chat:read and chat:write scopes. 3. Copy the generated access token (starts with 'oauth:'). 4. For the Client ID, visit the Twitch Developer Console at dev.twitch.tv/console, register an application, and copy its Client ID. The access token can also be provided via the OPENCLAW_TWITCH_ACCESS_TOKEN environment variable. If both the environment variable and config file value are set, the config file takes precedence.
terminal 
# Environment variable (default account only)
export OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
Never commit your access token to version control. Use environment variables or a secrets manager.
Tokens from twitchtokengenerator.com expire after several hours. Set up automatic refresh for long-running bots.

Automatic Token Refresh

Tokens from the Twitch Token Generator expire after a few hours. For production bots, configure automatic token refresh to avoid downtime. 1. Register an application at the Twitch Developer Console (dev.twitch.tv/console). 2. Note the Client Secret and use the OAuth Authorization Code flow to obtain a refresh token. 3. Add clientSecret and refreshToken to your account configuration. The bot will automatically refresh the token before it expires and log refresh events for monitoring.
openclaw.json 
{
  "channels": {
    "twitch": {
      "accessToken": "oauth:abc123...",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "refreshToken": "your-refresh-token"
    }
  }
}
Without automatic refresh, you must manually replace the token each time it expires.

Access Control with User IDs

Twitch usernames can change, which creates an impersonation risk. OpenClaw strongly recommends using numeric user IDs for access control instead of usernames. The allowFrom field accepts an array of permanent Twitch user IDs. Only users whose IDs are in this list can interact with the bot. Everyone else is silently ignored. You can look up a user's numeric ID using the Twitch API or third-party tools like twitchinsights.net.
openclaw.json 
{
  "channels": {
    "twitch": {
      "allowFrom": ["123456789", "987654321"]
    }
  }
}
User IDs are permanent and immune to username changes. Always prefer IDs over usernames for security.

Role-Based Access Control

Instead of (or in addition to) an explicit user ID allowlist, you can restrict access by Twitch chat roles. The allowedRoles field accepts an array of role names. Available roles: • moderator — Channel moderators • owner — The channel broadcaster • vip — VIP users • subscriber — Channel subscribers • all — Everyone in the channel (use with caution) When allowedRoles is set, only users with at least one matching role can interact with the bot.
openclaw.json 
{
  "channels": {
    "twitch": {
      "allowedRoles": ["moderator", "vip"]
    }
  }
}
Setting allowedRoles to ['all'] lets every viewer interact with the bot, which may consume significant AI quota on busy channels.

Mention Requirement

By default, the bot only responds when explicitly @mentioned in chat (requireMention: true). This prevents the bot from responding to every message in a busy channel. You can disable this behavior by setting requireMention to false, which makes the bot respond to all messages from allowed users. This is useful for dedicated bot channels or low-traffic streams.
openclaw.json 
{
  "channels": {
    "twitch": {
      "requireMention": false
    }
  }
}
Keep requireMention enabled on busy channels to avoid overwhelming the bot with every chat message.

Multi-Account Setup

OpenClaw supports running multiple Twitch bot accounts simultaneously. Each account requires its own OAuth token and maps to a single channel. Use the accounts.<name> pattern to configure multiple accounts. Each account can have independent access control, mention requirements, and token refresh settings.
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"]
        }
      }
    }
  }
}

Agent Tool Actions

AI agents can proactively send messages to Twitch channels using the twitch tool action. This allows agents to send notifications, alerts, or scheduled messages without a user trigger. The action requires a message and a target channel (prefixed with #).
agent-action.json 
{
  "action": "twitch",
  "params": {
    "message": "Hello Twitch!",
    "to": "#mychannel"
  }
}
Tool actions respect the same rate limits as regular chat messages.

Rate Limits and Message Constraints

Twitch enforces strict rate limits on chat messages. OpenClaw uses Twitch's built-in rate limiting — there is no additional rate limiting layer. Standard (unverified) accounts: • 20 messages per 30 seconds (non-mod/VIP) • 100 messages per 30 seconds (mod/VIP/broadcaster) Verified bot accounts: • 7,500 messages per 30 seconds All accounts are limited to 1 message per second per channel. Messages exceeding the limit are silently dropped by Twitch. The maximum message length is 500 characters. Longer responses are automatically split at word boundaries.
If your bot exceeds rate limits, Twitch silently drops messages without any error. Monitor your bot's activity on busy channels.

Twitch Configuration Reference

enabled
Type: boolean Default: true

Enable or disable the Twitch channel

username
Type: string Default: ""

The Twitch account name used by the bot

accessToken
Type: string Default: ""

OAuth token with chat:read and chat:write scopes (must start with 'oauth:')

clientId
Type: string Default: ""

Client ID from the Twitch Developer Console

channel
Type: string Default: ""

Target Twitch channel to join (required)

clientSecret
Type: string Default: ""

Client secret for automatic token refresh

refreshToken
Type: string Default: ""

Refresh token for automatic token renewal

expiresIn
Type: number Default: —

Token expiry duration in seconds

obtainmentTimestamp
Type: number Default: —

Timestamp (ms) when the current token was obtained

allowFrom
Type: string[] Default: []

Twitch user ID allowlist for hard access restriction

allowedRoles
Type: string[] Default: []

Role-based access control (moderator, owner, vip, subscriber, all)

requireMention
Type: boolean Default: true

Whether the bot requires an @mention to respond

accounts.<id>.username
Type: string Default: ""

Bot username for a specific account in multi-account mode

accounts.<id>.accessToken
Type: string Default: ""

OAuth token for a specific account

accounts.<id>.channel
Type: string Default: ""

Target channel for a specific account

Twitch Frequently Asked Questions

Twitch Troubleshooting

Bot is unresponsive — does not reply to messages

The allowFrom list may not include your user ID, or the bot is not detecting the @mention.

Verify that your Twitch user ID (not username) is in the allowFrom array. For testing, try setting allowedRoles to ['all']. Check that you are @mentioning the bot correctly if requireMention is true.
Authentication failed on startup

The OAuth token is invalid, expired, or missing required scopes.

Ensure the token starts with 'oauth:' and has chat:read and chat:write scopes. Generate a fresh token at twitchtokengenerator.com. Check Gateway logs for specific error messages.
Token refresh is not working

The clientSecret or refreshToken is missing or incorrect.

Ensure both clientSecret and refreshToken are provided in the configuration. The client secret must match the application registered at dev.twitch.tv/console. Check logs for token refresh error details.
Messages are being silently dropped

The bot is exceeding Twitch's rate limits.

Reduce message frequency. Standard accounts are limited to 20 messages per 30 seconds (100 for mods). Consider applying for verified bot status for higher limits. Check if the bot is generating overly long responses that result in many chunked messages.
Bot connects but does not join the channel

The channel name may be incorrect or the account has been banned from the channel.

Verify the channel name is correct (lowercase, without the # prefix). Check Gateway logs for JOIN errors. Ensure the bot account is not banned or timed out in the target channel.
View Full Documentation Back to All Channels

Related Channels

WhatsApp

Medium

Connect OpenClaw via QR code using Baileys protocol

Setup Guide

Telegram

Easy

OpenClaw bot via Telegram grammY Bot API

Setup Guide

Discord

Easy

OpenClaw bot integration using discord.js

Setup Guide