Twitch（插件）

通过 IRC 连接实现 Twitch 聊天支持。OpenClaw 以 Twitch 用户（机器人账号）身份连接，在直播频道中接收和发送消息。

需要安装插件

Twitch 以插件形式发布，不包含在核心安装包中。

通过 CLI 安装（npm 仓库）：

openclaw plugins install @openclaw/twitch

本地 checkout（从 git 仓库运行时）：

openclaw plugins install ./extensions/twitch

详情：插件系统

快速配置（新手上路）

让小龙虾入驻直播间，分四步走：

1. 为机器人创建一个专用 Twitch 账号（或使用现有账号）。
2. 生成凭证：Twitch Token Generator
   • 选择 Bot Token
   • 确认已选中 chat:read 和 chat:write 权限范围
   • 复制 Client ID 和 Access Token
3. 查找你的 Twitch 用户 ID：streamweasels.com
4. 配置 token：
   • 环境变量：OPENCLAW_TWITCH_ACCESS_TOKEN=...（仅限默认账号）
   • 或配置文件：channels.twitch.accessToken
   • 两者都设置时，配置文件优先（环境变量回退仅限默认账号）。

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

最小配置示例：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // 机器人的 Twitch 账号
      accessToken: "oauth:abc123...", // OAuth Access Token（或使用 OPENCLAW_TWITCH_ACCESS_TOKEN 环境变量）
      clientId: "xyz789...", // Token Generator 提供的 Client ID
      channel: "vevisk", // 要加入哪个 Twitch 频道的聊天室（必填）
      allowFrom: ["123456789"], // （推荐）只允许你自己的 Twitch 用户 ID
    },
  },
}

功能说明

• 由 Gateway 拥有的 Twitch 频道。
• 确定性路由：回复始终发回 Twitch。
• 每个账号对应独立的会话键 agent:<agentId>:twitch:<accountName>。
• username 是机器人账号（认证方），channel 是要加入的聊天室。

生成凭证

使用 Twitch Token Generator：

• 选择 Bot Token
• 确认已选中 chat:read 和 chat:write 权限范围
• 复制 Client ID 和 Access Token

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

访问控制

用户 ID 白名单（最安全）

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // 推荐：只填你自己的用户 ID
    },
  },
}

为什么用用户 ID？ 用户名可以修改，存在被冒充的风险；用户 ID 是永久不变的。

查找 Twitch 用户 ID：streamweasels.com

基于角色的访问控制

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

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

allowFrom 是硬白名单，设置后只有这些用户 ID 被允许。如需角色访问，不设 allowFrom，仅配置 allowedRoles。

禁用 @mention 要求

默认 requireMention 为 true。要响应所有消息：

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

Token 自动刷新（可选）

Twitch Token Generator 生成的 Token 无法自动刷新，过期后需要重新生成。

要启用自动刷新，在 Twitch Developer Console 创建自己的 Twitch 应用，然后在配置中添加：

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

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

多账号支持

使用 channels.twitch.accounts 配置每账号独立的 token。参见 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",
        },
      },
    },
  },
}

注意： 每个账号需要独立的 Token（每频道一个 Token）。

故障排查

先运行诊断命令：

openclaw doctor
openclaw channels status --probe

机器人不响应消息：

• 检查访问控制：确认你的用户 ID 在 allowFrom 中，或临时移除 allowFrom 并设置 allowedRoles: ["all"] 进行测试。
• 检查机器人是否在频道中：机器人必须已加入 channel 指定的频道。

Token 问题（"Failed to connect" 或认证错误）：

• 确认 accessToken 是 OAuth access token 值（通常以 oauth: 前缀开头）
• 检查 Token 具有 chat:read 和 chat:write 权限范围
• 如使用 Token 刷新，确认已设置 clientSecret 和 refreshToken

Token 刷新不工作： 检查日志中是否有刷新事件，确认提供了 clientSecret 和 refreshToken。

配置参数

账号配置：

• username - 机器人用户名
• accessToken - 具有 chat:read 和 chat:write 的 OAuth access token
• clientId - Twitch Client ID（来自 Token Generator 或你的应用）
• channel - 要加入的频道（必填）
• enabled - 启用此账号（默认：true）
• clientSecret - 可选：用于自动 Token 刷新
• refreshToken - 可选：用于自动 Token 刷新
• allowFrom - 用户 ID 白名单
• allowedRoles - 基于角色的访问控制（"moderator" | "owner" | "vip" | "subscriber" | "all"）
• requireMention - 是否需要 @mention（默认：true）

Provider 配置项：

• channels.twitch.enabled - 启用/禁用渠道
• channels.twitch.username - 机器人用户名（简化单账号配置）
• channels.twitch.accessToken - OAuth access token（简化单账号配置）
• channels.twitch.clientId - Twitch Client ID（简化单账号配置）
• channels.twitch.channel - 要加入的频道（简化单账号配置）
• channels.twitch.accounts.<accountName> - 多账号配置（包含上述所有账号字段）

Tool 动作

Agent 可以调用 twitch 执行以下动作：

• send - 向频道发送消息

示例：

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

安全与运维

• 像密码一样保管 Token - 不要提交到 git
• 对长期运行的机器人启用自动 Token 刷新
• 用用户 ID 白名单而非用户名进行访问控制
• 监控日志中的 Token 刷新事件和连接状态
• 最小化 Token 权限范围 - 只申请 chat:read 和 chat:write
• 卡住时：确认没有其他进程占用会话后重启 Gateway

限制

• 每条消息 500 个字符（在词边界自动分块）
• 分块前会去除 Markdown
• 不额外限速（使用 Twitch 内置速率限制）