openclaw/extensions/twitch/README.md

@clawdbot/twitch

Twitch channel plugin for Clawdbot.

Install (local checkout)

clawdbot plugins install ./extensions/twitch

Install (npm)

clawdbot plugins install @clawdbot/twitch

Onboarding: select Twitch and confirm the install prompt to fetch the plugin automatically.

Config

Minimal config (default account):

{
  channels: {
    twitch: {
      enabled: true,
      accounts: {
        default: {
          username: "mybot",
          token: "oauth:your_token_here",
          clientId: "your_client_id_here"
        }
      }
    }
  }
}

Setup

1. Create a Twitch application:

   • Go to Twitch Developer Console
   • Click "Register Your Application"
   • Set Application Type to "Chat Bot"
   • Copy the Client ID

2. Generate your OAuth token:

   • Use Twitch Token Generator or TwitchApps TMI
   • Select scopes: chat:read and chat:write
   • Copy the token (starts with oauth:)

3. Configure credentials:

   • Config: channels.twitch.accounts.default.token
   • Or env: CLAWDBOT_TWITCH_ACCESS_TOKEN=... (default account only)

4. Start the gateway - Twitch starts when a token is resolved

Token refresh (recommended)

For long-running bots, configure automatic token refresh:

{
  channels: {
    twitch: {
      accounts: {
        default: {
          username: "mybot",
          token: "oauth:abc123...",
          clientId: "your_client_id",
          clientSecret: "your_client_secret",
          refreshToken: "your_refresh_token"
        }
      }
    }
  }
}

Access control

Allowlist by user ID (recommended):

{
  channels: {
    twitch: {
      accounts: {
        default: {
          username: "mybot",
          token: "oauth:...",
          clientId: "...",
          allowFrom: ["123456789", "987654321"]
        }
      }
    }
  }
}

Role-based restrictions:

{
  channels: {
    twitch: {
      accounts: {
        default: {
          username: "mybot",
          token: "oauth:...",
          clientId: "...",
          allowedRoles: ["moderator", "vip"]
        }
      }
    }
  }
}

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

Multiple accounts

{
  channels: {
    twitch: {
      accounts: {
        main: {
          username: "mybot",
          token: "oauth:...",
          clientId: "...",
          channel: "streamer1"
        },
        secondary: {
          username: "mybot",
          token: "oauth:...",
          clientId: "...",
          channel: "streamer2"
        }
      }
    }
  }
}

Environment variables

For the default account:

• CLAWDBOT_TWITCH_ACCESS_TOKEN - OAuth token (with oauth: prefix)

Restart the gateway after config changes.

Full documentation

See https://docs.clawd.bot/channels/twitch for complete documentation including:

• Token setup options
• Access control patterns
• Troubleshooting
• Capabilities & limits