Twitch

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

安装¶

Twitch 作为官方插件提供；它不包含在核心安装中。

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 或更高版本。

详细信息：插件

快速设置¶

1. 安装插件

见上文安装。

2. 创建 Twitch 机器人账号

为机器人创建一个专用的 Twitch 账号（或使用现有账号）。

3. 生成凭据

使用 Twitch 令牌生成器：

• 选择 Bot Token
• 确认已选择作用域 chat:read 和 chat:write
• 复制 Client ID 和 Access Token

4. 查找你的 Twitch 用户 ID

使用 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 将用户名转换为 Twitch 用户 ID。

5. 配置令牌

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

如果两者都设置了，配置优先（环境变量仅为默认账号的备用方案）。

6. 启动网关

openclaw gateway run

最小配置：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Bot's Twitch account (authenticates)
      accessToken: "oauth:abc123...", // OAuth access token (or use OPENCLAW_TWITCH_ACCESS_TOKEN env var)
      clientId: "xyz789...", // Client ID from Token Generator
      channel: "yourchannel", // Which Twitch channel's chat to join (required)
      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
    },
  },
}

这是什么¶

• 一条由网关拥有的 Twitch 频道。
• 确定性路由：回复始终返回到消息来源的 Twitch 频道。
• 每个已加入的频道映射到一个独立的组会话密钥 agent:<agentId>:twitch:group:<channel>。
• username 是机器人的账号（用于身份验证），channel 是要加入的聊天室。每个账号条目恰好加入一个频道。
• 令牌无论是否带有 oauth: 前缀均可使用；OpenClaw 会对两种形式进行规范化（设置向导期望 oauth: 形式）。

入站持久性¶

OpenClaw 在正常分发之前，将每条已接受的 Twitch 聊天消息持久化入队。待处理或可重试的消息在网关重启后仍然存在，并针对所配置的频道保持序列化；在存在活动或保留的完成记录时，使用 Twitch 的消息 ID 来抑制重复的队列条目。

Twitch 聊天不会在客户端接受 PRIVMSG 后重放该消息。这保护了本地从接受到分发的崩溃窗口，但无法恢复在持久化接纳之前错过的消息。如果队列追加本身失败，OpenClaw 会记录该失败；重新连接不会要求 Twitch 重新发送该消息。

令牌刷新（可选）¶

来自 Twitch 令牌生成器 的令牌无法由 OpenClaw 刷新——过期时请重新生成（它们只持续几小时；无需注册应用）。

如需自动刷新，请在 Twitch Developer Console 创建自己的应用，并添加：

{
  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",
        },
      },
    },
  },
}

访问控制¶

allowFrom 是 Twitch 用户 ID 的硬性允许列表。设置后，allowedRoles 将被忽略；不设置 allowFrom 以改用基于角色的访问。

在设置向导中，Disabled（禁用） 通过写入空的 allowFrom 列表来阻止所有聊天。Open（开放） 移除用户 ID 允许列表并允许所有角色。Allowlist（允许列表） 保留非空的用户 ID 列表；否则，它会移除空的覆盖项并允许管理员和 VIP。所有三个选项都需要 @提及。

选择 Open（开放） 或 Disabled（禁用） 会丢弃之前的任何用户 ID。切换回 Allowlist（允许列表） 不会恢复这些 ID；请重新配置 allowFrom 以限制特定 ID 的访问。

现有配置如果没有 allowFrom 且 allowedRoles 为空或不存在，则保持开放。由于这些值不记录是否原本打算禁用，因此不会自动迁移。在设置中重新选择 Disabled（禁用） 或配置 allowFrom: [] 以阻止聊天。

可用角色： "moderator"、"owner"、"vip"、"subscriber"、"all"。

{
  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"],
        },
      },
    },
  },
}

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

故障排除¶

执行身份审计¶

启用执行身份收集后，受信任的原生 Twitch 插件会将运行归属于原生 Twitch 发送者，范围限定为已配置的账户。审计存储的是不透明身份，而不是原始 Twitch 用户 ID。诸如 moderator 之类的角色用于授权访问；它们不会替代发送者的身份。即使角色或开放策略允许回复，缺失的原生用户 ID 仍保持未知。外部插件安装不会通过此路径获得受信任参与者证据。审计收集永远不会更改这些访问决策。

连接与回复¶

首先，运行诊断命令：

openclaw doctor
openclaw channels status --probe

Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)

配置¶

账户配置¶

username string (path) required

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

accessToken string (path) required

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

clientId string (path) required

Twitch Client ID（来自 Token Generator 或你的应用）。模式中可选，但连接时必需。

channel string (path) required

要加入的频道。

enabled boolean (path)

启用此账户。

clientSecret string (path)

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

refreshToken string (path)

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

expiresIn number (path)

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

obtainmentTimestamp number (path)

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

allowFrom string[] (path)

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

<ParamField path="allowedRoles" type='Array<"moderator" | "owner" | "vip" | "subscriber" | "all">'> 基于角色的访问控制。

requireMention boolean (path)

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

responsePrefix string (path)

此账户的出站响应前缀覆盖。

提供商选项¶

• 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 消息：

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

当在 Twitch 会话中回复时，省略 to 以使用当前会话。没有当前会话的 Message-tool 调用以及 CLI 发送需要显式目标。直接 Gateway message.action 发送可以省略 to，以使用所选账户配置的 channel。

安全与运维¶

• 将 token 视为密码 - 切勿将 token 提交到 git。
• 对长时间运行的机器人使用自动 token 刷新。
• 使用用户 ID 允许列表 而不是用户名进行访问控制。
• 监控日志 中的 token 刷新事件和连接状态。
• 最小化 token 权限 - 仅请求 chat:read 和 chat:write。
• 如果卡住：在确认没有其他进程拥有该会话后，重启网关。

限制¶

• 每条消息 500 个字符；更长的回复会在单词边界处分块。
• 发送前会移除 Markdown（Twitch 聊天为纯文本；换行符变为空格）。
• 在移除 Markdown 后变为空的内容（例如 ---）会被记录为有意未发送，并且不计为已送达消息。
• OpenClaw 本身不添加速率限制；Twurple 聊天客户端处理 Twitch 速率限制。

相关¶

• 频道路由 — 消息的会话路由
• 频道概览 — 所有支持的频道
• 群组 — 群聊行为和提及门控
• 配对 — DM 身份验证和配对流程
• 安全 — 访问模型和加固