Twitch（插件）

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

需要插�?

Twitch 作为插件提供，不随核心安装一起打包�?

通过 CLI 安装（npm 注册表）�?

openclaw plugins install @openclaw/twitch

本地检出（�?git 仓库运行时）�?

openclaw plugins install ./extensions/twitch

详情：Plugins

快速设置（入门�?

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

*⚠️ 重要�? 添加访问控制（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 - �?https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 获取
    },
  },
}

它是什�?

  • 网关拥有�?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
    },
  },
}

优先使用 allowList 进行硬允许列表。如果你想基于角色的访问，使�?allowedRoles�?

*可用角色�? "moderator"、"owner"、"vip"、"subscriber"、"all"�?

*为什么用用户 ID�? 用户名可以更改，允许冒名顶替。用�?ID 是永久的�?

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

令牌刷新（可选）

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

要自动刷新令牌，�?Console](https:// [Twitch Developerdev.twitch.tv/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 是硬允许列表。设置后，仅允许那些用户 ID�? 如果你想基于角色的访问，保持 allowFrom 未设置而是配置 allowedRoles�?

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

禁用 @提及要求

默认情况下，requireMention �?true。要禁用并回复所有消息：

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

故障排除

首先，运行诊断命令：

openclaw doctor
openclaw channels status --probe

机器人不回复消息

检查访问控制： 确保你的用户 ID �?allowFrom 中，或暂时移�? allowFrom 并设�?allowedRoles: ["all"] 进行测试�?

*检查机器人在频道中�? 机器人必须加�?channel 中指定的频道�?

令牌问题

“连接失败”或认证错误：

  • 验证 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（来�?Token Generator 或你的应用）
  • channel - 要加入的频道（必需�?
  • enabled - 启用此账户（默认：true�?
  • clientSecret - 可选：用于自动令牌刷新
  • refreshToken - 可选：用于自动令牌刷新
  • expiresIn - 令牌过期秒数
  • obtainmentTimestamp - 令牌获取时间�?
  • allowFrom - 用户 ID 允许列表
  • allowedRoles - 基于角色的访问控制（"moderator" | "owner" | "vip" | "subscriber" | "all"�?
  • requireMention - 需�?@提及（默认：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
  • 如果卡住：确认没有其他进程拥有会话后重启网关

限制

  • 每条消息 **500 个字�?*（在单词边界自动分块�?
  • 分块前剥�?markdown
  • 无速率限制（使�?Twitch 内置速率限制�?