Twitch
Twitch 聊天机器人配置与安装（IRC）
通过 IRC 连接支持 Twitch chat。OpenClaw 以 Twitch 用户（bot 账号）身份连接到频道，从而接收并发送消息。
需要安装插件
Twitch 以插件形式提供，不随 core 安装打包。
通过 CLI 安装（npm registry）：
openclaw plugins install @openclaw/twitch
本地安装（当你从 git 仓库运行时）：
openclaw plugins install ./extensions/twitch
详情：''/plugin''
新手快速配置
1. 为 bot 创建一个专用 Twitch 账号（或使用已有账号）。
2. 生成凭据：''Twitch Token Generator''
- 选择 Bot Token
- 确认 scopes 勾选了 ''chat:read'' 与 ''chat:write''
- 复制 Client ID 与 Access Token
3. 查找你的 Twitch user ID：
https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. 配置 token：
- Env：''OPENCLAW_TWITCH_ACCESS_TOKEN=...''（仅 default account）
- 或 config：''channels.twitch.accessToken''
- 两者都设置时，config 优先（env 仅作为 default account 兜底）。
5. 启动 gateway。
''重要：'' 请配置访问控制（''allowFrom'' 或 ''allowedRoles''）以避免未授权用户触发 bot。''requireMention'' 默认是 ''true''。
最小配置：
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
allowFrom: ["123456789"],
},
},
}这是什么
- 一个由 Gateway 管理的 Twitch 通道。
- 确定性路由：回复永远回到 Twitch。
- Each account maps to an isolated session key: ''agent:<agentId>:twitch:<accountName>''.
- ''username'' 是 bot 账号（用于鉴权），''channel'' 是要加入的 chat room（必填）。
设置（详细）
#
生成凭据
使用 ''Twitch Token Generator''：
- 选择 Bot Token
- 确认 scopes：''chat:read'' 与 ''chat:write''
- 复制 Client ID 与 Access Token
该方式无需手动注册 App，但 token 可能在数小时后过期。
#
配置 bot
Env（仅 default account）：
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
或 config：
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
},
}env 与 config 同时存在时，config 优先。
#
访问控制（推荐）
{
channels: {
twitch: {
allowFrom: ["123456789"]
},
},
}''allowFrom'' 是硬 allowlist（最安全）。如果你想按角色控制访问，则不设置 ''allowFrom''，改用 ''allowedRoles''。
''可用角色：'' ''"moderator"''、''"owner"''、''"vip"''、''"subscriber"''、''"all"''。
为什么用 user ID？ username 可能被改名，从而被冒名顶替；user ID 是永久的。
查找 user ID：
https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/
Token 刷新（可选）
由 ''Twitch Token Generator'' 生成的 tokens 无法自动刷新——过期后需要重新生成。
如果你希望自动刷新 token，请在 ''Twitch Developer Console'' 创建自己的 Twitch 应用，并在配置中加入：
{
channels: {
twitch: {
clientSecret: "your_client_secret",
refreshToken: "your_refresh_token",
},
},
}bot 会在 token 过期前自动刷新，并记录 refresh 日志事件。
多账号
使用 ''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",
},
},
},
},
}注意：每个 account 都需要自己的 token（通常一条 token 对应一个 channel）。
访问控制（更多示例）
#
基于角色限制
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator", "vip"],
},
},
},
},
}#
基于 User ID allowlist（最安全）
{
channels: {
twitch: {
accounts: {
default: {
allowFrom: ["123456789", "987654321"],
},
},
},
},
}#
角色访问（替代方案）
''allowFrom'' 是硬 allowlist；一旦设置，只允许这些 user IDs。
如果你希望按角色允许，把 ''allowFrom'' 留空，改用 ''allowedRoles''：
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator"],
},
},
},
},
}#
关闭 @mention 需求
默认 ''requireMention=true''。要对所有消息都回复：
{
channels: {
twitch: {
accounts: {
default: {
requireMention: false,
},
},
},
},
}排障
先运行诊断命令：
openclaw doctor openclaw channels status --probe
#
Bot 不回复
- 检查访问控制：确认你的 user ID 在 ''allowFrom''，或临时移除 ''allowFrom'' 并设置 ''allowedRoles: ["all"]'' 测试。
- 检查 bot 是否加入了 ''channel'' 指定的频道。
#
Token 问题
"Failed to connect" 或鉴权错误：
- 确认 ''accessToken'' 为 OAuth access token（通常以 ''oauth:'' 开头）
- 确认 token scopes 包含 ''chat:read'' 与 ''chat:write''
- 若启用 token refresh，确认 ''clientSecret'' 与 ''refreshToken'' 已设置
#
Token refresh 不工作
查看日志中的 refresh 事件：
Using env token source for mybot Access token refreshed for user 123456 (expires in 14400s)
如果看到 "token refresh disabled (no refresh token)"：
- 确认提供了 ''clientSecret''
- 确认提供了 ''refreshToken''
配置
Account 配置字段：
- ''username''：bot 用户名
- ''accessToken''：带 ''chat:read''/''chat:write'' 的 OAuth access token
- ''clientId''：Twitch Client ID（Token Generator 或你的应用）
- ''channel''：要加入的频道（必填）
- ''enabled''：是否启用该 account（默认 ''true''）
- ''clientSecret''：可选，用于自动 token refresh
- ''refreshToken''：可选，用于自动 token refresh
- ''expiresIn''：过期秒数
- ''obtainmentTimestamp''：获取 token 的时间戳
- ''allowFrom''：user ID allowlist
- ''allowedRoles''：按角色访问控制（''"moderator" | "owner" | "vip" | "subscriber" | "all"''）
- ''requireMention''：是否需要 @mention（默认 ''true''）
Provider 配置字段：
- ''channels.twitch.enabled''
- ''channels.twitch.username''（单账号简化配置）
- ''channels.twitch.accessToken''（单账号简化配置）
- ''channels.twitch.clientId''（单账号简化配置）
- ''channels.twitch.channel''（单账号简化配置）
- ''channels.twitch.accounts.<accountName>'' (multi-account config)
完整示例：
{
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"],
},
},
},
},
}工具动作（Tool actions）
agent 可以调用 ''twitch'' 的动作：
- ''send''：向频道发送消息
示例：
{
action: "twitch",
params: {
message: "Hello Twitch!",
to: "#mychannel",
},
}安全与运维
- 把 tokens 当作密码：不要提交到 git
- 长期运行建议启用自动 token refresh
- 访问控制优先使用 user ID allowlist（不要用 username）
- 监控 logs 中的 refresh 与连接状态
- 只申请最小 scopes：''chat:read'' 与 ''chat:write''
- 若卡住：确认没有其他进程占用会话后重启 gateway
限制
- 单条消息 500 字符（会按词边界自动分段）
- 分段前会去掉 Markdown
- 不做额外的 rate limiting（依赖 Twitch 自带限流）