diff --git a/docs/channels/twitch.md b/docs/channels/twitch.md
index c8aabd3536e..b148363b4b4 100644
--- a/docs/channels/twitch.md
+++ b/docs/channels/twitch.md
@@ -3,50 +3,69 @@ summary: "Twitch chat bot configuration and setup"
read_when:
- Setting up Twitch chat integration for OpenClaw
title: "Twitch"
+sidebarTitle: "Twitch"
---
Twitch chat support via IRC connection. OpenClaw connects as a Twitch user (bot account) to receive and send messages in channels.
## Bundled plugin
-Twitch ships as a bundled plugin in current OpenClaw releases, so normal
-packaged builds do not need a separate install.
+
+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
-it manually:
+If you are on an older build or a custom install that excludes Twitch, install it manually:
-Install via CLI (npm registry):
-
-```bash
-openclaw plugins install @openclaw/twitch
-```
-
-Local checkout (when running from a git repo):
-
-```bash
-openclaw plugins install ./path/to/local/twitch-plugin
-```
+
+
+ ```bash
+ openclaw plugins install @openclaw/twitch
+ ```
+
+
+ ```bash
+ openclaw plugins install ./path/to/local/twitch-plugin
+ ```
+
+
Details: [Plugins](/tools/plugin)
## Quick setup (beginner)
-1. Ensure the Twitch plugin is available.
- - Current packaged OpenClaw releases already bundle it.
- - Older/custom installs can add it manually with the commands above.
-2. Create a dedicated Twitch account for the bot (or use an existing account).
-3. Generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
- - Select **Bot Token**
- - Verify scopes `chat:read` and `chat:write` are selected
- - Copy the **Client ID** and **Access Token**
-4. Find your Twitch user ID: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)
-5. 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).
-6. Start the gateway.
+
+
+ Current packaged OpenClaw releases already bundle it. Older/custom installs can add it manually with the commands above.
+
+
+ Create a dedicated Twitch account for the bot (or use an existing account).
+
+
+ Use [Twitch Token Generator](https://twitchtokengenerator.com/):
-**⚠️ Important:** Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot. `requireMention` defaults to `true`.
+ - Select **Bot Token**
+ - Verify scopes `chat:read` and `chat:write` are selected
+ - Copy the **Client ID** and **Access Token**
+
+
+
+ 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.
+
+
+ - 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).
+
+
+
+ Start the gateway with the configured channel.
+
+
+
+
+Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot. `requireMention` defaults to `true`.
+
Minimal config:
@@ -82,31 +101,34 @@ Use [Twitch Token Generator](https://twitchtokengenerator.com/):
- 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):**
-
-```bash
-OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
-```
-
-**Or config:**
-
-```json5
-{
- channels: {
- twitch: {
- enabled: true,
- username: "openclaw",
- accessToken: "oauth:abc123...",
- clientId: "xyz789...",
- channel: "vevisk",
- },
- },
-}
-```
+
+
+ ```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.
@@ -126,9 +148,11 @@ Prefer `allowFrom` for a hard allowlist. Use `allowedRoles` instead if you want
**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/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (Convert your Twitch username to ID)
+
## Token refresh (optional)
@@ -151,7 +175,7 @@ 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`](/gateway/configuration) for the shared pattern.
+Use `channels.twitch.accounts` with per-account tokens. See [Configuration](/gateway/configuration) for the shared pattern.
Example (one bot account in two channels):
@@ -178,78 +202,65 @@ Example (one bot account in two channels):
}
```
-**Note:** Each account needs its own token (one token per channel).
+
+Each account needs its own token (one token per channel).
+
## Access control
-### Role-based restrictions
-
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- allowedRoles: ["moderator", "vip"],
+
+
+ ```json5
+ {
+ channels: {
+ twitch: {
+ accounts: {
+ default: {
+ allowFrom: ["123456789", "987654321"],
+ },
+ },
},
},
- },
- },
-}
-```
-
-### Allowlist by User ID (most secure)
-
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- allowFrom: ["123456789", "987654321"],
+ }
+ ```
+
+
+ ```json5
+ {
+ channels: {
+ twitch: {
+ accounts: {
+ default: {
+ allowedRoles: ["moderator", "vip"],
+ },
+ },
},
},
- },
- },
-}
-```
+ }
+ ```
-### 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.
-`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:
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- allowedRoles: ["moderator"],
+ ```json5
+ {
+ channels: {
+ twitch: {
+ accounts: {
+ default: {
+ requireMention: false,
+ },
+ },
},
},
- },
- },
-}
-```
+ }
+ ```
-### Disable @mention requirement
-
-By default, `requireMention` is `true`. To disable and respond to all messages:
-
-```json5
-{
- channels: {
- twitch: {
- accounts: {
- default: {
- requireMention: false,
- },
- },
- },
- },
-}
-```
+
+
## Troubleshooting
@@ -260,53 +271,77 @@ 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`.
+
+
+ "Failed to connect" or authentication errors:
-**Check access control:** Ensure your user ID is in `allowFrom`, or temporarily remove
-`allowFrom` and set `allowedRoles: ["all"]` to test.
+ - 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
-**Check the bot is in the channel:** The bot must join the channel specified in `channel`.
+
+
+ Check logs for refresh events:
-### Token issues
+ ```
+ Using env token source for mybot
+ Access token refreshed for user 123456 (expires in 14400s)
+ ```
-**"Failed to connect" or authentication errors:**
+ If you see "token refresh disabled (no refresh token)":
-- 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
+ - Ensure `clientSecret` is provided
+ - Ensure `refreshToken` is provided
-### 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:**
+### 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`)
+
+ 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:**
+### Provider options
- `channels.twitch.enabled` - Enable/disable channel startup
- `channels.twitch.username` - Bot username (simplified single-account config)
@@ -368,25 +403,25 @@ Example:
}
```
-## Safety & ops
+## 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 `chat:read` and `chat:write`
-- **If stuck**: Restart the gateway after confirming no other process owns the session
+- **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)
+- **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](/channels) — all supported channels
-- [Pairing](/channels/pairing) — DM authentication and pairing flow
-- [Groups](/channels/groups) — group chat behavior and mention gating
- [Channel Routing](/channels/channel-routing) — session routing for messages
+- [Channels Overview](/channels) — all supported channels
+- [Groups](/channels/groups) — group chat behavior and mention gating
+- [Pairing](/channels/pairing) — DM authentication and pairing flow
- [Security](/gateway/security) — access model and hardening