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

詳細資訊：外掛

​

快速設定

1. 安裝外掛

   請參閱上方的安裝。

2. 建立 Twitch 機器人帳號

   為機器人建立專用的 Twitch 帳號（或使用現有帳號）。

3. 產生認證資訊

   使用 Twitch Token Generator：

   • 選取 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
   

新增存取控制（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
    },
  },
}

​

功能說明

• 由閘道擁有的 Twitch 頻道。
• 確定性路由：回覆一律傳回訊息來源的 Twitch 頻道。
• 每個已加入的頻道會對應至獨立的群組工作階段金鑰 agent:<agentId>:twitch:group:<channel>。
• username 是機器人的帳號（用於驗證身分），channel 則是要加入的聊天室。每個帳號項目只會加入一個頻道。
• 權杖無論是否包含 oauth: 前綴都可使用；OpenClaw 會將兩種形式正規化（設定精靈預期使用 oauth: 形式）。

​

傳入訊息的持久性

OpenClaw 會先將每則已接受的 Twitch 聊天訊息持久排入佇列，再進行一般分派。待處理或可重試的訊息會在閘道重新啟動後繼續保留、針對已設定的頻道維持依序處理，並使用 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。共用模式請參閱設定。

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

{
  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

機器人未回應訊息

• 檢查存取控制： 確認你的使用者 ID 位於 allowFrom 中，或暫時移除 allowFrom 並設定 allowedRoles: ["all"] 以進行測試。
• 檢查提及閘門： 使用 requireMention: true（預設值）時，訊息必須 @提及機器人的使用者名稱。
• 檢查機器人是否位於頻道中： 機器人只會加入 channel 中指定的頻道。

權杖問題

“連線失敗”或驗證錯誤：

• 確認 accessToken 是 OAuth 存取權杖值（oauth: 前綴為選用）
• 檢查權杖是否具有 chat:read 和 chat:write 範圍
• 若使用權杖重新整理，請確認已設定 clientSecret 和 refreshToken

權杖重新整理無法運作

檢查記錄中的重新整理事件：

對 mybot 使用環境變數權杖來源
已重新整理使用者 123456 的存取權杖（於 14400s 後到期）

若看到 token refresh disabled (no refresh token)：

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

​

設定

​

帳號設定

username · string · 必填

機器人使用者名稱（用於驗證的帳號）。

accessToken · string · 必填

具有 chat:read 和 chat:write 的 OAuth 存取權杖（預設帳號可使用設定或環境變數）。

clientId · string · 必填

Twitch Client ID（來自 Token Generator 或你的應用程式）。在結構描述中為選用，但連線時為必填。

channel · string · 必填

要加入的頻道。

enabled · boolean · 預設值: "true"

啟用此帳號。

clientSecret · string

選用：用於自動重新整理權杖。

refreshToken · string

選用：用於自動重新整理權杖。

expiresIn · number

權杖到期秒數（重新整理追蹤）。

obtainmentTimestamp · number

取得權杖時的時間戳記（重新整理追蹤）。

allowFrom · string[]

使用者 ID 允許清單。設定後會忽略角色。

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

角色型存取控制。

requireMention · boolean · 預設值: "true"

要求 @提及才能觸發機器人。

responsePrefix · 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。
• 對長時間執行的機器人，使用自動權杖重新整理。
• 使用使用者 ID 允許清單而非使用者名稱進行存取控制。
• 監控日誌中的權杖重新整理事件與連線狀態。
• 將權杖範圍縮至最小 - 僅要求 chat:read 和 chat:write。
• 如果卡住：確認沒有其他程序占用工作階段後，重新啟動閘道。

​

限制

• 每則訊息 500 個字元；較長的回覆會在單字邊界處分段。
• 傳送前會移除 Markdown（Twitch 聊天使用純文字；換行會轉換成空格）。
• OpenClaw 本身不會新增任何速率限制；Twurple 聊天用戶端會處理 Twitch 的速率限制。

​

相關內容

• 頻道路由 — 訊息的工作階段路由
• 頻道概覽 — 所有支援的頻道
• 群組 — 群組聊天行為與提及閘控
• 配對 — 私訊驗證與配對流程
• 安全性 — 存取模型與強化措施