OpenClaw Twitch 渠道
即时通讯
简单
通过 IRC 协议将 OpenClaw 连接到 Twitch 聊天，让你的 AI 助手能够与观众实时互动。安装 Twitch 插件，配置具有聊天权限的 OAuth Token，你的机器人即可加入频道、回复提及消息，并通过基于角色的访问控制来管理对话。
快速信息
难度简单
分类即时通讯
支持功能数2 / 6
Twitch 支持的功能
文本消息
支持
媒体与文件
不支持
消息反应
不支持
消息线程
不支持
语音消息
不支持
群聊
支持
Twitch 前置条件
- 一个用作机器人身份的 Twitch 账号
- 一个具有 chat:read 和 chat:write 权限的 OAuth Access Token
- 从 Twitch Developer Console 获取的 Client ID
- 已安装并运行 OpenClaw Gateway
- 通过 'openclaw plugins install @openclaw/twitch' 安装 Twitch 插件
Twitch 快速设置
1
安装 Twitch 插件
运行 'openclaw plugins install @openclaw/twitch' 以添加 Twitch 支持。也可以通过本地路径安装：'openclaw plugins install ./extensions/twitch'。
2
获取 OAuth Token 和 Client ID
访问 twitchtokengenerator.com，选择 'Bot Token' 并勾选 chat:read 和 chat:write 权限。复制生成的 Access Token。此外，从 Twitch Developer Console (dev.twitch.tv/console) 获取你的 Client ID。
3
配置并启动
在 ~/.openclaw/openclaw.json 中添加 Twitch 频道配置，填入你的 username、accessToken、clientId 和目标频道。运行 'openclaw start' 启动 Gateway，然后在 Twitch 频道中 @提及机器人以验证是否正常工作。
Twitch 配置示例
config.json
{
"channels": {
"twitch": {
"enabled": true,
"username": "mybotname",
"accessToken": "oauth:abc123...",
"clientId": "your-client-id",
"channel": "targetchannel",
"allowFrom": ["123456789"]
}
}
}Twitch 深入了解
架构概述
OpenClaw 使用 IRC 协议连接到 Twitch 聊天。Gateway 通过你的 OAuth Token 进行身份验证，加入指定频道并监听消息。
当观众发送触发机器人的消息时（默认通过 @提及触发），Gateway 会将消息转发给你的 AI 代理。响应内容会发送回同一个 Twitch 频道，并自动按每条消息 500 个字符进行分割，以符合 Twitch 的限制。
每个账号映射到一个唯一的会话键 (agent:<agentId>:twitch:<accountName>)，因此多个账号可以在同一个 Gateway 下独立运行。由于 Twitch 聊天不支持渲染 Markdown，发送前会自动去除 Markdown 格式。
回复会确定性地路由回消息来源的 Twitch 频道。
超过 500 个字符的消息会自动在单词边界处分割。
获取凭据
你需要三个凭据来建立连接：OAuth Access Token、Client ID 和机器人的用户名。
1. 访问 twitchtokengenerator.com 并选择 'Bot Token'。
2. 授权该 Token 的 chat:read 和 chat:write 权限。
3. 复制生成的 Access Token（以 'oauth:' 开头）。
4. 获取 Client ID：访问 Twitch Developer Console (dev.twitch.tv/console)，注册一个应用程序，然后复制其 Client ID。
Access Token 也可以通过 OPENCLAW_TWITCH_ACCESS_TOKEN 环境变量提供。如果环境变量和配置文件中同时设置了该值，配置文件的值优先。
terminal
# Environment variable (default account only)
export OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...切勿将 Access Token 提交到版本控制系统。请使用环境变量或密钥管理工具。
从 twitchtokengenerator.com 获取的 Token 会在数小时后过期。对于长期运行的机器人，请配置自动刷新。
Token 自动刷新
从 Twitch Token Generator 获取的 Token 会在数小时后过期。对于生产环境的机器人，请配置 Token 自动刷新以避免服务中断。
1. 在 Twitch Developer Console (dev.twitch.tv/console) 注册一个应用程序。
2. 记录 Client Secret，并使用 OAuth Authorization Code 流程获取 Refresh Token。
3. 在账号配置中添加 clientSecret 和 refreshToken。
机器人会在 Token 过期前自动刷新，并记录刷新事件以供监控。
openclaw.json
{
"channels": {
"twitch": {
"accessToken": "oauth:abc123...",
"clientId": "your-client-id",
"clientSecret": "your-client-secret",
"refreshToken": "your-refresh-token"
}
}
}如果未配置自动刷新，每次 Token 过期时你都需要手动替换。
基于用户 ID 的访问控制
Twitch 用户名可以随时更改，这会带来冒充风险。OpenClaw 强烈建议使用数字用户 ID 而非用户名进行访问控制。
allowFrom 字段接受一个永久性 Twitch 用户 ID 的数组。只有 ID 在此列表中的用户才能与机器人交互，其他用户的消息会被静默忽略。
你可以使用 Twitch API 或第三方工具（如 twitchinsights.net）查询用户的数字 ID。
openclaw.json
{
"channels": {
"twitch": {
"allowFrom": ["123456789", "987654321"]
}
}
}用户 ID 是永久性的，不受用户名更改的影响。出于安全考虑，始终优先使用 ID 而非用户名。
基于角色的访问控制
除了（或代替）显式的用户 ID 白名单，你还可以按 Twitch 聊天角色限制访问。allowedRoles 字段接受一个角色名称数组。
可用角色：
• moderator — 频道管理员
• owner — 频道主播
• vip — VIP 用户
• subscriber — 频道订阅者
• all — 频道中的所有人（请谨慎使用）
设置 allowedRoles 后，只有拥有至少一个匹配角色的用户才能与机器人交互。
openclaw.json
{
"channels": {
"twitch": {
"allowedRoles": ["moderator", "vip"]
}
}
}将 allowedRoles 设置为 ['all'] 会允许所有观众与机器人交互，在繁忙的频道中可能会消耗大量 AI 配额。
@提及要求
默认情况下，机器人只在聊天中被明确 @提及时才会回复（requireMention: true）。这可以防止机器人在繁忙的频道中回复每条消息。
你可以将 requireMention 设置为 false 来禁用此行为，使机器人回复所有来自允许用户的消息。这适用于专用机器人频道或低流量的直播。
openclaw.json
{
"channels": {
"twitch": {
"requireMention": false
}
}
}在繁忙的频道中建议保持 requireMention 开启，以避免机器人被大量聊天消息淹没。
多账号配置
OpenClaw 支持同时运行多个 Twitch 机器人账号。每个账号需要各自的 OAuth Token，并映射到一个频道。
使用 accounts.<name> 模式配置多个账号。每个账号可以拥有独立的访问控制、@提及要求和 Token 刷新设置。
openclaw.json
{
"channels": {
"twitch": {
"accounts": {
"gaming-bot": {
"username": "gamingbot",
"accessToken": "oauth:token1...",
"clientId": "client-id-1",
"channel": "gamingchannel",
"allowedRoles": ["subscriber"]
},
"mod-bot": {
"username": "modbot",
"accessToken": "oauth:token2...",
"clientId": "client-id-2",
"channel": "modchannel",
"allowFrom": ["111222333"]
}
}
}
}
}代理工具动作
AI 代理可以使用 twitch 工具动作主动向 Twitch 频道发送消息。这使得代理能够在没有用户触发的情况下发送通知、警报或定时消息。
该动作需要一条消息内容和一个目标频道（以 # 为前缀）。
agent-action.json
{
"action": "twitch",
"params": {
"message": "Hello Twitch!",
"to": "#mychannel"
}
}工具动作遵循与常规聊天消息相同的速率限制。
速率限制与消息约束
Twitch 对聊天消息有严格的速率限制。OpenClaw 使用 Twitch 内置的速率限制机制，不添加额外的限制层。
标准（未验证）账号：
• 每 30 秒 20 条消息（非管理员/VIP）
• 每 30 秒 100 条消息（管理员/VIP/主播）
已验证的机器人账号：
• 每 30 秒 7,500 条消息
所有账号在每个频道限制为每秒 1 条消息。超出限制的消息会被 Twitch 静默丢弃。
单条消息最大长度为 500 个字符。更长的回复会自动在单词边界处分割。
如果机器人超出速率限制，Twitch 会静默丢弃消息而不返回任何错误。请在繁忙频道上监控机器人的活动。
Twitch 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 启用或禁用 Twitch 频道 |
| username | string | "" | 机器人使用的 Twitch 账号名称 |
| accessToken | string | "" | 具有 chat:read 和 chat:write 权限的 OAuth Token（必须以 'oauth:' 开头） |
| clientId | string | "" | 从 Twitch Developer Console 获取的 Client ID |
| channel | string | "" | 要加入的目标 Twitch 频道（必填） |
| clientSecret | string | "" | 用于 Token 自动刷新的 Client Secret |
| refreshToken | string | "" | 用于 Token 自动续期的 Refresh Token |
| expiresIn | number | — | Token 过期时间（秒） |
| obtainmentTimestamp | number | — | 当前 Token 获取时间的时间戳（毫秒） |
| allowFrom | string[] | [] | 用于严格访问限制的 Twitch 用户 ID 白名单 |
| allowedRoles | string[] | [] | 基于角色的访问控制（moderator、owner、vip、subscriber、all） |
| requireMention | boolean | true | 机器人是否需要被 @提及才会回复 |
| accounts.<id>.username | string | "" | 多账号模式下特定账号的机器人用户名 |
| accounts.<id>.accessToken | string | "" | 特定账号的 OAuth Token |
| accounts.<id>.channel | string | "" | 特定账号的目标频道 |
enabled
Type: booleanDefault: true
启用或禁用 Twitch 频道
username
Type: stringDefault: ""
机器人使用的 Twitch 账号名称
accessToken
Type: stringDefault: ""
具有 chat:read 和 chat:write 权限的 OAuth Token（必须以 'oauth:' 开头）
clientId
Type: stringDefault: ""
从 Twitch Developer Console 获取的 Client ID
channel
Type: stringDefault: ""
要加入的目标 Twitch 频道（必填）
clientSecret
Type: stringDefault: ""
用于 Token 自动刷新的 Client Secret
refreshToken
Type: stringDefault: ""
用于 Token 自动续期的 Refresh Token
expiresIn
Type: numberDefault: —
Token 过期时间（秒）
obtainmentTimestamp
Type: numberDefault: —
当前 Token 获取时间的时间戳（毫秒）
allowFrom
Type: string[]Default: []
用于严格访问限制的 Twitch 用户 ID 白名单
allowedRoles
Type: string[]Default: []
基于角色的访问控制（moderator、owner、vip、subscriber、all）
requireMention
Type: booleanDefault: true
机器人是否需要被 @提及才会回复
accounts.<id>.username
Type: stringDefault: ""
多账号模式下特定账号的机器人用户名
accounts.<id>.accessToken
Type: stringDefault: ""
特定账号的 OAuth Token
accounts.<id>.channel
Type: stringDefault: ""
特定账号的目标频道
Twitch 常见问题
Twitch 故障排查
机器人无响应 — 不回复消息
allowFrom 列表中可能未包含你的用户 ID，或者机器人未检测到 @提及。
确认你的 Twitch 用户 ID（不是用户名）已添加到 allowFrom 数组中。测试时可以尝试将 allowedRoles 设置为 ['all']。如果 requireMention 为 true，请检查你是否正确地 @提及了机器人。
启动时身份验证失败
OAuth Token 无效、已过期，或缺少必要的权限。
确保 Token 以 'oauth:' 开头，并具有 chat:read 和 chat:write 权限。在 twitchtokengenerator.com 生成新的 Token。查看 Gateway 日志获取具体的错误信息。
Token 刷新不生效
clientSecret 或 refreshToken 缺失或不正确。
确保配置中同时提供了 clientSecret 和 refreshToken。Client Secret 必须与在 dev.twitch.tv/console 注册的应用程序匹配。查看日志获取 Token 刷新错误的详细信息。
消息被静默丢弃
机器人超出了 Twitch 的速率限制。
降低消息发送频率。标准账号限制为每 30 秒 20 条消息（管理员为 100 条）。考虑申请已验证的机器人身份以获取更高限制。检查机器人是否生成了过长的回复导致产生大量分割消息。
机器人已连接但未加入频道
频道名称可能不正确，或者账号已被该频道封禁。
确认频道名称正确（小写，不带 # 前缀）。查看 Gateway 日志中的 JOIN 错误。确保机器人账号未在目标频道中被封禁或禁言。