Twitch（插件）

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

需安装插件

Twitch 以插件形式提供，不随核心安装打包。通过 CLI 安装（npm 仓库）：


moltbot plugins install @moltbot/twitch

本地检出（在 git 仓库中运行时）：


moltbot plugins install ./extensions/twitch

详见插件。

快速设置（入门）

为机器人创建专用 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/
配置 token：
- 环境变量：CLAWDBOT_TWITCH_ACCESS_TOKEN=...（仅默认账号）
- 或配置：channels.twitch.accessToken
- 若两者都设，以配置为准（环境变量仅作默认账号回退）。
启动网关。

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


{
  channels: {
    twitch: {
      enabled: true,
      username: "moltbot",              // 机器人的 Twitch 账号
      accessToken: "oauth:abc123...",    // OAuth Access Token（或用 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

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

配置机器人

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


CLAWDBOT_TWITCH_ACCESS_TOKEN=oauth:abc123...

或配置：


{
  channels: {
    twitch: {
      enabled: true,
      username: "moltbot",
      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/

Token 刷新（可选）

Twitch Token Generator 的 token 无法自动刷新，过期后需重新生成。若要自动刷新，在 Twitch Developer Console 创建自己的 Twitch 应用并在配置中添加：


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

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

多账号支持

使用 channels.twitch.accounts，每账号单独 token。共享模式见配置。示例（一个机器人账号加入两个频道）：


{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "moltbot",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "vevisk"
        },
        channel2: {
          username: "moltbot",
          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 中的用户跳过角色检查：


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

关闭 @ 提及要求

默认 requireMention 为 true。若要关闭并对所有消息回复：


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

故障排查

先运行诊断命令：


moltbot doctor
moltbot channels status --probe

机器人不回复消息

检查访问控制：临时设 allowedRoles: ["all"] 测试。检查机器人是否在频道：机器人必须加入 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 — 机器人用户名
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 — 机器人用户名（单账号简化配置）
channels.twitch.accessToken — OAuth access token（单账号简化配置）
channels.twitch.clientId — Twitch Client ID（单账号简化配置）
channels.twitch.channel — 要加入的频道（单账号简化配置）
channels.twitch.accounts.<accountName> — 多账号配置（含上述所有账号字段）

完整示例：


{
  channels: {
    twitch: {
      enabled: true,
      username: "moltbot",
      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
长运行机器人使用自动 token 刷新
访问控制用用户 ID 白名单，不用用户名
监控日志中的 token 刷新事件与连接状态
权限最小化 — 只请求 chat:read 和 chat:write
若卡住：确认无其他进程占用该会话后重启网关

限制

每条消息 500 字符（按词边界自动分块）
分块前会剥离 Markdown
无额外限速（使用 Twitch 内置限速）