Twitch (plugin)

Hỗ trợ chat Twitch qua kết nối IRC. OpenClaw kết nối với tư cách là một user Twitch (tài khoản bot) để nhận và gửi tin nhắn trong các channel.

Cần cài Plugin

Twitch được cung cấp dưới dạng plugin và không đi kèm với bản cài đặt core.

Cài đặt qua CLI (npm registry):

openclaw plugins install @openclaw/twitch

Cài từ local (khi chạy từ git repo):

openclaw plugins install ./extensions/twitch

Chi tiết: Plugins

Thiết lập nhanh (dành cho người mới)

  1. Tạo một tài khoản Twitch riêng cho bot (hoặc dùng tài khoản có sẵn).
  2. Tạo credentials: Twitch Token Generator
    • Chọn Bot Token
    • Kiểm tra các scope chat:read và chat:write đã được chọn
    • Copy Client ID và Access Token
  3. Tìm Twitch user ID của các bạn: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. Cấu hình token:
    • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (chỉ cho tài khoản mặc định)
    • Hoặc config: channels.twitch.accessToken
    • Nếu cả hai đều được set, config sẽ được ưu tiên (env chỉ là fallback cho tài khoản mặc định).
  5. Khởi động Gateway.

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

Config tối thiểu:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Tài khoản Twitch của bot
      accessToken: "oauth:abc123...", // OAuth Access Token (hoặc dùng biến env OPENCLAW_TWITCH_ACCESS_TOKEN)
      clientId: "xyz789...", // Client ID từ Token Generator
      channel: "vevisk", // Channel Twitch nào để tham gia chat (bắt buộc)
      allowFrom: ["123456789"], // (khuyên dùng) Chỉ Twitch user ID của bạn - lấy từ https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

Đây là gì

  • Một Twitch channel được quản lý bởi Gateway.
  • Routing xác định: các reply luôn quay về Twitch.
  • Mỗi tài khoản được map tới một session key riêng biệt agent:<agentId>:twitch:<accountName>.
  • username là tài khoản của bot (ai đang xác thực), channel là phòng chat nào để tham gia.

Thiết lập (chi tiết)

Tạo credentials

Dùng Twitch Token Generator:

  • Chọn Bot Token
  • Kiểm tra các scope chat:read và chat:write đã được chọn
  • Copy Client ID và Access Token

Không cần đăng ký app thủ công. Token sẽ hết hạn sau vài giờ.

Cấu hình bot

Biến env (chỉ cho tài khoản mặc định):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

Hoặc config:

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

Nếu cả env và config đều được set, config sẽ được ưu tiên.

Kiểm soát truy cập (khuyên dùng)

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (khuyên dùng) Chỉ Twitch user ID của bạn
    },
  },
}

Ưu tiên dùng allowFrom cho allowlist cứng. Dùng allowedRoles nếu các bạn muốn kiểm soát theo role.

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

Tại sao dùng user ID? Username có thể đổi, cho phép giả mạo. User ID thì vĩnh viễn.

Tìm Twitch user ID của bạn: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Chuyển đổi Twitch username sang ID)

Làm mới Token (tùy chọn)

Token từ Twitch Token Generator không thể tự động làm mới - phải tạo lại khi hết hạn.

Để tự động làm mới token, tạo ứng dụng Twitch của riêng bạn tại Twitch Developer Console và thêm vào config:

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

Bot sẽ tự động làm mới token trước khi hết hạn và ghi log các sự kiện refresh.

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

Dùng channels.twitch.accounts với token riêng cho từng tài khoản. Xem gateway/configuration để biết pattern chung.

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

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

Lưu ý: Mỗi tài khoản cần token riêng (một token cho mỗi channel).

Kiểm soát truy cập

Giới hạn theo role

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

Allowlist theo User ID (an toàn nhất)

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

Truy cập theo role (phương án thay thế)

allowFrom là allowlist cứng. Khi được set, chỉ những user ID đó mới được phép. Nếu các bạn muốn truy cập theo role, bỏ trống allowFrom và cấu hình allowedRoles:

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

Tắt yêu cầu @mention

Mặc định, requireMention là true. Để tắt và phản hồi tất cả tin nhắn:

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

Troubleshooting

Đầu 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 user ID của bạn có trong allowFrom, hoặc tạm thời xóa allowFrom và set allowedRoles: ["all"] để test.

Kiểm tra bot đã vào channel chưa: Bot phải tham gia channel được chỉ định trong channel.

Vấn đề với Token

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

  • Kiểm tra accessToken là giá trị OAuth access token (thường bắt đầu bằng prefix oauth:)
  • Kiểm tra token có các scope chat:read và chat:write
  • Nếu dùng token refresh, kiểm tra clientSecret và refreshToken đã được set

Token refresh không hoạt động

Kiểm tra log để xem các sự kiện refresh:

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

Nếu thấy “token refresh disabled (no refresh token)”:

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

Config

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

  • username - Tên bot
  • accessToken - OAuth access token với chat:read và chat:write
  • clientId - Twitch Client ID (từ Token Generator hoặc app của bạn)
  • channel - Channel để tham gia (bắt buộc)
  • enabled - Bật tài khoản này (mặc định: true)
  • clientSecret - Tùy chọn: Để tự động làm mới token
  • refreshToken - Tùy chọn: Để tự động làm mới token
  • expiresIn - Thời gian hết hạn token tính bằng giây
  • obtainmentTimestamp - Timestamp lấy token
  • allowFrom - Allowlist user ID
  • allowedRoles - Kiểm soát truy cập theo role ("moderator" | "owner" | "vip" | "subscriber" | "all")
  • requireMention - Yêu cầu @mention (mặc định: true)

Tùy chọn Provider:

  • channels.twitch.enabled - Bật/tắt khởi động channel
  • channels.twitch.username - Tên bot (config đơn giản cho một tài khoản)
  • channels.twitch.accessToken - OAuth access token (config đơn giản cho một tài khoản)
  • channels.twitch.clientId - Twitch Client ID (config đơn giản cho một tài khoản)
  • channels.twitch.channel - Channel để tham gia (config đơn giản cho một tài khoản)
  • channels.twitch.accounts.<accountName> - Config nhiều tài khoản (tất cả các trường tài khoản ở trên)

Ví dụ đầy đủ:

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

Tool actions

Agent có thể gọi twitch với action:

  • send - Gửi tin nhắn tới một channel

Ví dụ:

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

An toàn & vận hành

  • Đối xử với token như mật khẩu - Không bao giờ commit token vào git
  • Dùng tự động làm mới token cho các bot chạy lâu dài
  • Dùng allowlist user ID thay vì username để kiểm soát truy cập
  • Theo dõi log để xem các sự kiện làm mới token và trạng thái kết nối
  • Giới hạn scope token tối thiểu - Chỉ yêu cầu chat:read và chat:write
  • Nếu bị kẹt: Khởi động lại Gateway sau khi xác nhận không có process nào khác đang sở hữu session

Giới hạn

  • 500 ký tự mỗi tin nhắn (tự động chia nhỏ theo ranh giới từ)
  • Markdown bị loại bỏ trước khi chia nhỏ
  • Không có rate limiting (dùng rate limit tích hợp của Twitch)