Connect OpenClaw to Twitch: Setup Guide

Ever tried to get an AI bot into your Twitch chat only to realize that managing OAuth tokens and preventing random users from spamming your API is a total headache? You just want the bot to show up, listen to commands, and talk back without a complex setup.

OpenClaw handles this through a dedicated plugin that connects via IRC. It’s straightforward to set up, but you’ll want to pay attention to the access control settings so you don’t end up with unexpected bills or a chaotic chat.

Plugin required

Twitch ships as a plugin and is not bundled with the core install.

Install via CLI (npm registry):

openclaw plugins install @openclaw/twitch

Local checkout (when running from a git repo):

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

Details: Plugins

Quick setup (beginner)

1. Create a dedicated Twitch account for the bot (or use an existing account).
2. Generate credentials: Twitch Token Generator
   • Select Bot Token
   • Verify scopes chat:read and chat:write are selected
   • Copy the Client ID and Access Token
3. Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. Configure the token:
   • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (default account only)
   • Or config: channels.twitch.accessToken
   • If both are set, config takes precedence (env fallback is default-account only).
5. Start the gateway.

⚠️ Important: Add access control (allowFrom or allowedRoles) to prevent unauthorized users from triggering the bot. requireMention defaults to true.

Minimal config:

{
  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/
    },
  },
}

What it is

• A Twitch channel owned by the Gateway.
• Deterministic routing: replies always go back to Twitch.
• Each account maps to an isolated session key agent:<agentId>:twitch:<accountName>.
• username is the bot’s account (who authenticates), channel is which chat room to join.

Setup (detailed)

Generate credentials

Use Twitch Token Generator:

• Select Bot Token
• Verify scopes chat:read and chat:write are selected
• Copy the Client ID and Access Token

No manual app registration needed. Tokens expire after several hours.

Configure the bot

Env var (default account only):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Or config:

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

If both env and config are set, config takes precedence.

Access control (recommended)

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

Prefer allowFrom for a hard allowlist. Use allowedRoles instead if you want role-based access.

Available roles: "moderator", "owner", "vip", "subscriber", "all".

Why user IDs? Usernames can change, allowing impersonation. User IDs are permanent.

Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (Convert your Twitch username to ID)

Token refresh (optional)

Tokens from Twitch Token Generator cannot be automatically refreshed - regenerate when expired.

For automatic token refresh, create your own Twitch application at Twitch Developer Console and add to config:

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

The bot automatically refreshes tokens before expiration and logs refresh events.

Multi-account support

Use channels.twitch.accounts with per-account tokens. See gateway/configuration for the shared pattern.

Example (one bot account in two channels):

{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "vevisk",
        },
        channel2: {
          username: "openclaw",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel",
        },
      },
    },
  },
}

Note: Each account needs its own token (one token per channel).

Access control

Role-based restrictions

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

Allowlist by User ID (most secure)

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

Role-based access (alternative)

allowFrom is a hard allowlist. When set, only those user IDs are allowed. If you want role-based access, leave allowFrom unset and configure allowedRoles instead:

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

Disable @mention requirement

By default, requireMention is true. To disable and respond to all messages:

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

Troubleshooting

First, run diagnostic commands:

openclaw doctor
openclaw channels status --probe

Bot does not respond to messages

Check access control: Ensure your user ID is in allowFrom, or temporarily remove allowFrom and set allowedRoles: ["all"] to test.

Check the bot is in the channel: The bot must join the channel specified in channel.

Token issues

“Failed to connect” or authentication errors:

• Verify accessToken is the OAuth access token value (typically starts with oauth: prefix)
• Check token has chat:read and chat:write scopes
• If using token refresh, verify clientSecret and refreshToken are set

Token refresh not working

Check logs for refresh events:

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

If you see “token refresh disabled (no refresh token)”:

• Ensure clientSecret is provided
• Ensure refreshToken is provided

Config

Account config:

• username - Bot username
• accessToken - OAuth access token with chat:read and chat:write
• clientId - Twitch Client ID (from Token Generator or your app)
• channel - Channel to join (required)
• enabled - Enable this account (default: true)
• clientSecret - Optional: For automatic token refresh
• refreshToken - Optional: For automatic token refresh
• expiresIn - Token expiry in seconds
• obtainmentTimestamp - Token obtained timestamp
• allowFrom - User ID allowlist
• allowedRoles - Role-based access control ("moderator" | "owner" | "vip" | "subscriber" | "all")
• requireMention - Require @mention (default: true)

Provider options:

• channels.twitch.enabled - Enable/disable channel startup
• channels.twitch.username - Bot username (simplified single-account config)
• channels.twitch.accessToken - OAuth access token (simplified single-account config)
• channels.twitch.clientId - Twitch Client ID (simplified single-account config)
• channels.twitch.channel - Channel to join (simplified single-account config)
• channels.twitch.accounts.<accountName> - Multi-account config (all account fields above)

Full example:

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

Tool actions

The agent can call twitch with action:

• send - Send a message to a channel

Example:

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

Safety & ops

• Treat tokens like passwords - Never commit tokens to git
• Use automatic token refresh for long-running bots
• Use user ID allowlists instead of usernames for access control
• Monitor logs for token refresh events and connection status
• Scope tokens minimally - Only request chat:read and chat:write
• If stuck: Restart the gateway after confirming no other process owns the session

Limits

• 500 characters per message (auto-chunked at word boundaries)
• Markdown is stripped before chunking
• No rate limiting (uses Twitch’s built-in rate limits)

Related

• Channels Overview — all supported channels
• Pairing — DM authentication and pairing flow
• Groups — group chat behavior and mention gating
• Channel Routing — session routing for messages
• Security — access model and hardening

Next steps

Ready to get your bot live? If you run into any snags with the OAuth flow or permissions, check out the assistant below.

AI Setup Assistant