> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitch

透過 Twurple 用戶端，經由 Twitch 的聊天（IRC）介面支援 Twitch 聊天。OpenClaw 會以 Twitch QQ Bot 帳號登入，為每個已設定帳號加入一個頻道，並在該頻道中回覆。

## 安裝

Twitch 以官方外掛形式提供；它不屬於核心安裝的一部分。

<Tabs>
  <Tab title="npm registry">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins install @openclaw/twitch
    ```
  </Tab>

  <Tab title="Local checkout">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins install ./path/to/local/twitch-plugin
    ```
  </Tab>
</Tabs>

`plugins install` 會註冊並啟用外掛。在 `openclaw onboard` 或 `openclaw channels add` 期間選擇 Twitch，會依需求安裝它。使用裸套件名稱可跟隨目前版本；只有在需要可重現安裝時，才釘選精確版本。需要 OpenClaw 2026.4.10 或更新版本。

詳細資訊：[外掛](/zh-TW/tools/plugin)

## 快速設定

<Steps>
  <Step title="安裝外掛">
    請參閱上方的[安裝](#install)。
  </Step>

  <Step title="建立 Twitch QQ Bot 帳號">
    為 QQ Bot 建立專用 Twitch 帳號（或使用現有帳號）。
  </Step>

  <Step title="產生憑證">
    使用 [Twitch Token Generator](https://twitchtokengenerator.com/)：

    * 選取**機器人權杖**
    * 確認已選取 `chat:read` 和 `chat:write` 範圍
    * 複製**用戶端 ID** 和**存取權杖**
  </Step>

  <Step title="尋找你的 Twitch 使用者 ID">
    使用 [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) 將使用者名稱轉換為 Twitch 使用者 ID。
  </Step>

  <Step title="設定權杖">
    * 環境變數：`OPENCLAW_TWITCH_ACCESS_TOKEN=...`（僅限預設帳號）
    * 或設定：`channels.twitch.accessToken`

    若兩者都已設定，設定會優先（環境變數僅作為預設帳號的備援）。
  </Step>

  <Step title="啟動閘道">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw gateway run
    ```
  </Step>
</Steps>

<Warning>
  新增存取控制（`allowFrom` 或 `allowedRoles`）以防止未授權使用者觸發 QQ Bot。`requireMention` 預設為 `true`。
</Warning>

最小設定：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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` 是 QQ Bot 的帳號（用於驗證），`channel` 是要加入的聊天室。每個帳號項目只會加入一個頻道。
* 權杖可搭配或不搭配 `oauth:` 前綴使用；OpenClaw 會以兩種方式正規化（設定精靈預期使用 `oauth:` 形式）。

## 權杖重新整理（選用）

[Twitch Token Generator](https://twitchtokengenerator.com/) 產生的權杖無法由 OpenClaw 重新整理，過期時請重新產生（它們會持續數小時；不需要註冊應用程式）。

若要自動重新整理，請在 [Twitch Developer Console](https://dev.twitch.tv/console) 建立你自己的應用程式，並新增：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    twitch: {
      clientSecret: "your_client_secret",
      refreshToken: "your_refresh_token",
    },
  },
}
```

兩者都設定時，外掛會使用可重新整理的驗證提供者，在到期前更新權杖，並記錄每次重新整理。若沒有 `refreshToken`，它會記錄 `token refresh disabled (no refresh token)`；若沒有 `clientSecret`，它會退回使用靜態（不可重新整理）權杖。

## 多帳號支援

使用 `channels.twitch.accounts` 搭配每帳號憑證。共用模式請參閱[設定](/zh-TW/gateway/configuration)。

範例（一個 QQ Bot 帳號在兩個頻道中）：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "yourchannel",
        },
        channel2: {
          username: "openclaw",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel",
        },
      },
    },
  },
}
```

<Note>
  每個帳號項目都需要自己的 `accessToken`（環境變數只涵蓋預設帳號）。一個帳號只會加入一個頻道，因此加入兩個頻道代表需要兩個帳號。`channels.twitch.defaultAccount` 會選擇哪個帳號是預設帳號。
</Note>

## 存取控制

`allowFrom` 是 Twitch 使用者 ID 的嚴格允許清單。設定它時，`allowedRoles` 會被忽略；若要改用角色型存取，請保留 `allowFrom` 未設定。

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

<Tabs>
  <Tab title="使用者 ID 允許清單（最安全）">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      channels: {
        twitch: {
          accounts: {
            default: {
              allowFrom: ["123456789", "987654321"],
            },
          },
        },
      },
    }
    ```
  </Tab>

  <Tab title="角色型">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      channels: {
        twitch: {
          accounts: {
            default: {
              allowedRoles: ["moderator", "vip"],
            },
          },
        },
      },
    }
    ```
  </Tab>

  <Tab title="停用 @mention 要求">
    預設情況下，`requireMention` 是 `true`。若要回應所有允許的訊息：

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      channels: {
        twitch: {
          accounts: {
            default: {
              requireMention: false,
            },
          },
        },
      },
    }
    ```
  </Tab>
</Tabs>

<Note>
  **為什麼使用使用者 ID？** 使用者名稱可以變更，可能造成冒用。使用者 ID 是永久的。

  使用[使用者名稱轉 ID 轉換器](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/)尋找你的 ID。
</Note>

## 疑難排解

首先，執行診斷命令：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw doctor
openclaw channels status --probe
```

<AccordionGroup>
  <Accordion title="QQ Bot 沒有回應訊息">
    * **檢查存取控制：** 確認你的使用者 ID 位於 `allowFrom` 中，或暫時移除 `allowFrom` 並設定 `allowedRoles: ["all"]` 進行測試。
    * **檢查 mention 閘門：** 使用 `requireMention: true`（預設）時，訊息必須 @mention QQ Bot 使用者名稱。
    * **檢查 QQ Bot 是否在頻道中：** QQ Bot 只會加入 `channel` 中命名的頻道。
  </Accordion>

  <Accordion title="權杖問題">
    「連線失敗」或驗證錯誤：

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

  <Accordion title="權杖重新整理無法運作">
    檢查紀錄中的重新整理事件：

    ```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
    Using env token source for mybot
    Access token refreshed for user 123456 (expires in 14400s)
    ```

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

    * 確認已提供 `clientSecret`
    * 確認已提供 `refreshToken`
  </Accordion>
</AccordionGroup>

## 設定

### 帳號設定

<ParamField path="username" type="string" required>
  QQ Bot 使用者名稱（進行驗證的帳號）。
</ParamField>

<ParamField path="accessToken" type="string" required>
  具備 `chat:read` 和 `chat:write` 的 OAuth 存取權杖（設定或預設帳號的環境變數）。
</ParamField>

<ParamField path="clientId" type="string" required>
  Twitch 用戶端 ID（來自 Token Generator 或你的應用程式）。在結構描述中為選用，但連線時必填。
</ParamField>

<ParamField path="channel" type="string" required>
  要加入的頻道。
</ParamField>

<ParamField path="enabled" type="boolean" default="true">
  啟用此帳號。
</ParamField>

<ParamField path="clientSecret" type="string">
  選用：用於自動權杖重新整理。
</ParamField>

<ParamField path="refreshToken" type="string">
  選用：用於自動權杖重新整理。
</ParamField>

<ParamField path="expiresIn" type="number">
  權杖到期秒數（重新整理追蹤）。
</ParamField>

<ParamField path="obtainmentTimestamp" type="number">
  權杖取得時的時間戳記（重新整理追蹤）。
</ParamField>

<ParamField path="allowFrom" type="string[]">
  使用者 ID 允許清單。設定時，角色會被忽略。
</ParamField>

<ParamField path="allowedRoles" type="Array<&#x22;moderator&#x22; | &#x22;owner&#x22; | &#x22;vip&#x22; | &#x22;subscriber&#x22; | &#x22;all&#x22;>">
  角色型存取控制。
</ParamField>

<ParamField path="requireMention" type="boolean" default="true">
  要求 @mention 才能觸發 QQ Bot。
</ParamField>

<ParamField path="responsePrefix" type="string">
  此帳號的外送回應前綴覆寫。
</ParamField>

### 提供者選項

* `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`）

完整範例：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 訊息：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channel: "twitch",
  action: "send",
  to: "#mychannel",
  message: "Hello Twitch!",
}
```

`to` 是選用的，預設為帳號已設定的 `channel`。

## 安全性與維運

* **像密碼一樣看待權杖** - 絕不要將權杖提交到 git。
* **使用自動權杖重新整理**，適用於長時間執行的 QQ Bot。
* **使用使用者 ID 允許清單** 取代使用者名稱來進行存取控制。
* **監控紀錄** 以查看權杖重新整理事件與連線狀態。
* **最小化權杖範圍** - 只要求 `chat:read` 和 `chat:write`。
* **若卡住**：確認沒有其他程序擁有該工作階段後，重新啟動閘道。

## 限制

* 每則訊息 **500 個字元**；較長的回覆會在單字邊界分塊。
* 傳送前會移除 Markdown（Twitch 聊天是純文字；換行會變成空格）。
* OpenClaw 不會新增自己的速率限制；Twurple 聊天用戶端會處理 Twitch 速率限制。

## 相關

* [頻道路由](/zh-TW/channels/channel-routing) — 訊息的工作階段路由
* [頻道概觀](/zh-TW/channels) — 所有支援的頻道
* [群組](/zh-TW/channels/groups) — 群組聊天行為與 mention 閘門
* [配對](/zh-TW/channels/pairing) — DM 驗證與配對流程
* [安全性](/zh-TW/gateway/security) — 存取模型與強化