Twitch (插件)

通过 IRC 连接支持 Twitch 聊天。openclaw 以 Twitch 用户 (机器人账户) 身份连接，接收和发送频道消息。

需要插件

Twitch 作为插件提供，不包含在核心安装中。

通过 CLI 安装 (npm 注册表):

openclaw plugins install @openclaw/twitch

本地检出 (从 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: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. 配置令牌:
   • 环境变量: CLAWDBOT_TWITCH_ACCESS_TOKEN=... (仅限默认账户)
   • 或配置: channels.twitch.accessToken
   • 如果两者都设置，配置优先 (环境变量回退仅限默认账户)。
5. 启动网关。

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

最小配置:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",              // 机器人的 Twitch 账户
      accessToken: "oauth:abc123...",    // OAuth 访问令牌 (或使用 CLAWDBOT_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

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

配置机器人

环境变量 (仅限默认账户):

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

禁用 @提及要求

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

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

故障排除

首先，运行诊断命令:

openclaw doctor
openclaw channels status --probe

机器人不响应消息

检查访问控制: 临时设置 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 的内置速率限制)