本页内容
本页内容
开发者和自托管
Twitch
通过 Twurple 客户端通过 Twitch 的聊天 (IRC) 界面支持 Twitch 聊天。 OpenClaw 以 Twitch 机器人帐户登录,为每个配置的帐户加入一个频道,并在该频道中回复。
安装
Twitch 作为官方插件提供;它不属于核心安装的一部分。
npm 注册表
本地结账
plugins install 会注册并启用该插件。在 openclaw onboard 或 openclaw channels add 期间选择 Twitch 会按需安装它。使用不带版本号的软件包名称可跟随当前发布版本;仅在需要可复现安装时才固定到精确版本。需要 OpenClaw 2026.4.10 或更新版本。
详细信息:插件
快速设置
安装插件
见上面的 安装。
创建 Twitch 机器人帐户
为机器人创建一个专用的 Twitch 账户(或者使用现有账户)。
生成凭证
- 选择 Bot Token
- 确认已选择
chat:read和chat:write作用域 - 复制 Client ID 和 Access Token
查找您的 Twitch 用户 ID
使用 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 将用户名转换为 Twitch 用户 ID。
配置令牌
- 环境变量:
OPENCLAW_TWITCH_ACCESS_TOKEN=...(仅默认账户) - 或配置:
channels.twitch.accessToken
如果两者都设置了,则以配置为准(环境变量仅作为默认账户的备用项)。
启动网关
最小配置:
它是什么
- 由 Gateway 拥有的 Twitch 频道。
- 回复始终返回到消息来源的 Twitch 通道。
- 每个已加入的频道都会映射到一个隔离的组会话密钥
agent:<agentId>:twitch:group:<channel>。 username是机器人的账号(进行身份验证),channel是要加入的聊天房间。一个账号条目只加入一个频道。- Token 带或不带
oauth:前缀都可以;OpenClaw 会按两种方式进行规范化(设置向导期望的是oauth:格式)。
入站持久性
OpenClaw 会在正常分发之前,将每条已接受的 Twitch 聊天消息持久化入队。待处理或可重试的消息在 Gateway 重启后仍会保留,保持为已配置频道的序列化状态,并使用 Twitch 的消息 ID 来抑制重复的队列条目,只要活动的或保留的完成记录存在即可。
Twitch 聊天在客户端接受 PRIVMSG 后不会重放该消息。这可以保护本地“接受到分发”之间的崩溃窗口,但无法恢复在持久化接纳之前遗漏的消息。如果队列追加本身失败,OpenClaw 会记录该失败;重新连接不会要求 Twitch 重新发送该消息。
令牌刷新(可选)
来自 Twitch Token Generator 的令牌无法被 OpenClaw 刷新 - 过期时请重新生成(它们通常只会持续几个小时;无需应用注册)。
对于自动刷新,请在 Twitch 开发人员 Console 创建您自己的应用程序并添加:
当两者都设置后,插件会使用可刷新的认证提供者,在令牌过期前自动续期,并记录每次刷新。若没有 refreshToken,它会记录 token refresh disabled (no refresh token);若没有 clientSecret,则会回退到静态(不可刷新的)令牌。
多账户支持
使用 channels.twitch.accounts 配合每个账户各自的凭据。请参阅 配置 了解通用模式。
示例(一个机器人账户在两个频道中):
访问控制
allowFrom 是 Twitch 用户 ID 的硬允许列表。设置时,allowedRoles 被忽略;保留 allowFrom 未设置以使用基于角色的访问。
在设置向导中,Disabled 通过写入空的 allowFrom 列表来阻止所有聊天。 Open 删除用户 ID 白名单并允许所有角色。 Allowlist 保留一个非空用户 ID 列表;否则,它会删除空覆盖并允许版主和 VIP。所有三个选择都需要 @mention.
选择 Open 或 Disabled 将丢弃任何以前的用户 ID。切换回 Allowlist 不会恢复它们;再次配置allowFrom,限制特定ID的访问。
没有 allowFrom 且 allowedRoles 为空或不存在的现有配置保持打开状态。没有自动迁移,因为这些值不记录是否有意禁用。在设置中重新选择 Disabled 或配置 allowFrom: [] 以阻止聊天。
可用角色: "moderator"、"owner"、"vip"、"subscriber"、"all"。
用户 ID 许可名单(最安全)
基于角色
禁用 @mention 要求
默认情况下,requireMention 为 true。若要响应所有允许的消息:
故障排查
执行身份审核
启用 执行身份收集 后,受信任的本机 Twitch 插件将运行归因于本机 Twitch 发送者,范围为配置的帐户。审计存储不透明身份,而不是原始 Twitch 用户 ID。主持人等角色授权访问;它们不会取代发件人的身份。即使角色或开放策略允许回复,丢失的本机用户 ID 仍然未知。外部插件安装不会通过此路径获得可信参与者证据。审计收集永远不会改变这些访问决策。
连接和回复
首先,运行诊断命令:
机器人不回复消息
- 检查访问控制: 检查您的用户ID是否在
allowFrom中,或者暂时删除allowFrom并设置allowedRoles: ["all"]进行测试。 - 检查提及门槛: 在
requireMention: true(默认)时,消息必须 @mention 机器人用户名。 - 检查机器人是否在频道中: 机器人只会加入
channel中指定的频道。
代币问题
“连接失败”或身份验证错误:
- 验证
accessToken是否为 OAuth 访问令牌值(oauth:前缀可选) - 检查令牌是否具有
chat:read和chat:write权限范围 - 如果使用令牌刷新,请验证已设置
clientSecret和refreshToken
令牌刷新不起作用
检查日志中的刷新事件:
如果你看到 token refresh disabled (no refresh token):
- 提供
clientSecret - 提供
refreshToken
配置
账户配置
usernamestring必填机器人用户名(用于认证的账户)。
accessTokenstring必填具有 chat:read 和 chat:write 权限的 OAuth 访问令牌(默认账户的配置项或环境变量)。
clientIdstring必填Twitch 客户端 ID(来自 Token Generator 或你的应用)。在 schema 中是可选项,但连接时必需。
channelstring必填要加入的频道。
enabledbooleandefault: true启用此账户。
clientSecretstring可选:用于自动刷新令牌。
refreshTokenstring可选:用于自动刷新令牌。
expiresInnumber令牌过期时间(秒)(刷新跟踪)。
obtainmentTimestampnumber获取令牌时的时间戳(刷新跟踪)。
allowFromstring[]用户 ID 允许列表。设置后将忽略角色。
allowedRolesArray<"moderator" | "owner" | "vip" | "subscriber" | "all">基于角色的访问控制。
requireMentionbooleandefault: true需要 @mention 才会触发机器人。
responsePrefixstring此账户的外发响应前缀覆盖值。
提供者选项
channels.twitch.enabled- Enable/disable 通道启动channels.twitch.username/accessToken/clientId/channel- 使用隐式default账户的简化单账户配置channels.twitch.accounts.<accountName>- 多账户配置(包含上述所有账户字段);不要与顶层账户凭据结合使用channels.twitch.defaultAccount- 默认账户的名称channels.twitch.markdown.tables- Markdown 表格渲染模式(off|bullets|code|block)
完整示例:
工具动作
代理可以通过消息工具send操作发送Twitch消息:
在 Twitch 对话中回复时,省略 to 以使用当前对话。没有当前对话的消息工具调用和 CLI 发送需要明确的目标。直接网关 message.action 发送可以省略 to 以使用所选帐户的配置 channel。
安全与运维
- 将令牌视为密码 - 绝不要将令牌提交到 git。
- 为长期运行的机器人使用自动令牌刷新。
- 使用用户 ID 白名单 而不是用户名进行访问控制。
- 监控日志 中的令牌刷新事件和连接状态。
- 尽量缩小令牌范围 - 只请求
chat:read和chat:write。 - 如果卡住:在确认没有其他进程占用该会话后重启网关。
限制
- 每条消息 500 个字符;更长的回复会在单词边界处分块。
- Markdown 会在发送前被去除(Twitch 聊天是纯文本;换行会变成空格)。
- 剥离 Markdown 后变空的文本,例如
---,将被记录为故意不发送,并且不计为已发送消息。 - OpenClaw 本身不增加任何限流;Twurple 聊天客户端会处理 Twitch 的速率限制。
相关内容
- 通道路由 — 消息的会话路由
- Channels Overview — 所有支持的通道
- Groups — 群聊行为和提及门控
- 配对 — DM 身份验证和配对流程
- Security — 访问模型和强化