Twitch

通过 IRC 连接支持 Twitch 聊天。OpenClaw 作为 Twitch 用户（机器人账户）连接，以在频道中接收和发送消息。

需要插件

Twitch 作为插件发布，不随核心安装包捆绑。

通过 CLI 安装 (npm registry)：

openclaw plugins install @openclaw/twitch

本地检出（当从 git 仓库运行时）：

openclaw plugins install ./extensions/twitch

详情：插件 (Plugins)

快速设置（初学者）

为机器人创建一个专用的 Twitch 账户（或使用现有账户）。
生成凭据：Twitch Token Generator
- 选择 Bot Token
- 验证已选择 chat:read 和 chat:write 范围
- 复制 Client ID 和 Access Token
找到你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
配置令牌：
- 环境变量：OPENCLAW_TWITCH_ACCESS_TOKEN=...（仅限默认账户）
- 或配置：channels.twitch.accessToken
- 如果两者都设置了，配置优先（环境变量回退仅适用于默认账户）。
启动 Gateway。

⚠️ 重要： 添加访问控制（allowFrom 或 allowedRoles）以防止未授权用户触发机器人。requireMention 默认为 true。

最小配置：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",              // 机器人的 Twitch 账户
      accessToken: "oauth:abc123...",    // OAuth 访问令牌（或使用 OPENCLAW_TWITCH_ACCESS_TOKEN 环境变量）
      clientId: "xyz789...",             // 来自令牌生成器的 Client ID
      channel: "vevisk",                 // 要加入哪个 Twitch 频道的聊天（必填）
      allowFrom: ["123456789"]           // (推荐) 仅你的 Twitch 用户 ID - 从 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 获取
    }
  }
}

简介

一个由 Gateway 拥有的 Twitch 通道。
确定性路由：回复总是返回到 Twitch。
每个账户映射到一个隔离的会话键 agent:<agentId>:twitch:<accountName>。
username 是机器人的账户（谁在认证），channel 是要加入的聊天室。

设置（详细）

生成凭据

使用 Twitch Token Generator：

选择 Bot Token
验证已选择 chat:read 和 chat:write 范围
复制 Client ID 和 Access Token

无需手动注册应用。令牌会在数小时后过期。

配置机器人

环境变量（仅限默认账户）：

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

或配置：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "vevisk"
    }
  }
}

如果同时设置了环境变量和配置，配置优先。

访问控制（推荐）

{
  channels: {
    twitch: {
      allowFrom: ["123456789"],       // (推荐) 仅你的 Twitch 用户 ID
      allowedRoles: ["moderator"]     // 或限制为特定角色
    }
  }
}

可用角色： "moderator", "owner", "vip", "subscriber", "all"。

为什么使用用户 ID？ 用户名可以更改，允许冒充。用户 ID 是永久的。

找到你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (将你的 Twitch 用户名转换为 ID)

令牌刷新（可选）

来自 Twitch Token Generator 的令牌无法自动刷新 - 过期时请重新生成。

要实现自动令牌刷新，请在 Twitch Developer Console 创建你自己的 Twitch 应用程序并添加到配置：

{
  channels: {
    twitch: {
      clientSecret: "your_client_secret",
      refreshToken: "your_refresh_token"
    }
  }
}

机器人会在过期前自动刷新令牌并记录刷新事件。

多账户支持

使用 channels.twitch.accounts 进行每个账户的令牌配置。参见 gateway/configuration 了解共享模式。

示例（一个机器人账户在两个频道中）：

{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "vevisk"
        },
        channel2: {
          username: "openclaw",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel"
        }
      }
    }
  }
}

注意： 每个账户需要自己的令牌（每个频道一个令牌）。

访问控制详情

基于角色的限制

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator", "vip"]
        }
      }
    }
  }
}

基于用户 ID 的白名单（最安全）

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowFrom: ["123456789", "987654321"]
        }
      }
    }
  }
}

组合白名单 + 角色

allowFrom 中的用户绕过角色检查：

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowFrom: ["123456789"],
          allowedRoles: ["moderator"]
        }
      }
    }
  }
}

禁用 @mention 要求

默认情况下，requireMention 为 true。要禁用并响应所有消息：

{
  channels: {
    twitch: {
      accounts: {
        default: {
          requireMention: false
        }
      }
    }
  }
}

故障排除

首先，运行诊断命令：

openclaw doctor
openclaw channels status --probe

机器人不响应消息

检查访问控制： 临时设置 allowedRoles: ["all"] 进行测试。

检查机器人是否在频道中： 机器人必须加入 channel 中指定的频道。

令牌问题

“Failed to connect” 或认证错误：

验证 accessToken 是 OAuth 访问令牌值（通常以 oauth: 前缀开头）
检查令牌是否具有 chat:read 和 chat:write 范围
如果使用令牌刷新，验证 clientSecret 和 refreshToken 已设置

令牌刷新不工作

检查日志中的刷新事件：

Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)

如果你看到 “token refresh disabled (no refresh token)”：

确保提供了 clientSecret
确保提供了 refreshToken

配置参考

账户配置：

username - 机器人用户名
accessToken - 具有 chat:read 和 chat:write 的 OAuth 访问令牌
clientId - Twitch Client ID（来自令牌生成器或你的应用）
channel - 要加入的频道（必填）
enabled - 启用此账户（默认：true）
clientSecret - 可选：用于自动令牌刷新
refreshToken - 可选：用于自动令牌刷新
expiresIn - 令牌过期时间（秒）
obtainmentTimestamp - 令牌获取时间戳
allowFrom - 用户 ID 白名单
allowedRoles - 基于角色的访问控制（"moderator" | "owner" | "vip" | "subscriber" | "all"）
requireMention - 需要 @mention（默认：true）

提供商选项：

channels.twitch.enabled - 启用/禁用通道启动
channels.twitch.username - 机器人用户名（简化单账户配置）
channels.twitch.accessToken - OAuth 访问令牌（简化单账户配置）
channels.twitch.clientId - Twitch Client ID（简化单账户配置）
channels.twitch.channel - 要加入的频道（简化单账户配置）
channels.twitch.accounts.<accountName> - 多账户配置（上述所有账户字段）

完整示例：

{
  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"]
        }
      }
    }
  }
}

工具动作

代理可以使用 twitch 动作调用：

send - 发送消息到频道

示例：

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

安全与运维

像对待密码一样对待令牌 - 切勿将令牌提交到 git
使用自动令牌刷新 - 对于长期运行的机器人
使用用户 ID 白名单 - 代替用户名进行访问控制
监控日志 - 关注令牌刷新事件和连接状态
最小化令牌范围 - 仅请求 chat:read 和 chat:write
如果卡住：确认没有其他进程拥有会话后重启 Gateway

限制

每条消息 500 字符（在单词边界自动分块）
Markdown 在分块前被剥离
无速率限制（使用 Twitch 的内置速率限制）