Twitch

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

安装

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 Bot 账号

为 Bot 创建专用 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

如果两者均已设置，配置优先（环境变量仅作为默认账号的回退值）。

启动 Gateway 网关

openclaw gateway run

添加访问控制（allowFrom 或 allowedRoles），防止未授权用户触发 Bot。requireMention 默认为 true。

最小配置：

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

工作原理

由 Gateway 网关拥有的 Twitch 频道。
确定性路由：回复始终发回消息来源的 Twitch 频道。
每个已加入的频道都映射到一个隔离的群组会话键 agent:<agentId>:twitch:group:<channel>。
username 是 Bot 的账号（用于身份验证），channel 是要加入的聊天室。每个账号条目只加入一个频道。
令牌无论是否带有 oauth: 前缀均可使用；OpenClaw 会规范化这两种形式（设置向导要求使用 oauth: 形式）。

入站持久性

OpenClaw 会在正常分发前，将每条已接受的 Twitch 聊天消息持久化到队列。待处理或可重试的消息在 Gateway 网关重启后仍会保留，并按已配置的频道串行处理；只要存在活动或保留的完成记录，就会使用 Twitch 的消息 ID 阻止重复的队列条目。 Twitch 聊天不会在客户端接受 PRIVMSG 后重放它。这可以防范从本地接受消息到分发消息期间的崩溃窗口，但无法恢复在持久化接纳前错过的消息。如果追加队列本身失败，OpenClaw 会记录该故障；重新连接不会要求 Twitch 重新发送该消息。

令牌刷新（可选）

Twitch Token Generator 生成的令牌无法由 OpenClaw 刷新——过期后请重新生成（有效期为几小时；无需注册应用）。如需自动刷新，请在 Twitch Developer Console 创建自己的应用，并添加：

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

两者均已设置时，插件会使用可刷新身份验证提供商，在令牌过期前进行续期，并记录每次刷新。如果没有 refreshToken，则记录 token refresh disabled (no refresh token)；如果没有 clientSecret，则回退到静态（不可刷新）令牌。

多账号支持

使用 channels.twitch.accounts 配置各账号的凭据。有关共用模式，请参阅配置。示例（一个 Bot 账号用于两个频道）：

{
  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 允许列表（最安全）
基于角色
禁用 @提及要求

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

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

默认情况下，requireMention 为 true。要响应所有获准的消息：

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

为什么使用用户 ID？ 用户名可以更改，从而可能被冒充。用户 ID 是永久不变的。使用用户名转 ID 工具查找你的用户 ID。

故障排查

首先运行诊断命令：

openclaw doctor
openclaw channels status --probe

Bot 不响应消息

检查访问控制： 确保你的用户 ID 位于 allowFrom 中，或者临时移除 allowFrom 并设置 allowedRoles: ["all"] 进行测试。
检查提及门控： 使用 requireMention: true（默认值）时，消息必须 @提及 Bot 用户名。
检查 Bot 是否在频道中： Bot 只会加入 channel 中指定的频道。

令牌问题

“连接失败”或身份验证错误：

确认 accessToken 是 OAuth 访问令牌值（oauth: 前缀可选）
检查令牌是否具有 chat:read 和 chat:write 权限范围
如果使用令牌刷新，请确认已设置 clientSecret 和 refreshToken

令牌刷新不起作用

检查日志中的刷新事件：

对 mybot 使用环境变量令牌来源
用户 123456 的访问令牌已刷新（将在 14400s 后过期）

如果看到 token refresh disabled (no refresh token)：

确保已提供 clientSecret
确保已提供 refreshToken

配置

账号配置

string

必填

Bot 用户名（用于身份验证的账号）。

string

必填

具有 chat:read 和 chat:write 权限范围的 OAuth 访问令牌（默认账号可使用配置或环境变量）。

string

必填

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

string

必填

要加入的频道。

boolean

默认值:"true"

启用此账号。

string

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

string

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

number

令牌过期时间，以秒为单位（刷新跟踪）。

number

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

string[]

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

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

基于角色的访问控制。

boolean

默认值:"true"

要求使用 @提及才能触发 Bot。

string

覆盖此账号的出站回复前缀。

提供商选项

channels.twitch.enabled - 启用/禁用频道启动
channels.twitch.username / accessToken / clientId / channel - 简化的单账号配置（隐式 default 账号；优先于 accounts.default）
channels.twitch.accounts.<accountName> - 多账号配置（包括上述所有账号字段）
channels.twitch.defaultAccount - 哪个账号名称为默认账号
channels.twitch.markdown.tables - Markdown 表格渲染模式（off | bullets | code | block）

完整示例：

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

工具操作

智能体可以通过消息工具的 send 操作发送 Twitch 消息：

{
  channel: "twitch",
  action: "send",
  to: "#mychannel",
  message: "Hello Twitch!",
}

to 是可选项，默认使用账号已配置的 channel。

安全与运维

将令牌视同密码 — 切勿将令牌提交到 git。
对于长期运行的 Bot，使用自动令牌刷新。
使用用户 ID 允许列表而非用户名进行访问控制。
监控日志中的令牌刷新事件和连接状态。
尽可能缩小令牌权限范围 — 仅请求 chat:read 和 chat:write。
如果遇到问题：确认没有其他进程占用该会话后，重启 Gateway 网关。

限制

每条消息不超过 500 个字符；较长的回复会在单词边界处分块。
发送前会移除 Markdown 格式（Twitch 聊天使用纯文本；换行符会转换为空格）。
OpenClaw 本身不添加速率限制；Twurple 聊天客户端负责处理 Twitch 的速率限制。

概览

消息平台

Developer and self-hosted

Regional platforms

配置

安装

快速设置

工作原理

入站持久性

令牌刷新（可选）

多账号支持

访问控制

故障排查

配置

账号配置

提供商选项

工具操作

安全与运维

限制

相关内容

​安装

​快速设置

​工作原理

​入站持久性

​令牌刷新（可选）

​多账号支持

​访问控制

​故障排查

​配置

​账号配置

​提供商选项

​工具操作

​安全与运维

​限制

​相关内容

安装

快速设置

工作原理

入站持久性

令牌刷新（可选）

多账号支持

访问控制

故障排查

配置

账号配置

提供商选项

工具操作

安全与运维

限制

相关内容