Twitch（外掛）

透過 IRC 連接的 Twitch 聊天支援。OpenClaw 以 Twitch 使用者（機器人帳號）身分連接以接收和發送頻道中的訊息。

需要外掛

Twitch 是外掛式的，不包含在核心安裝中。

透過 CLI（npm 套件庫）安裝：

openclaw plugins install @openclaw/twitch

本機 checkout（在 git repo 中開發）：

openclaw plugins install ./extensions/twitch

詳情：外掛

快速設定（入門）

  1. 為機器人建立專用 Twitch 帳號（或使用現有帳號）。
  2. 產生憑證：Twitch Token Generator
    • 選擇 Bot Token
    • 確認已選取 chat:read 和 chat:write 範圍
    • 複製 Client ID 和 Access Token
  3. 查詢你的 Twitch 使用者 ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. 設定 token：
    • 環境變數：OPENCLAW_TWITCH_ACCESS_TOKEN=...（僅預設帳號）
    • 或設定：channels.twitch.accessToken
    • 如果兩者都設定，設定值優先（環境變數備援僅限預設帳號）。
  5. 啟動 Gateway。

注意： 新增存取控制（allowFrom 或 allowedRoles）以防止未授權使用者觸發機器人。requireMention 預設為 true。

最小設定：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // 機器人的 Twitch 帳號
      accessToken: "oauth:abc123...", // OAuth Access Token（或使用 OPENCLAW_TWITCH_ACCESS_TOKEN 環境變數）
      clientId: "xyz789...", // 從 Token Generator 取得的 Client ID
      channel: "vevisk", // 要加入的 Twitch 頻道聊天室（必填）
      allowFrom: ["123456789"], // （推薦）你的 Twitch 使用者 ID — 從 https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 取得
    },
  },
}

這是什麼

  • 由 Gateway 擁有的 Twitch 頻道。
  • 確定性路由：回覆永遠回到 Twitch。
  • 每個帳號對應到一個隔離的工作階段鍵 agent:<agentId>:twitch:<accountName>。
  • username 是機器人的帳號（認證用），channel 是要加入的聊天室。

設定（詳細）

產生憑證

使用 Twitch Token Generator：

  • 選擇 Bot Token
  • 確認已選取 chat:read 和 chat:write 範圍
  • 複製 Client ID 和 Access Token

不需要手動註冊應用程式。Token 在數小時後過期。

設定機器人

環境變數（僅預設帳號）：

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

或設定：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "vevisk",
    },
  },
}

如果兩者都設定，設定值優先。

存取控制（推薦）

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // （推薦）你的 Twitch 使用者 ID
    },
  },
}

偏好使用 allowFrom 進行硬許可清單。若想要基於角色的存取，請改用 allowedRoles。

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

為何使用使用者 ID？ 使用者名稱可以變更，允許冒充。使用者 ID 是永久的。

查詢你的 Twitch 使用者 ID：https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/（將 Twitch 使用者名稱轉換為 ID）

Token 重新整理（選用）

從 Twitch Token Generator 取得的 token 無法自動重新整理 — 過期時重新產生。

若要自動重新整理 token，請在 Twitch Developer Console 建立你自己的 Twitch 應用程式並加入設定：

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

機器人會在 token 過期前自動重新整理並記錄重新整理事件。

多帳號支援

使用 channels.twitch.accounts 搭配按帳號的 token。詳見 gateway/configuration 的共用模式。

範例（一個機器人帳號在兩個頻道）：

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

備註： 每個帳號需要自己的 token（每個頻道一個 token）。

存取控制

基於角色的限制

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

按使用者 ID 的許可清單（最安全）

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

基於角色的存取（替代方案）

allowFrom 是硬許可清單。設定後，只允許那些使用者 ID。 如果你想要基於角色的存取，不要設定 allowFrom，改為設定 allowedRoles：

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

停用 @mention 要求

預設 requireMention 為 true。若要停用並回覆所有訊息：

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

疑難排解

首先執行診斷指令：

openclaw doctor
openclaw channels status --probe

機器人不回覆訊息

檢查存取控制： 確認你的使用者 ID 在 allowFrom 中，或暫時移除 allowFrom 並設定 allowedRoles: ["all"] 進行測試。

檢查機器人是否在頻道中： 機器人必須加入 channel 指定的頻道。

Token 問題

「連接失敗」或認證錯誤：

  • 確認 accessToken 是 OAuth access token 值（通常以 oauth: 前綴開頭）
  • 檢查 token 是否有 chat:read 和 chat:write 範圍
  • 如果使用 token 重新整理，確認已設定 clientSecret 和 refreshToken

Token 重新整理無法運作

檢查日誌中的重新整理事件：

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

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

  • 確認已提供 clientSecret
  • 確認已提供 refreshToken

設定

帳號設定：

  • username - 機器人使用者名稱
  • accessToken - 具有 chat:read 和 chat:write 的 OAuth access token
  • clientId - Twitch Client ID（從 Token Generator 或你的應用程式取得）
  • channel - 要加入的頻道（必填）
  • enabled - 啟用此帳號（預設：true）
  • clientSecret - 選用：用於自動 token 重新整理
  • refreshToken - 選用：用於自動 token 重新整理
  • expiresIn - Token 到期秒數
  • obtainmentTimestamp - Token 取得時間戳記
  • allowFrom - 使用者 ID 許可清單
  • allowedRoles - 基於角色的存取控制（"moderator" | "owner" | "vip" | "subscriber" | "all"）
  • requireMention - 需要 @mention（預設：true）

供應商選項：

  • channels.twitch.enabled - 啟用/停用頻道啟動
  • channels.twitch.username - 機器人使用者名稱（簡化單帳號設定）
  • channels.twitch.accessToken - OAuth access token（簡化單帳號設定）
  • channels.twitch.clientId - Twitch Client ID（簡化單帳號設定）
  • channels.twitch.channel - 要加入的頻道（簡化單帳號設定）
  • channels.twitch.accounts.<accountName> - 多帳號設定（以上所有帳號欄位）

完整範例：

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

工具操作

代理可以用 action 呼叫 twitch：

  • send - 發送訊息到頻道

範例：

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

安全與營運

  • 將 token 視為密碼 - 絕不將 token 提交到 git
  • 使用自動 token 重新整理 用於長時間運行的機器人
  • 使用使用者 ID 許可清單 而非使用者名稱進行存取控制
  • 監控日誌 以追蹤 token 重新整理事件和連接狀態
  • 最小化 token 範圍 - 只請求 chat:read 和 chat:write
  • 如果卡住：確認沒有其他程序佔用工作階段後重啟 Gateway

限制

  • 每則訊息 500 字元（自動在字詞邊界分段）
  • 分段前會移除 Markdown
  • 無頻率限制（使用 Twitch 內建的頻率限制）
arrow_back
上一頁
Tlon
下一頁
Whatsapp
arrow_forward