Twitch

Hỗ trợ trò chuyện Twitch qua giao diện trò chuyện (IRC) của Twitch bằng ứng dụng khách Twurple. OpenClaw đăng nhập bằng tài khoản bot Twitch, tham gia một kênh cho mỗi tài khoản được cấu hình và trả lời trong kênh đó.

​

Cài đặt

Twitch được phân phối dưới dạng plugin chính thức; plugin này không thuộc bản cài đặt lõi.

npm registry

openclaw plugins install @openclaw/twitch

Bản mã nguồn cục bộ

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

plugins install đăng ký và bật plugin. Việc chọn Twitch trong openclaw onboard hoặc openclaw channels add sẽ cài đặt plugin khi cần. Dùng tên gói trần để theo bản phát hành hiện tại; chỉ ghim một phiên bản chính xác khi cần các bản cài đặt có thể tái tạo. Yêu cầu OpenClaw 2026.4.10 trở lên.

Chi tiết: Plugin

​

Thiết lập nhanh

1. Cài đặt plugin

   Xem phần Cài đặt ở trên.

2. Tạo tài khoản bot Twitch

   Tạo một tài khoản Twitch riêng cho bot (hoặc dùng tài khoản hiện có).

3. Tạo thông tin xác thực

   Dùng Twitch Token Generator:

   • Chọn Bot Token
   • Xác minh rằng các phạm vi chat:read và chat:write đã được chọn
   • Sao chép Client ID và Access Token
4. Tìm ID người dùng Twitch của bạn

   Dùng https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ để chuyển đổi tên người dùng thành ID người dùng Twitch.

5. Cấu hình token

   • Biến môi trường: OPENCLAW_TWITCH_ACCESS_TOKEN=... (chỉ tài khoản mặc định)
   • Hoặc cấu hình: channels.twitch.accessToken

   Nếu cả hai đều được đặt, cấu hình được ưu tiên (biến môi trường chỉ là phương án dự phòng cho tài khoản mặc định).

6. Khởi động Gateway

   openclaw gateway run
   

Thêm kiểm soát truy cập (allowFrom hoặc allowedRoles) để ngăn người dùng trái phép kích hoạt bot. requireMention mặc định là true.

Cấu hình tối thiểu:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Tài khoản Twitch của bot (dùng để xác thực)
      accessToken: "oauth:abc123...", // Token truy cập OAuth (hoặc dùng biến môi trường OPENCLAW_TWITCH_ACCESS_TOKEN)
      clientId: "xyz789...", // ID ứng dụng khách từ Token Generator
      channel: "yourchannel", // Kênh trò chuyện Twitch cần tham gia (bắt buộc)
      allowFrom: ["123456789"], // (khuyến nghị) Chỉ ID người dùng Twitch của bạn
    },
  },
}

​

Đây là gì

• Một kênh Twitch do Gateway sở hữu.
• Định tuyến xác định: phản hồi luôn được gửi lại kênh Twitch nơi tin nhắn bắt nguồn.
• Mỗi kênh đã tham gia ánh xạ tới một khóa phiên nhóm biệt lập agent:<agentId>:twitch:group:<channel>.
• username là tài khoản của bot (tài khoản xác thực), còn channel là phòng trò chuyện cần tham gia. Mỗi mục tài khoản tham gia đúng một kênh.
• Token hoạt động dù có hay không có tiền tố oauth:; OpenClaw chuẩn hóa cả hai dạng (trình hướng dẫn thiết lập yêu cầu dạng oauth:).

​

Độ bền của dữ liệu đến

OpenClaw đưa từng tin nhắn trò chuyện Twitch được chấp nhận vào hàng đợi bền vững trước khi điều phối thông thường. Các tin nhắn đang chờ hoặc có thể thử lại vẫn tồn tại sau khi Gateway khởi động lại, được xử lý tuần tự cho kênh đã cấu hình và dùng ID tin nhắn của Twitch để ngăn các mục hàng đợi trùng lặp trong khi bản ghi hoàn tất đang hoạt động hoặc được lưu giữ vẫn tồn tại.

Trò chuyện Twitch không phát lại một PRIVMSG sau khi ứng dụng khách đã chấp nhận nó. Cơ chế này bảo vệ khoảng thời gian có thể xảy ra sự cố từ lúc chấp nhận cục bộ đến lúc điều phối, nhưng không thể khôi phục các tin nhắn bị bỏ lỡ trước khi được tiếp nhận bền vững. Nếu thao tác thêm vào hàng đợi thất bại, OpenClaw ghi lại lỗi; việc kết nối lại không yêu cầu Twitch gửi lại tin nhắn đó.

​

Làm mới token (không bắt buộc)

OpenClaw không thể làm mới các token từ Twitch Token Generator — hãy tạo lại khi hết hạn (chúng tồn tại vài giờ; không cần đăng ký ứng dụng).

Để tự động làm mới, hãy tạo ứng dụng riêng tại Twitch Developer Console và thêm:

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

Khi cả hai đều được đặt, plugin dùng nhà cung cấp xác thực có khả năng làm mới để gia hạn token trước khi hết hạn và ghi nhật ký mỗi lần làm mới. Nếu thiếu refreshToken, plugin ghi nhật ký token refresh disabled (no refresh token); nếu thiếu clientSecret, plugin quay về dùng token tĩnh (không làm mới).

​

Hỗ trợ nhiều tài khoản

Dùng channels.twitch.accounts với thông tin xác thực riêng cho từng tài khoản. Xem Cấu hình để biết mẫu dùng chung.

Ví dụ (một tài khoản bot trong hai kênh):

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

Mỗi mục tài khoản cần accessToken riêng (biến môi trường chỉ áp dụng cho tài khoản mặc định). Một tài khoản tham gia đúng một kênh, vì vậy việc tham gia hai kênh cần hai tài khoản. channels.twitch.defaultAccount chọn tài khoản mặc định.

​

Kiểm soát truy cập

allowFrom là danh sách cho phép nghiêm ngặt gồm các ID người dùng Twitch. Khi được đặt, allowedRoles bị bỏ qua; không đặt allowFrom để thay vào đó dùng quyền truy cập dựa trên vai trò.

Các vai trò có sẵn: "moderator", "owner", "vip", "subscriber", "all".

Danh sách cho phép theo ID người dùng (an toàn nhất)

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

Dựa trên vai trò

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

Tắt yêu cầu @đề cập

Theo mặc định, requireMention là true. Để phản hồi tất cả tin nhắn được phép:

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

Tại sao dùng ID người dùng? Tên người dùng có thể thay đổi, tạo điều kiện cho việc mạo danh. ID người dùng là vĩnh viễn.

Tìm ID của bạn bằng công cụ chuyển đổi tên người dùng sang ID.

​

Khắc phục sự cố

Trước tiên, chạy các lệnh chẩn đoán:

openclaw doctor
openclaw channels status --probe

Bot không phản hồi tin nhắn

• Kiểm tra kiểm soát truy cập: Đảm bảo ID người dùng của bạn có trong allowFrom, hoặc tạm thời xóa allowFrom và đặt allowedRoles: ["all"] để kiểm thử.
• Kiểm tra cổng đề cập: Khi dùng requireMention: true (mặc định), tin nhắn phải @đề cập tên người dùng của bot.
• Kiểm tra bot có trong kênh: Bot chỉ tham gia kênh được đặt tên trong channel.

Sự cố token

Lỗi “Failed to connect” hoặc lỗi xác thực:

• Xác minh accessToken là giá trị token truy cập OAuth (tiền tố oauth: không bắt buộc)
• Kiểm tra token có các phạm vi chat:read và chat:write
• Nếu dùng tính năng làm mới token, hãy xác minh clientSecret và refreshToken đã được đặt

Tính năng làm mới token không hoạt động

Kiểm tra nhật ký để tìm các sự kiện làm mới:

Đang dùng nguồn token từ biến môi trường cho mybot
Token truy cập đã được làm mới cho người dùng 123456 (hết hạn sau 14400s)

Nếu bạn thấy token refresh disabled (no refresh token):

• Đảm bảo đã cung cấp clientSecret
• Đảm bảo đã cung cấp refreshToken

​

Cấu hình

​

Cấu hình tài khoản

username · string · bắt buộc

Tên người dùng bot (tài khoản xác thực).

accessToken · string · bắt buộc

Token truy cập OAuth có chat:read và chat:write (cấu hình hoặc biến môi trường cho tài khoản mặc định).

clientId · string · bắt buộc

Twitch Client ID (từ Token Generator hoặc ứng dụng của bạn). Không bắt buộc trong lược đồ nhưng cần thiết để kết nối.

channel · string · bắt buộc

Kênh cần tham gia.

enabled · boolean · mặc định: "true"

Bật tài khoản này.

clientSecret · string

Không bắt buộc: dùng để tự động làm mới token.

refreshToken · string

Không bắt buộc: dùng để tự động làm mới token.

expiresIn · number

Thời gian hết hạn token tính bằng giây (theo dõi làm mới).

obtainmentTimestamp · number

Dấu thời gian khi nhận được token (theo dõi làm mới).

allowFrom · string[]

Danh sách cho phép theo ID người dùng. Khi được đặt, các vai trò bị bỏ qua.

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

Kiểm soát truy cập dựa trên vai trò.

requireMention · boolean · mặc định: "true"

Yêu cầu @đề cập để kích hoạt bot.

responsePrefix · string

Ghi đè tiền tố phản hồi gửi đi cho tài khoản này.

​

Tùy chọn nhà cung cấp

• channels.twitch.enabled - Bật/tắt khởi động kênh
• channels.twitch.username / accessToken / clientId / channel - Cấu hình một tài khoản đơn giản hóa (tài khoản default ngầm định; được ưu tiên hơn accounts.default)
• channels.twitch.accounts.<accountName> - Cấu hình nhiều tài khoản (tất cả các trường tài khoản ở trên)
• channels.twitch.defaultAccount - Tên tài khoản nào là mặc định
• channels.twitch.markdown.tables - Chế độ kết xuất bảng Markdown (off | bullets | code | block)

Ví dụ đầy đủ:

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

​

Thao tác công cụ

Tác tử có thể gửi tin nhắn Twitch thông qua thao tác send của công cụ nhắn tin:

{
  channel: "twitch",
  action: "send",
  to: "#mychannel",
  message: "Xin chào Twitch!",
}

to không bắt buộc và mặc định là channel được cấu hình của tài khoản.

​

An toàn và vận hành

• Xử lý token như mật khẩu - tuyệt đối không commit token vào git.
• Sử dụng cơ chế tự động làm mới token cho các bot chạy lâu dài.
• Sử dụng danh sách cho phép theo ID người dùng thay vì tên người dùng để kiểm soát quyền truy cập.
• Theo dõi nhật ký để kiểm tra các sự kiện làm mới token và trạng thái kết nối.
• Giới hạn phạm vi token ở mức tối thiểu - chỉ yêu cầu chat:read và chat:write.
• Nếu gặp bế tắc: khởi động lại Gateway sau khi xác nhận không có tiến trình nào khác sở hữu phiên.

​

Giới hạn

• 500 ký tự cho mỗi tin nhắn; các phản hồi dài hơn được chia thành nhiều phần tại ranh giới giữa các từ.
• Markdown bị loại bỏ trước khi gửi (trò chuyện Twitch sử dụng văn bản thuần túy; các ký tự xuống dòng được chuyển thành dấu cách).
• OpenClaw không tự áp dụng giới hạn tốc độ; ứng dụng trò chuyện Twurple xử lý các giới hạn tốc độ của Twitch.

​

Liên quan

• Định tuyến kênh — định tuyến phiên cho tin nhắn
• Tổng quan về các kênh — tất cả các kênh được hỗ trợ
• Nhóm — hành vi trò chuyện nhóm và cơ chế kiểm soát bằng lượt đề cập
• Ghép nối — xác thực tin nhắn trực tiếp và luồng ghép nối
• Bảo mật — mô hình truy cập và tăng cường bảo mật