將 OpenClaw 連接到 Twitch：5 分鐘完成聊天機器人設定

想要在 Twitch 實況中加入 AI 互動，但光是處理 IRC 連線和 OAuth 驗證就讓你頭大嗎？手寫一個穩定的 Twitch 機器人往往比想像中麻煩，特別是當你還要處理 Token 過期或多頻道管理的時候。

這篇指南會教你如何使用 Twitch plugin，讓你的 OpenClaw 透過 IRC 連線，像真正的 Twitch 使用者（機器人帳號）一樣在頻道中收發訊息。

Twitch (plugin)

透過 IRC 連線支援 Twitch 聊天室。OpenClaw 會以 Twitch 使用者（機器人帳號）的身分連線，並在頻道中接收與傳送訊息。

需要安裝 Plugin

Twitch 功能是以 plugin 形式提供的，並沒有內建在核心安裝包中。

透過 CLI 安裝（npm registry）：

openclaw plugins install @openclaw/twitch

本地開發安裝（從 git repo 執行時）：

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

詳細資訊請參考：Plugins

快速設定（新手入門）

為機器人建立一個專用的 Twitch 帳號（或使用現有帳號）。
產生憑證：Twitch Token Generator
- 選擇 Bot Token
- 確認已勾選 chat:read 和 chat:write 權限範圍 (scopes)
- 複製 Client ID 和 Access Token
找到你的 Twitch user ID：https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
設定 Token：
- 環境變數：OPENCLAW_TWITCH_ACCESS_TOKEN=...（僅限預設帳號）
- 或設定檔：channels.twitch.accessToken
- 如果兩者都設定了，設定檔的優先權較高（環境變數僅作為預設帳號的備援）。
啟動 Gateway。

⚠️ 重要： 請務必加入存取控制（allowFrom 或 allowedRoles），防止未經授權的使用者觸發機器人。requireMention 預設為 true。

最簡設定範例：

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Bot's Twitch account
      accessToken: "oauth:abc123...", // OAuth Access Token (or use OPENCLAW_TWITCH_ACCESS_TOKEN env var)
      clientId: "xyz789...", // Client ID from Token Generator
      channel: "vevisk", // Which Twitch channel's chat to join (required)
      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

這是什麼

這是一個由 Gateway 擁有的 Twitch 頻道。
確定性路由：回覆總是會傳回 Twitch。
每個帳號都會對應到一個獨立的 session key 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"], // (recommended) Your Twitch user ID only
    },
  },
}

建議使用 allowFrom 來建立嚴格的白名單。如果你想要基於身分的存取權限，請改用 allowedRoles。

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

為什麼要用 user ID？ 因為使用者名稱可以更改，這可能導致冒充行為。User ID 是永久不變的。

找到你的 Twitch user ID：https://www.streamweasels.com/tools/convert-twitch-username-to-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"],
        },
      },
    },
  },
}

透過 User ID 建立白名單（最安全）

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

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

allowFrom 是硬性的白名單。一旦設定，就只有這些 user ID 被允許存取。如果你想要基於角色的存取，請不要設定 allowFrom，改為設定 allowedRoles：

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

停用 @mention 需求

預設情況下 requireMention 為 true。若要停用並讓機器人回應所有訊息：

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

疑難排解

首先，執行診斷指令：

openclaw doctor
openclaw channels status --probe

機器人沒有回應訊息

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

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

Token 問題

「Failed to connect」或驗證錯誤：

確認 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 - 是否需要 @提及（預設：true）

Provider 選項：

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

工具動作

Agent 可以呼叫 twitch 並執行以下動作：

send - 傳送訊息到頻道

範例：

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

安全與維運

像對待密碼一樣對待 Token - 絕對不要將 Token 提交到 git
使用自動 Token 刷新 以確保長期運行的機器人不會中斷
使用 User ID 白名單 而非使用者名稱來進行存取控制
監控日誌 以查看 Token 刷新事件和連線狀態
最小化 Token 權限 - 僅請求 chat:read 和 chat:write
如果卡住了：在確認沒有其他程序佔用 session 後，重啟 Gateway

限制

每則訊息 500 個字元（會在單字邊界自動切分）
在切分訊息前會先移除 Markdown 格式
沒有速率限制（使用 Twitch 內建的速率限制）

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。