Twitch

通过 Twurple 客户端，使用 Twitch 的聊天（IRC）接口支持 Twitch 聊天。OpenClaw 以 Twitch 机器人账号登录，加入每个已配置账号对应的一个频道，并在该频道中回复。

安装

Twitch 作为官方插件提供；它不属于核心安装的一部分。

npm 注册表
本地检出

openclaw plugins install @openclaw/twitch

openclaw plugins install ./path/to/local/twitch-plugin

plugins install 会注册并启用该插件。在 openclaw onboard 或 openclaw channels add 期间选择 Twitch 会按需安装它。使用不带版本号的软件包名称可跟随当前发布版本；仅在需要可复现安装时才固定到精确版本。需要 OpenClaw 2026.4.10 或更新版本。详情：插件。

快速设置

安装插件

见上面的安装。

创建 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/ 将用户名转换为 Twitch 用户 ID。

配置令牌

环境变量：OPENCLAW_TWITCH_ACCESS_TOKEN=...（仅默认账户）
或配置：channels.twitch.accessToken

如果两者都设置了，则以配置为准（环境变量仅作为默认账户的备用项）。

启动网关

openclaw gateway run

添加访问控制（allowFrom 或 allowedRoles）以防止未授权用户触发机器人。requireMention 默认值为 true。

最小配置：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // 机器人的 Twitch 账户（用于身份验证）
      accessToken: "oauth:abc123...", // OAuth 访问令牌（或使用 OPENCLAW_TWITCH_ACCESS_TOKEN 环境变量）
      clientId: "xyz789...", // 来自 Token Generator 的 Client ID
      channel: "yourchannel", // 要加入哪个 Twitch 频道的聊天（必填）
      allowFrom: ["123456789"], //（推荐）仅允许你的 Twitch 用户 ID
    },
  },
}

它是什么

由 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 开发者控制台创建你自己的应用，并添加：

{
  channels: {
    twitch: {
      username: "openclaw",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "yourchannel",
      clientSecret: "your_client_secret",
      refreshToken: "your_refresh_token",
    },
  },
}

当两者都设置后，插件会使用可刷新的认证提供者，在令牌过期前自动续期，并记录每次刷新。若没有 refreshToken，它会记录 token refresh disabled (no refresh token)；若没有 clientSecret，则会回退到静态（不可刷新的）令牌。

多账户支持

使用 channels.twitch.accounts 配合每个账户各自的凭据。请参阅配置了解通用模式。示例（一个机器人账户在两个频道中）：

{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "yourchannel",
        },
        channel2: {
          username: "openclaw",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel",
        },
      },
    },
  },
}

每个账户条目都需要自己的 accessToken（环境变量只覆盖默认账户）。一个账户只会加入一个频道，因此加入两个频道就需要两个账户。channels.twitch.defaultAccount 用于选择哪个账户作为默认账户。

访问控制

allowFrom 是 Twitch 用户 ID 的硬性允许列表。设置后，allowedRoles 会被忽略；若要改用基于角色的访问控制，请不要设置 allowFrom。 可用角色： "moderator"、"owner"、"vip"、"subscriber"、"all"。

用户 ID 允许列表（最安全）
基于角色
禁用 @mention 要求

{
  channels: {
    twitch: {
      accounts: {
        default: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          channel: "yourchannel",
          allowFrom: ["123456789", "987654321"],
        },
      },
    },
  },
}

{
  channels: {
    twitch: {
      accounts: {
        default: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          channel: "yourchannel",
          allowedRoles: ["moderator", "vip"],
        },
      },
    },
  },
}

默认情况下，requireMention 为 true。若要响应所有允许的消息：

{
  channels: {
    twitch: {
      accounts: {
        default: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          channel: "yourchannel",
          requireMention: false,
        },
      },
    },
  },
}

为什么使用用户 ID？ 用户名可以更改，可能导致冒充。用户 ID 是永久的。可通过用户名转 ID 转换器查找你的 ID。

故障排查

首先，运行诊断命令：

openclaw doctor
openclaw channels status --probe

机器人不响应消息

检查访问控制： 确保你的用户 ID 在 allowFrom 中，或者临时移除 allowFrom 并将 allowedRoles 设置为 ["all"] 进行测试。
检查提及门槛： 在 requireMention: true（默认）时，消息必须 @mention 机器人用户名。
检查机器人是否在频道中： 机器人只会加入 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

配置

账户配置

string

required

机器人用户名（用于认证的账户）。

string

required

具有 chat:read 和 chat:write 权限的 OAuth 访问令牌（默认账户的配置项或环境变量）。

string

required

Twitch 客户端 ID（来自 Token Generator 或你的应用）。在 schema 中是可选项，但连接时必需。

string

required

要加入的频道。

boolean

default:"true"

启用此账户。

string

可选：用于自动刷新令牌。

string

可选：用于自动刷新令牌。

number

令牌过期时间（秒）（刷新跟踪）。

number

获取令牌时的时间戳（刷新跟踪）。

string[]

用户 ID 允许列表。设置后将忽略角色。

Array<"moderator" | "owner" | "vip" | "subscriber" | "all">

基于角色的访问控制。

boolean

default:"true"

需要 @mention 才会触发机器人。

string

此账户的外发响应前缀覆盖值。

提供者选项

channels.twitch.enabled - 启用／禁用频道启动
channels.twitch.username / accessToken / clientId / channel - 使用隐式 default 账户的简化单账户配置
channels.twitch.accounts.<accountName> - 多账户配置（包含上述所有账户字段）；不要与顶层账户凭据结合使用
channels.twitch.defaultAccount - 默认账户的名称
channels.twitch.markdown.tables - Markdown 表格渲染模式（off | bullets | code | block）

完整示例：

{
  channels: {
    twitch: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        default: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "yourchannel",
          clientSecret: "secret123...",
          refreshToken: "refresh456...",
          allowFrom: ["123456789"],
        },
        second: {
          username: "mybot",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "your_channel",
          enabled: true,
          expiresIn: 14400,
          obtainmentTimestamp: 1706092800000,
          allowedRoles: ["moderator"],
        },
      },
    },
  },
}

## 工具操作

该代理可以通过消息工具的 `send` 操作发送 Twitch 消息：

```json5
{
  channel: "twitch",
  action: "send",
  to: "#mychannel",
  message: "你好，Twitch！",
}

to 是可选的，默认值为账户已配置的 channel

安全与运维

将令牌视为密码 - 绝不要将令牌提交到 git。
为长期运行的机器人使用自动令牌刷新。
使用用户 ID 白名单 而不是用户名进行访问控制。
监控日志 中的令牌刷新事件和连接状态。
尽量缩小令牌范围 - 只请求 chat:read 和 chat:write。
如果卡住：在确认没有其他进程占用该会话后重启网关。

限制

每条消息 500 个字符；更长的回复会在单词边界处分块。
Markdown 会在发送前被去除（Twitch 聊天是纯文本；换行会变成空格）。
OpenClaw 本身不增加任何限流；Twurple 聊天客户端会处理 Twitch 的速率限制。

概览

主流消息平台

开发者与自托管

区域平台

配置

安装

快速设置

它是什么

入站持久性

令牌刷新（可选）

多账户支持

访问控制

故障排查

配置

账户配置

提供者选项

安全与运维

限制

相关内容

​安装

​快速设置

​它是什么

​入站持久性

​令牌刷新（可选）

​多账户支持

​访问控制

​故障排查

​配置

​账户配置

​提供者选项

​安全与运维

​限制

​相关内容

安装

快速设置

它是什么

入站持久性

令牌刷新（可选）

多账户支持

访问控制

故障排查

配置

账户配置

提供者选项

安全与运维

限制

相关内容