OpenClaw

OpenClaw Twitch 채널

메시징
쉬움

IRC를 통해 OpenClaw를 Twitch 채팅에 연결하여 AI 어시스턴트가 시청자와 실시간으로 상호작용할 수 있도록 합니다. Twitch 플러그인을 설치하고 채팅 스코프가 포함된 OAuth 토큰을 구성하면 봇이 채널에 참여하여 멘션에 응답하고 역할 기반 접근 제어로 대화를 관리할 수 있습니다.

기본 정보
난이도쉬움
카테고리메시징
지원 기능 수2 / 6

Twitch 지원 기능

텍스트 메시지

지원

미디어 및 파일

미지원

리액션

미지원

스레드

미지원

음성 메시지

미지원

그룹 채팅

지원

Twitch 사전 요구사항

  • 봇 ID로 사용할 Twitch 계정
  • chat:read 및 chat:write 스코프가 포함된 OAuth Access Token
  • Twitch Developer Console에서 발급한 Client ID
  • OpenClaw Gateway 설치 및 실행 완료
  • 'openclaw plugins install @openclaw/twitch'를 통해 Twitch 플러그인 설치 완료

Twitch 빠른 설정

1

Twitch 플러그인 설치

'openclaw plugins install @openclaw/twitch'를 실행하여 Twitch 지원을 추가합니다. 또는 'openclaw plugins install ./extensions/twitch'로 로컬 경로에서 설치할 수도 있습니다.

2

OAuth 토큰 및 Client ID 발급

twitchtokengenerator.com을 방문하여 chat:read 및 chat:write 스코프가 포함된 'Bot Token'을 선택합니다. Access Token을 복사합니다. 또한 Twitch Developer Console(dev.twitch.tv/console)에서 Client ID를 발급받습니다.

3

구성 및 실행

~/.openclaw/openclaw.json에 username, accessToken, clientId, 대상 채널을 포함한 Twitch 채널 구성을 추가합니다. 'openclaw start'로 Gateway를 시작하고 Twitch 채널에서 봇을 멘션하는 메시지를 전송하여 정상 작동을 확인합니다.

Twitch 구성 예시

config.json
{
  "channels": {
    "twitch": {
      "enabled": true,
      "username": "mybotname",
      "accessToken": "oauth:abc123...",
      "clientId": "your-client-id",
      "channel": "targetchannel",
      "allowFrom": ["123456789"]
    }
  }
}

Twitch 상세 문서

아키텍처 개요

OpenClaw는 IRC 프로토콜을 사용하여 Twitch 채팅에 연결합니다. Gateway는 OAuth 토큰으로 인증하고 지정된 채널에 참여하여 메시지를 수신합니다. 시청자가 봇을 트리거하는 메시지를 전송하면(기본적으로 @멘션) Gateway가 이를 AI 에이전트로 전달합니다. 응답은 동일한 Twitch 채널로 전송되며, Twitch의 제한을 준수하기 위해 메시지당 500자 단위로 자동 분할됩니다. 각 계정은 고유한 세션 키(agent:<agentId>:twitch:<accountName>)에 매핑되므로 동일한 Gateway에서 여러 계정을 독립적으로 운영할 수 있습니다. Twitch 채팅은 마크다운을 렌더링하지 않으므로 전송 전에 마크다운이 자동으로 제거됩니다.
응답은 발생한 Twitch 채널로 결정적으로 라우팅됩니다.
500자를 초과하는 메시지는 단어 경계에서 자동으로 분할됩니다.

자격 증명 발급

연결에 필요한 세 가지 자격 증명: OAuth Access Token, Client ID, 봇의 사용자 이름. 1. twitchtokengenerator.com으로 이동하여 'Bot Token'을 선택합니다. 2. chat:read 및 chat:write 스코프로 토큰을 인증합니다. 3. 생성된 Access Token을 복사합니다('oauth:'로 시작). 4. Client ID는 Twitch Developer Console(dev.twitch.tv/console)에서 애플리케이션을 등록한 후 Client ID를 복사합니다. Access Token은 OPENCLAW_TWITCH_ACCESS_TOKEN 환경 변수로도 제공할 수 있습니다. 환경 변수와 구성 파일 값이 모두 설정된 경우 구성 파일이 우선합니다.
terminal
# Environment variable (default account only)
export OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...
Access Token을 버전 관리 시스템에 커밋하지 마세요. 환경 변수 또는 시크릿 관리자를 사용하세요.
twitchtokengenerator.com에서 발급한 토큰은 몇 시간 후 만료됩니다. 장기 실행 봇의 경우 자동 갱신을 설정하세요.

토큰 자동 갱신

Twitch Token Generator에서 발급한 토큰은 몇 시간 후 만료됩니다. 프로덕션 봇의 경우 다운타임을 방지하기 위해 토큰 자동 갱신을 구성하세요. 1. Twitch Developer Console(dev.twitch.tv/console)에서 애플리케이션을 등록합니다. 2. Client Secret을 기록하고 OAuth Authorization Code 플로우를 사용하여 Refresh Token을 발급받습니다. 3. 계정 구성에 clientSecret과 refreshToken을 추가합니다. 봇은 토큰이 만료되기 전에 자동으로 갱신하며 모니터링을 위해 갱신 이벤트를 로그에 기록합니다.
openclaw.json
{
  "channels": {
    "twitch": {
      "accessToken": "oauth:abc123...",
      "clientId": "your-client-id",
      "clientSecret": "your-client-secret",
      "refreshToken": "your-refresh-token"
    }
  }
}
자동 갱신이 구성되지 않으면 토큰이 만료될 때마다 수동으로 교체해야 합니다.

사용자 ID를 통한 접근 제어

Twitch 사용자 이름은 변경될 수 있어 사칭 위험이 있습니다. OpenClaw는 사용자 이름 대신 숫자 사용자 ID를 사용한 접근 제어를 강력히 권장합니다. allowFrom 필드는 영구적인 Twitch 사용자 ID 배열을 받습니다. 이 목록에 ID가 포함된 사용자만 봇과 상호작용할 수 있으며, 그 외의 사용자는 자동으로 무시됩니다. 사용자의 숫자 ID는 Twitch API 또는 twitchinsights.net과 같은 서드파티 도구를 사용하여 조회할 수 있습니다.
openclaw.json
{
  "channels": {
    "twitch": {
      "allowFrom": ["123456789", "987654321"]
    }
  }
}
사용자 ID는 영구적이며 사용자 이름 변경의 영향을 받지 않습니다. 보안을 위해 항상 사용자 이름보다 ID를 사용하세요.

역할 기반 접근 제어

명시적 사용자 ID 허용 목록 대신(또는 추가로) Twitch 채팅 역할로 접근을 제한할 수 있습니다. allowedRoles 필드는 역할 이름 배열을 받습니다. 사용 가능한 역할: • moderator — 채널 관리자 • owner — 채널 방송인 • vip — VIP 사용자 • subscriber — 채널 구독자 • all — 채널의 모든 사용자 (주의하여 사용) allowedRoles가 설정되면 하나 이상의 일치하는 역할을 가진 사용자만 봇과 상호작용할 수 있습니다.
openclaw.json
{
  "channels": {
    "twitch": {
      "allowedRoles": ["moderator", "vip"]
    }
  }
}
allowedRoles를 ['all']로 설정하면 모든 시청자가 봇과 상호작용할 수 있으며, 활발한 채널에서는 상당한 AI 사용량이 발생할 수 있습니다.

멘션 요구 사항

기본적으로 봇은 채팅에서 명시적으로 @멘션된 경우에만 응답합니다(requireMention: true). 이를 통해 활발한 채널에서 봇이 모든 메시지에 응답하는 것을 방지합니다. requireMention을 false로 설정하면 이 동작을 비활성화할 수 있으며, 이 경우 봇은 허용된 사용자의 모든 메시지에 응답합니다. 전용 봇 채널이나 트래픽이 적은 스트림에서 유용합니다.
openclaw.json
{
  "channels": {
    "twitch": {
      "requireMention": false
    }
  }
}
활발한 채널에서는 requireMention을 활성화 상태로 유지하여 봇이 모든 채팅 메시지에 반응하는 것을 방지하세요.

다중 계정 설정

OpenClaw는 여러 Twitch 봇 계정을 동시에 운영할 수 있습니다. 각 계정은 자체 OAuth 토큰이 필요하며 하나의 채널에 매핑됩니다. accounts.<name> 패턴을 사용하여 여러 계정을 구성합니다. 각 계정은 독립적인 접근 제어, 멘션 요구 사항, 토큰 갱신 설정을 가질 수 있습니다.
openclaw.json
{
  "channels": {
    "twitch": {
      "accounts": {
        "gaming-bot": {
          "username": "gamingbot",
          "accessToken": "oauth:token1...",
          "clientId": "client-id-1",
          "channel": "gamingchannel",
          "allowedRoles": ["subscriber"]
        },
        "mod-bot": {
          "username": "modbot",
          "accessToken": "oauth:token2...",
          "clientId": "client-id-2",
          "channel": "modchannel",
          "allowFrom": ["111222333"]
        }
      }
    }
  }
}

에이전트 도구 액션

AI 에이전트는 twitch 도구 액션을 사용하여 Twitch 채널에 메시지를 능동적으로 전송할 수 있습니다. 이를 통해 사용자의 트리거 없이도 알림, 경고, 예약된 메시지를 보낼 수 있습니다. 이 액션에는 메시지와 대상 채널(#을 접두사로 사용)이 필요합니다.
agent-action.json
{
  "action": "twitch",
  "params": {
    "message": "Hello Twitch!",
    "to": "#mychannel"
  }
}
도구 액션은 일반 채팅 메시지와 동일한 속도 제한을 따릅니다.

속도 제한 및 메시지 제약

Twitch는 채팅 메시지에 엄격한 속도 제한을 적용합니다. OpenClaw는 Twitch의 내장 속도 제한을 사용하며 추가적인 속도 제한 레이어는 없습니다. 일반(미인증) 계정: • 30초당 20개 메시지 (관리자/VIP가 아닌 경우) • 30초당 100개 메시지 (관리자/VIP/방송인) 인증된 봇 계정: • 30초당 7,500개 메시지 모든 계정은 채널당 초당 1개 메시지로 제한됩니다. 제한을 초과하는 메시지는 Twitch에 의해 자동으로 삭제됩니다. 최대 메시지 길이는 500자입니다. 더 긴 응답은 단어 경계에서 자동으로 분할됩니다.
봇이 속도 제한을 초과하면 Twitch는 오류 없이 메시지를 자동으로 삭제합니다. 활발한 채널에서 봇의 활동을 모니터링하세요.

Twitch 구성 참조

enabled
Type: booleanDefault: true

Twitch 채널 활성화 또는 비활성화

username
Type: stringDefault: ""

봇이 사용하는 Twitch 계정 이름

accessToken
Type: stringDefault: ""

chat:read 및 chat:write 스코프가 포함된 OAuth 토큰 ('oauth:'로 시작해야 함)

clientId
Type: stringDefault: ""

Twitch Developer Console에서 발급한 Client ID

channel
Type: stringDefault: ""

참여할 대상 Twitch 채널 (필수)

clientSecret
Type: stringDefault: ""

토큰 자동 갱신을 위한 Client Secret

refreshToken
Type: stringDefault: ""

토큰 자동 갱신을 위한 Refresh Token

expiresIn
Type: numberDefault: —

토큰 만료 시간 (초 단위)

obtainmentTimestamp
Type: numberDefault: —

현재 토큰이 발급된 타임스탬프 (밀리초)

allowFrom
Type: string[]Default: []

엄격한 접근 제한을 위한 Twitch 사용자 ID 허용 목록

allowedRoles
Type: string[]Default: []

역할 기반 접근 제어 (moderator, owner, vip, subscriber, all)

requireMention
Type: booleanDefault: true

봇이 응답하기 위해 @멘션이 필요한지 여부

accounts.<id>.username
Type: stringDefault: ""

다중 계정 모드에서 특정 계정의 봇 사용자 이름

accounts.<id>.accessToken
Type: stringDefault: ""

특정 계정의 OAuth 토큰

accounts.<id>.channel
Type: stringDefault: ""

특정 계정의 대상 채널

Twitch 자주 묻는 질문

Twitch 문제 해결

봇이 응답하지 않음 — 메시지에 답장하지 않음

allowFrom 목록에 사용자 ID가 포함되어 있지 않거나 봇이 @멘션을 감지하지 못하고 있을 수 있습니다.

Twitch 사용자 ID(사용자 이름이 아님)가 allowFrom 배열에 포함되어 있는지 확인하세요. 테스트를 위해 allowedRoles를 ['all']로 설정해 보세요. requireMention이 true인 경우 봇을 올바르게 @멘션하고 있는지 확인하세요.
시작 시 인증 실패

OAuth 토큰이 유효하지 않거나, 만료되었거나, 필수 스코프가 누락되었습니다.

토큰이 'oauth:'로 시작하고 chat:read 및 chat:write 스코프를 가지고 있는지 확인하세요. twitchtokengenerator.com에서 새 토큰을 생성하세요. Gateway 로그에서 구체적인 오류 메시지를 확인하세요.
토큰 갱신이 작동하지 않음

clientSecret 또는 refreshToken이 누락되었거나 올바르지 않습니다.

구성에 clientSecret과 refreshToken이 모두 제공되어 있는지 확인하세요. Client Secret은 dev.twitch.tv/console에 등록된 애플리케이션과 일치해야 합니다. 로그에서 토큰 갱신 오류 세부 정보를 확인하세요.
메시지가 자동으로 삭제됨

봇이 Twitch의 속도 제한을 초과하고 있습니다.

메시지 빈도를 줄이세요. 일반 계정은 30초당 20개 메시지로 제한됩니다(관리자는 100개). 더 높은 제한을 위해 인증된 봇 상태 신청을 고려하세요. 봇이 지나치게 긴 응답을 생성하여 많은 분할 메시지가 발생하는지 확인하세요.
봇이 연결되지만 채널에 참여하지 않음

채널 이름이 올바르지 않거나 계정이 채널에서 차단되었을 수 있습니다.

채널 이름이 올바른지 확인하세요(소문자, # 접두사 없음). Gateway 로그에서 JOIN 오류를 확인하세요. 봇 계정이 대상 채널에서 차단되거나 타임아웃 상태가 아닌지 확인하세요.
전체 문서 보기모든 채널로 돌아가기

관련 채널

WhatsApp

Medium

OpenClaw Baileys 프로토콜을 사용한 QR 코드 연결

설정 가이드

Telegram

Easy

OpenClaw grammY 프레임워크를 통한 Bot API 통합

설정 가이드

Discord

Easy

OpenClaw discord.js를 사용한 Bot Token 통합

설정 가이드