Twitch（插件）

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

需要安装插件

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

通过 CLI 安装（npm 注册表）：

openclaw plugins install @openclaw/twitch

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

openclaw plugins install ./extensions/twitch

详情：插件

快速设置（新手）

  1. 为 Bot 创建一个专用 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. 配置 Token：
    • 环境变量：OPENCLAW_TWITCH_ACCESS_TOKEN=...（仅默认账户）
    • 或配置：channels.twitch.accessToken
    • 如果两者都设置了，配置优先（环境变量仅作为默认账户的备选）。
  5. 启动 Gateway。

警告： 请添加访问控制（allowFrom 或 allowedRoles）以防止未授权用户触发 Bot。requireMention 默认为 true。

最小配置：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Bot 的 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/ 获取
    },
  },
}

功能说明

  • Gateway 拥有 Twitch 频道连接。
  • 确定性路由：回复始终返回 Twitch。
  • 每个账户映射到一个隔离的会话键 agent:<agentId>:twitch:<accountName>。
  • username 是 Bot 的账户（用于认证），channel 是要加入的聊天室。

详细设置

生成凭据

使用 Twitch Token Generator：

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

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

配置 Bot

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

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
    },
  },
}

推荐使用 allowFrom 作为硬性白名单。如果需要基于角色的访问控制，则使用 allowedRoles。

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

为什么使用用户 ID？ 用户名可以更改，存在冒充风险。用户 ID 是永久性的。

查找你的 Twitch 用户 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/

Token 刷新（可选）

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

如需自动刷新 Token，请在 Twitch Developer Console 创建自己的 Twitch 应用并添加到配置：

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

Bot 会在 Token 过期前自动刷新，并记录刷新事件。

多账户支持

使用 channels.twitch.accounts 配置按账户的 Token。参见 gateway/configuration 了解共享模式。

示例（一个 Bot 账户在两个频道中）：

{
  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）。

访问控制

基于角色的限制

{
  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

Bot 不回复消息

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

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

Token 问题

“Failed to connect” 或认证错误：

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

Token 刷新不工作

检查日志中的刷新事件：

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

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

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

配置

账户配置：

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

提供者选项：

  • channels.twitch.enabled - 启用/禁用频道启动
  • channels.twitch.username - Bot 用户名（简化的单账户配置）
  • channels.twitch.accessToken - OAuth access token（简化的单账户配置）
  • 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"],
        },
      },
    },
  },
}

工具操作

Agent 可以调用 twitch 并执行操作：

  • send - 向频道发送消息

示例：

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

安全与运维

  • 将 Token 视为密码 — 切勿将 Token 提交到 git
  • 长期运行的 Bot 使用自动 Token 刷新
  • 使用用户 ID 白名单而非用户名进行访问控制
  • 监控日志关注 Token 刷新事件和连接状态
  • 最小化 Token 权限 — 仅请求 chat:read 和 chat:write
  • 遇到问题时：确认没有其他进程占用会话后重启 Gateway

限制

  • 每条消息 500 字符（在词边界处自动分块）
  • 发送前会剥离 Markdown
  • 无速率限制（使用 Twitch 内置速率限制）
arrow_back
上一页
Tlon
下一页
Whatsapp
arrow_forward