docs/channels/twitch.md
Twitch chat support via IRC connection. OpenClaw connects as a Twitch user (bot account) to receive and send messages in channels.
If you are on an older build or a custom install that excludes Twitch, install the npm package directly:
<Tabs> <Tab title="npm registry"> ```bash openclaw plugins install @openclaw/twitch ``` </Tab> <Tab title="Local checkout"> ```bash openclaw plugins install ./path/to/local/twitch-plugin ``` </Tab> </Tabs>Use the bare package to follow the current official release tag. Pin an exact version only when you need a reproducible install.
Details: Plugins
- Select **Bot Token**
- Verify scopes `chat:read` and `chat:write` are selected
- Copy the **Client ID** and **Access Token**
If both are set, config takes precedence (env fallback is default-account only).
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/
},
},
}
agent:<agentId>:twitch:<accountName>.username is the bot's account (who authenticates), channel is which chat room to join.chat:read and chat:write are selectedIf both env and config are set, config takes precedence.
{
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".
Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (Convert your Twitch username to ID) </Note>
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.
Use channels.twitch.accounts with per-account tokens. See 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",
},
},
},
},
}
`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.
```json5
{
channels: {
twitch: {
accounts: {
default: {
requireMention: false,
},
},
},
},
}
```
First, run diagnostic commands:
openclaw doctor
openclaw channels status --probe
- 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
```
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
channels.twitch.enabled - Enable/disable channel startupchannels.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"],
},
},
},
},
}
The agent can call twitch with action:
send - Send a message to a channelExample:
{
action: "twitch",
params: {
message: "Hello Twitch!",
to: "#mychannel",
},
}
chat:read and chat:write.