romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
jaydenfyi 2026-01-25 19:59:51 +08:00
parent 5a155697fa
commit cc9af164a8
2 changed files with 117 additions and 295 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

399
docs/channels/twitch.md
View File

@ -10,50 +10,6 @@ Twitch chat support via IRC connection. Clawdbot connects as a Twitch user (bot
Status: ready for Twitch chat via IRC connection with @twurple. Status: ready for Twitch chat via IRC connection with @twurple.
## Quick setup (beginner)
1) Install the Twitch plugin.
2) Generate your credentials (recommended: use [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** (and optionally **Refresh Token**)
3) Set the credentials for Clawdbot:
- Env: `CLAWDBOT_TWITCH_ACCESS_TOKEN=...` (default account only)
- Or config: `channels.twitch.accounts.default.token`
- If both are set, config takes precedence (env fallback is default-account only).
4) Start the gateway.
5) The bot joins your channel and responds to messages.
Minimal config:
```json5
{
channels: {
twitch: {
enabled: true,
username: "clawdbot", // Bot's Twitch account
accessToken: "oauth:abc123...", // OAuth Access Token (or use CLAWDBOT_TWITCH_ACCESS_TOKEN env var)
clientId: "your_client_id", // Client ID from Token Generator
channel: "vevisk" // Which Twitch channel's chat to join
}
}
}
```
**Note:** [Twitch Token Generator](https://twitchtokengenerator.com/) provides the Client ID and Access Token (select **Bot Token** and verify `chat:read` + `chat:write` scopes) - no manual app registration needed.
**Note:** `username` is the bot's account, `channel` is which chat to join.
**Multi-account setup:** Use `channels.twitch.accounts` for advanced multi-account configurations.
## How it works
1. Create a bot account (or use an existing Twitch account).
2. Generate credentials using [Twitch Token Generator](https://twitchtokengenerator.com/) (provides Client ID, Access Token, and Refresh Token).
3. Configure Clawdbot with the credentials.
4. Run the gateway; it auto-starts the Twitch channel when a token is available (config first, env fallback) and `channels.twitch.enabled` is not `false`.
5. The bot joins the specified `channel` to send/receive messages.
6. Direct chats collapse into the agent's main session (default `agent:main:main`); each account maps to an isolated session key `agent:<agentId>:twitch:<accountName>`.
**Key distinction:** `username` is who the bot authenticates as (the bot's account), `channel` is which chat room it joins.
## Plugin required ## Plugin required
Twitch ships as a plugin and is not bundled with the core install. Twitch ships as a plugin and is not bundled with the core install.
@ -74,90 +30,72 @@ Details: [Plugins](/plugin)
## Setup ## Setup
### 1) Generate your credentials (recommended: Twitch Token Generator) 1) Install the Twitch plugin and create a dedicated Twitch account for the bot.
- Go to [Twitch Token Generator](https://twitchtokengenerator.com/) 2) Generate your credentials (recommended: use [Twitch Token Generator](https://twitchtokengenerator.com/)):
- Select **Bot Token** - Select **Bot Token**
- Verify scopes `chat:read` and `chat:write` are selected - Verify scopes `chat:read` and `chat:write` are selected
- Copy the **Access Token** and **Client ID** - Copy the **Client ID** and **Access Token**
3) Configure credentials:
- Env: `CLAWDBOT_TWITCH_ACCESS_TOKEN=...` (default account only)
- Or config: `channels.twitch.accounts.default.accessToken`
- If both are set, config takes precedence (env fallback is default-account only).
4) Start the gateway.
5) The bot joins your channel and responds to messages.
### 2) Configure credentials **⚠️ Important:** Strongly recommended to add `requireMention` and access control (`allowFrom` or `allowedRoles`) to prevent the bot from replying to all chat messages.
Env (default account only):
```bash
export CLAWDBOT_TWITCH_ACCESS_TOKEN=your_access_token_here
```
Or config: Minimal config:
```json5 ```json5
{ {
channels: { channels: {
twitch: { twitch: {
enabled: true, enabled: true,
accounts: {
default: {
username: "clawdbot", // Bot's Twitch account username: "clawdbot", // Bot's Twitch account
accessToken: "oauth:abc123...", // Access Token from Token Generator (or omit to use env var) accessToken: "oauth:abc123...", // OAuth Access Token (or use CLAWDBOT_TWITCH_ACCESS_TOKEN env var)
clientId: "xyz789...", // Client ID from Token Generator clientId: "your_client_id", // Client ID from Token Generator
channel: "vevisk" // Which Twitch channel's chat to join channel: "vevisk", // Which Twitch channel's chat to join
} requireMention: true, // (recommended) Only reply when mentioned
} allowFrom: ["123456789"] // (recommended) Your Twitch user ID only (Convert your twitch username to ID at https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/)
} }
} }
} }
``` ```
**Note:** Copy the **Access Token** value to the `accessToken` property (add `oauth:` prefix if needed), and the **Client ID** value to the `clientId` property. **Recommended access control options:**
- `requireMention: true` - Only respond when the bot is mentioned with `@botname`
- `allowFrom: ["your_user_id"]` - Restrict to your Twitch user ID only
- `allowedRoles: ["moderator", "vip", "subscriber"]` - Restrict to specific roles
With env, you still need `clientId` and `channel` in config (or use the minimal config above without `accessToken`). **Note:** [Twitch Token Generator](https://twitchtokengenerator.com/) provides the Client ID and Access Token (select **Bot Token** and verify `chat:read` + `chat:write` scopes) - no manual app registration needed.
### 3) Start the gateway **Note:** `username` is the bot's account, `channel` is which chat to join.
Twitch starts when a token is resolved (config first, env fallback).
### 4) Join a channel ## How it works
The bot joins the channel specified in `channel`.
## Token refresh (optional, for long-running bots) 1. Create a bot account (or use an existing Twitch account).
2. Generate credentials using [Twitch Token Generator](https://twitchtokengenerator.com/) (provides Client ID, Access Token, and optionally Refresh Token).
3. Configure Clawdbot with the credentials.
4. Run the gateway; it auto-starts the Twitch channel when a token is available (config first, env fallback) and `channels.twitch.enabled` is not `false`.
5. The bot joins the specified `channel` to send/receive messages.
6. Each account maps to an isolated session key `agent:<agentId>:twitch:<accountName>`.
**Important:** Tokens from [Twitch Token Generator](https://twitchtokengenerator.com/) cannot be automatically refreshed - you'll need to generate a new token when it expires (typically after several hours). **Key distinction:** `username` is who the bot authenticates as (the bot's account), `channel` is which chat room it joins.
For automatic token refresh, you must create your own Twitch application: ## Token refresh (optional)
1. Create a Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console) Tokens from [Twitch Token Generator](https://twitchtokengenerator.com/) cannot be automatically refreshed - you'll need to generate a new token when it expires (typically after several hours).
- Copy the **Client ID** and **Client Secret**
2. Generate a refresh token using your own app (you'll need to implement the OAuth flow or use a tool that lets you specify your Client ID)
3. Add to config:
```json5 For automatic token refresh, create your own Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console) and add `clientSecret` and `refreshToken` to your config. The bot automatically refreshes tokens before they expire and logs refresh events.
{
channels: {
twitch: {
accounts: {
default: {
username: "clawdbot",
accessToken: "oauth:abc123...", // Access Token from your app
clientId: "xyz789...", // Client ID from your app
clientSecret: "secret123...", // Client Secret from your app
refreshToken: "refresh456...", // Refresh Token from your app
expiresIn: 14400,
obtainmentTimestamp: 1706092800000
}
}
}
}
}
```
**Note:** All three values (`accessToken`, `clientId`, `refreshToken`) must come from the same Twitch application you created.
The bot automatically refreshes tokens before they expire and logs refresh events.
## Routing model ## Routing model
- Replies always go back to Twitch. - Replies always go back to Twitch.
- Each account maps to `agent:<agentId>:twitch:<accountName>`. - Each account maps to `agent:<agentId>:twitch:<accountName>`.
## Multi-account support ## Multi-account support
Use `channels.twitch.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. Use `channels.twitch.accounts` with per-account tokens. See [`gateway/configuration`](/gateway/configuration) for the shared pattern.
Example (one bot account in two different channels): Example (one bot account in two different channels):
@ -184,71 +122,9 @@ Example (one bot account in two different channels):
} }
``` ```
## Migration notes
### Breaking changes (2026.1.23+)
**`token` renamed to `accessToken`:** If you have existing Twitch config using `token`, update to `accessToken`:
**Before:**
```json5
{
channels: {
twitch: {
accounts: {
default: {
username: "clawdbot",
token: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk"
}
}
}
}
}
```
**After:**
```json5
{
channels: {
twitch: {
accounts: {
default: {
username: "clawdbot",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk"
}
}
}
}
}
```
**Simplified config (recommended):** For single-account setups, you can now use base-level properties:
```json5
{
channels: {
twitch: {
enabled: true,
username: "clawdbot",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk"
}
}
}
```
The env var `CLAWDBOT_TWITCH_ACCESS_TOKEN` continues to work for the default account.
## Access control ## Access control
### Role-based restrictions (recommended) ### Role-based restrictions
Restrict access to specific roles:
```json5 ```json5
{ {
@ -268,12 +144,7 @@ Restrict access to specific roles:
} }
``` ```
**Available roles:** **Available roles:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`.
- `"moderator"` - Channel moderators
- `"owner"` - Channel owner/broadcaster
- `"vip"` - VIPs
- `"subscriber"` - Subscribers
- `"all"` - Anyone in chat
### Allowlist by User ID ### Allowlist by User ID
@ -299,11 +170,11 @@ Only allow specific Twitch user IDs (most secure):
**Why user IDs instead of usernames?** Twitch usernames can change, which could allow someone to hijack another user's access. User IDs are permanent. **Why user IDs instead of usernames?** Twitch usernames can change, which could allow someone to hijack another user's access. User IDs are permanent.
Find your Twitch user ID at: https://www.streamweasels.com/tools/convert-your-twitch-username-to-user-id/ Find your Twitch user ID at: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/
### Combined allowlist + roles ### Combined allowlist + roles
Users in `allowFrom` bypass role checks. In this example: Users in `allowFrom` bypass role checks. Example:
- User `123456789` can always message (bypasses role check) - User `123456789` can always message (bypasses role check)
- All moderators can message - All moderators can message
- Everyone else is blocked - Everyone else is blocked
@ -349,62 +220,6 @@ Only respond when the bot is mentioned:
} }
``` ```
## Environment variables
For the default account, you can use environment variables instead of config:
- `CLAWDBOT_TWITCH_ACCESS_TOKEN` - Access Token (without `oauth:` prefix)
Env fallback only works for the default account. For multi-account setups, use config.
Example:
```bash
export CLAWDBOT_TWITCH_ACCESS_TOKEN=abc123def456...
```
Config with env fallback:
```json5
{
channels: {
twitch: {
enabled: true,
accounts: {
default: {
username: "mybot",
clientId: "xyz789...",
channel: "your_channel"
// token will be read from CLAWDBOT_TWITCH_ACCESS_TOKEN
}
}
}
}
}
```
Priority: account config > base config > env var (for default account only).
## Plugin options
Control markdown stripping behavior:
```json5
{
plugins: {
entries: {
twitch: {
stripMarkdown: true
}
}
}
}
```
- `stripMarkdown` (default: `true`) - Remove markdown formatting before sending to Twitch
Twitch doesn't support markdown, so this is enabled by default. Disable if you want to send markdown as-is (it will appear as plain text with markdown symbols).
## Capabilities & limits ## Capabilities & limits
**Supported:** **Supported:**
@ -435,25 +250,7 @@ clawdbot channels status --probe
### Bot doesn't respond to messages ### Bot doesn't respond to messages
**Check access control:** **Check access control:** Temporarily set `allowedRoles: ["all"]` to test.
```json5
{
channels: {
twitch: {
accounts: {
default: {
username: "mybot",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "your_channel",
// Temporary: allow everyone
allowedRoles: ["all"]
}
}
}
}
}
```
**Check the bot is in the channel:** The bot must join the channel specified in `channel`. **Check the bot is in the channel:** The bot must join the channel specified in `channel`.
@ -468,70 +265,86 @@ clawdbot channels status --probe
**Check logs for refresh events:** **Check logs for refresh events:**
``` ```
[twitch] Using env token source for mybot Using env token source for mybot
[twitch] Access token refreshed for user 123456 (expires in 14400s) Access token refreshed for user 123456 (expires in 14400s)
``` ```
If you see "token refresh disabled (no refresh token)": If you see "token refresh disabled (no refresh token)":
- Ensure `clientSecret` is provided - Ensure `clientSecret` is provided
- Ensure `refreshToken` is provided (from Twitch Token Generator with "Include Refresh Token" checked) - Ensure `refreshToken` is provided
## Configuration reference (Twitch) ## Config
Full configuration: [Configuration](/gateway/configuration) ```json5
### Account config
```typescript
{ {
username: string, // Bot username channels: {
accessToken: string, // OAuth access token with chat:read and chat:write twitch: {
clientId: string, // Twitch Client ID (from Token Generator site or your app) enabled: true,
channel: string, // Channel to join username: "clawdbot",
enabled?: boolean, // Enable this account (default: true) accessToken: "oauth:abc123...",
clientSecret?: string, // Optional: For automatic token refresh (from YOUR Twitch app) clientId: "xyz789...",
refreshToken?: string, // Optional: For automatic token refresh (from YOUR Twitch app) channel: "vevisk",
expiresIn?: number, // Token expiry in seconds (for refresh) clientSecret: "secret123...",
obtainmentTimestamp?: number, // Token obtained timestamp (for refresh) refreshToken: "refresh456...",
allowFrom?: string[], // User ID allowlist requireMention: true,
allowedRoles?: TwitchRole[], // Role-based access control allowFrom: ["123456789"],
requireMention?: boolean // Require @mention (default: false) 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"],
requireMention: true
}
}
}
},
plugins: {
entries: {
twitch: {
stripMarkdown: true
}
}
}
} }
``` ```
**TwitchRole:** `"moderator"` | `"owner"` | `"vip"` | `"subscriber"` | `"all"` **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
- `enabled` - Enable this account (default: `true`)
- `clientSecret` - Optional: For automatic token refresh (from YOUR Twitch app)
- `refreshToken` - Optional: For automatic token refresh (from YOUR Twitch app)
- `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: `false`)
### Plugin config **Plugin config:**
- `stripMarkdown` - Strip markdown from outbound (default: `true`)
```typescript **Provider options:**
{ - `channels.twitch.enabled` - Enable/disable channel startup
stripMarkdown?: boolean // Strip markdown from outbound (default: true) - `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)
Provider options: - `channels.twitch.accounts.<accountName>` - Multi-account config (all account fields above)
- `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>.username`: bot username (multi-account config).
- `channels.twitch.accounts.<accountName>.accessToken`: OAuth access token (multi-account config).
- `channels.twitch.accounts.<accountName>.clientId`: Twitch Client ID (from Token Generator or your app).
- `channels.twitch.accounts.<accountName>.channel`: channel to join.
- `channels.twitch.accounts.<accountName>.enabled`: enable/disable account (default: true).
- `channels.twitch.accounts.<accountName>.clientSecret`: optional, for automatic token refresh (must be from YOUR Twitch app).
- `channels.twitch.accounts.<accountName>.refreshToken`: optional, for automatic token refresh (must be from YOUR Twitch app).
- `channels.twitch.accounts.<accountName>.expiresIn`: token expiry in seconds.
- `channels.twitch.accounts.<accountName>.obtainmentTimestamp`: token obtained timestamp.
- `channels.twitch.accounts.<accountName>.allowFrom`: user ID allowlist.
- `channels.twitch.accounts.<accountName>.allowedRoles`: role-based access control.
- `channels.twitch.accounts.<accountName>.requireMention`: require @mention (default: false).
## Tool actions ## Tool actions
The agent can call `twitch` with action: The agent can call `twitch` with action:
- `send` - Send a message to a channel - `send` - Send a message to a channel
Example: Example:

11
extensions/twitch/README.md
View File

@ -20,6 +20,8 @@ Onboarding: select Twitch and confirm the install prompt to fetch the plugin aut
Minimal config (simplified single-account): Minimal config (simplified single-account):
**⚠️ Important:** Strongly recommended to add `requireMention` and access control (`allowFrom` or `allowedRoles`) to prevent the bot from replying to all chat messages.
```json5 ```json5
{ {
channels: { channels: {
@ -29,11 +31,18 @@ Minimal config (simplified single-account):
accessToken: "oauth:abc123...", // OAuth Access Token (add oauth: prefix) accessToken: "oauth:abc123...", // OAuth Access Token (add oauth: prefix)
clientId: "xyz789...", // Client ID from Token Generator clientId: "xyz789...", // Client ID from Token Generator
channel: "vevisk", // Channel to join channel: "vevisk", // Channel to join
requireMention: true, // (recommended) Only reply when mentioned
allowFrom: ["123456789"], // (recommended) Your Twitch user ID only (Convert your twitch username to ID at https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/)
}, },
}, },
} }
``` ```
**Recommended access control options:**
- `requireMention: true` - Only respond when the bot is mentioned with `@botname`
- `allowFrom: ["your_user_id"]` - Restrict to your Twitch user ID only (find your ID at https://www.twitchangles.com/xqc or similar)
- `allowedRoles: ["moderator", "vip", "subscriber"]` - Restrict to specific roles
Multi-account config (advanced): Multi-account config (advanced):
```json5 ```json5
@ -62,7 +71,7 @@ Multi-account config (advanced):
## Setup ## Setup
1. Generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/) 1. Create a dedicated Twitch account for the bot, then generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
- Select **Bot Token** - Select **Bot Token**
- Verify scopes `chat:read` and `chat:write` are selected - Verify scopes `chat:read` and `chat:write` are selected
- Copy the **Access Token** to `token` property - Copy the **Access Token** to `token` property