Use this file to discover all available pages before exploring further.

Twitch

Twitch chat support via IRC connection. OpenClaw connects as a Twitch user (bot account) to receive and send messages in channels.

Bundled plugin

note

Twitch ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.

If you are on an older build or a custom install that excludes Twitch, install a current npm package when one is published:

```bash} openclaw plugins install @openclaw/twitch ``` ```bash} openclaw plugins install ./path/to/local/twitch-plugin ```

If npm reports the OpenClaw-owned package as deprecated, use a current packaged OpenClaw build or the local checkout path until a newer npm package is published.

Details: Plugins

Quick setup (beginner)

Ensure plugin is available

Current packaged OpenClaw releases already bundle it. Older/custom installs can add it manually with the commands above.

Create a Twitch bot account

Create a dedicated Twitch account for the bot (or use an existing account).

Generate credentials

Use [Twitch Token Generator](https://twitchtokengenerator.com/):


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

Find your Twitch user ID

Use [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) to convert a username to a Twitch user ID.

Configure the token

* Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (default account only) * Or config: `channels.twitch.accessToken`


text
If both are set, config takes precedence (env fallback is default-account only).

Start the gateway

Start the gateway with the configured channel.

warning

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

Minimal config:


json5
{
  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
text
agent:<agentId>:twitch:<accountName>
.
text
username
is the bot's account (who authenticates),
text
channel
is which chat room to join.

Setup (detailed)

Generate credentials

Use Twitch Token Generator:

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

note

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

Configure the bot

```bash} OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... ``` ```json5} { 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)


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

Prefer

text

allowFrom

for a hard allowlist. Use

text

allowedRoles

instead if you want role-based access.

Available roles:

text

"moderator"

text

"owner"

text

"vip"

text

"subscriber"

text

"all"

note

**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:


json5
{
  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

text

channels.twitch.accounts

with per-account tokens. See Configuration for the shared pattern.

Example (one bot account in two channels):


json5
{
  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

```json5} { channels: { twitch: { accounts: { default: { allowFrom: ["123456789", "987654321"], }, }, }, }, } ``` ```json5} { channels: { twitch: { accounts: { default: { allowedRoles: ["moderator", "vip"], }, }, }, }, } ```


text
`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.

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


text
```json5}
{
  channels: {
    twitch: {
      accounts: {
        default: {
          requireMention: false,
        },
      },
    },
  },
}
```

Troubleshooting

First, run diagnostic commands:


bash
openclaw doctor
openclaw channels status --probe

Config

Account config

Bot username. OAuth access token with `chat:read` and `chat:write`. Twitch Client ID (from Token Generator or your app). Channel to join. Enable this account. Optional: for automatic token refresh. Optional: for automatic token refresh. Token expiry in seconds. Token obtained timestamp. User ID allowlist. Role-based access control. Require @mention.

Provider options

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

Full example:


json5
{
  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

text

twitch

with action:

text
send
- Send a message to a channel

Example:


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

Safety and 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
text
chat:read
and
text
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).

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

OpenClaw Docs

Twitch

Bundled plugin

note

Quick setup (beginner)

Ensure plugin is available

Create a Twitch bot account

Generate credentials

Find your Twitch user ID

Configure the token

Start the gateway

warning

What it is

Setup (detailed)

Generate credentials

note

Configure the bot

Access control (recommended)

note

Token refresh (optional)

Multi-account support

note

Access control

Troubleshooting

Config

Account config

Provider options

Tool actions

Safety and ops

Limits

Related