Twitch

Twurple 클라이언트를 통해 Twitch의 채팅(IRC) 인터페이스를 사용하는 Twitch 채팅 지원입니다. OpenClaw는 Twitch 봇 계정으로 로그인하고, 구성된 계정마다 하나의 채널에 참여하여 해당 채널에서 답변합니다.

설치

Twitch는 공식 Plugin으로 제공되며, 핵심 설치에는 포함되지 않습니다.

npm 레지스트리
로컬 체크아웃

openclaw plugins install @openclaw/twitch

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

plugins install은 Plugin을 등록하고 활성화합니다. openclaw onboard 또는 openclaw channels add 중에 Twitch를 선택하면 필요할 때 설치됩니다. 현재 릴리스를 따르려면 버전 없는 패키지 이름을 사용하고, 재현 가능한 설치가 필요한 경우에만 정확한 버전을 고정하세요. OpenClaw 2026.4.10 이상이 필요합니다. 자세한 내용: Plugin

빠른 설정

Plugin 설치

위의 설치를 참조하세요.

Twitch 봇 계정 만들기

봇 전용 Twitch 계정을 만들거나 기존 계정을 사용하세요.

자격 증명 생성

Twitch Token Generator를 사용하세요.

Bot Token을 선택합니다
chat:read 및 chat:write 범위가 선택되어 있는지 확인합니다
Client ID와 Access Token을 복사합니다

Twitch 사용자 ID 찾기

https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/를 사용하여 사용자 이름을 Twitch 사용자 ID로 변환하세요.

토큰 구성

환경 변수: OPENCLAW_TWITCH_ACCESS_TOKEN=...(기본 계정에만 적용)
또는 구성: channels.twitch.accessToken

둘 다 설정된 경우 구성이 우선합니다. 환경 변수는 기본 계정의 대체 값으로만 사용됩니다.

Gateway 시작

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에서 받은 클라이언트 ID
      channel: "yourchannel", // 참여할 Twitch 채널의 채팅(필수)
      allowFrom: ["123456789"], // (권장) 자신의 Twitch 사용자 ID만 허용
    },
  },
}

개요

Gateway가 소유하는 Twitch 채널입니다.
결정적 라우팅: 답변은 항상 메시지가 들어온 Twitch 채널로 돌아갑니다.
참여한 각 채널은 격리된 그룹 세션 키 agent:<agentId>:twitch:group:<channel>에 매핑됩니다.
username은 인증하는 봇 계정이고, channel은 참여할 채팅방입니다. 계정 항목 하나는 정확히 하나의 채널에 참여합니다.
토큰은 oauth: 접두사가 있거나 없어도 작동하며, OpenClaw가 두 형식을 모두 정규화합니다. 설정 마법사는 oauth: 형식을 요구합니다.

토큰 갱신(선택 사항)

Twitch Token Generator에서 받은 토큰은 OpenClaw가 갱신할 수 없습니다. 만료되면 다시 생성하세요. 이 토큰은 몇 시간 동안 유효하며 앱 등록은 필요하지 않습니다. 자동 갱신을 사용하려면 Twitch Developer Console에서 직접 앱을 만들고 다음을 추가하세요.

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

둘 다 설정하면 Plugin은 만료 전에 토큰을 갱신하고 각 갱신을 기록하는 갱신 가능 인증 공급자를 사용합니다. 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이 설정되어 있는지 확인하세요.

토큰 갱신이 작동하지 않음

로그에서 갱신 이벤트를 확인하세요.

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

token refresh disabled (no refresh token)이 표시되는 경우:

clientSecret이 제공되었는지 확인하세요.
refreshToken이 제공되었는지 확인하세요.

구성

계정 구성

string

필수

봇 사용자 이름(인증하는 계정).

string

필수

chat:read 및 chat:write 권한이 있는 OAuth 액세스 토큰(기본 계정의 경우 구성 또는 환경 변수).

string

필수

Twitch 클라이언트 ID(Token Generator 또는 자체 앱에서 발급). 스키마에서는 선택 사항이지만 연결하려면 필수입니다.

string

필수

참여할 채널.

boolean

기본값:"true"

이 계정을 활성화합니다.

string

선택 사항: 자동 토큰 갱신에 사용합니다.

string

선택 사항: 자동 토큰 갱신에 사용합니다.

number

토큰 만료 시간(초 단위, 갱신 추적용).

number

토큰을 얻은 시점의 타임스탬프(갱신 추적용).

string[]

사용자 ID 허용 목록. 설정하면 역할은 무시됩니다.

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

역할 기반 접근 제어.

boolean

기본값:"true"

봇을 실행하려면 @멘션을 요구합니다.

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만 요청하세요.
문제가 해결되지 않는 경우: 다른 프로세스가 세션을 소유하지 않는지 확인한 후 Gateway를 다시 시작하세요.

제한 사항

메시지당 500자이며, 더 긴 답변은 단어 경계에서 분할됩니다.
전송 전에 Markdown이 제거됩니다. Twitch 채팅은 일반 텍스트이며 줄바꿈은 공백으로 바뀝니다.
OpenClaw는 자체적인 속도 제한을 추가하지 않습니다. Twurple 채팅 클라이언트가 Twitch 속도 제한을 처리합니다.

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

설치

빠른 설정

개요

토큰 갱신(선택 사항)

다중 계정 지원

접근 제어

문제 해결

구성

계정 구성

공급자 옵션

도구 작업

보안 및 운영

제한 사항

관련 문서

​설치

​빠른 설정

​개요

​토큰 갱신(선택 사항)

​다중 계정 지원

​접근 제어

​문제 해결

​구성

​계정 구성

​공급자 옵션

​도구 작업

​보안 및 운영

​제한 사항

​관련 문서

설치

빠른 설정

개요

토큰 갱신(선택 사항)

다중 계정 지원

접근 제어

문제 해결

구성

계정 구성

공급자 옵션

도구 작업

보안 및 운영

제한 사항

관련 문서