Twitch (플러그인)
IRC 연결을 통한 Twitch 채팅 지원입니다. OpenClaw는 Twitch 사용자(봇 계정)로 연결하여 채널에서 메시지를 수신하고 전송합니다.
플러그인 필요
Twitch는 플러그인으로 제공되며 기본 코어에 포함되지 않습니다.
CLI로 설치 (npm 레지스트리):
openclaw plugins install @openclaw/twitch로컬 체크아웃 (git 저장소에서 실행 시):
openclaw plugins install ./extensions/twitch자세한 내용: Plugins
빠른 설정 (초보자)
- 봇 전용 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/
- 토큰을 설정합니다:
- 환경 변수:
OPENCLAW_TWITCH_ACCESS_TOKEN=...(기본 계정만) - 또는 설정:
channels.twitch.accessToken - 둘 다 설정된 경우 설정이 우선합니다 (환경 변수 폴백은 기본 계정에만 적용).
- 환경 변수:
- 게이트웨이를 시작합니다.
참고: 비인가 사용자가 봇을 트리거하지 못하도록 접근 제어(
allowFrom또는allowedRoles)를 추가하세요.requireMention은 기본적으로true입니다.
최소 설정:
{
channels: {
twitch: {
enabled: true,
username: "openclaw", // 봇의 Twitch 계정
accessToken: "oauth:abc123...", // OAuth Access Token (또는 OPENCLAW_TWITCH_ACCESS_TOKEN 환경 변수 사용)
clientId: "xyz789...", // Token Generator의 Client ID
channel: "vevisk", // 참여할 Twitch 채널의 채팅 (필수)
allowFrom: ["123456789"], // (권장) 본인의 Twitch 사용자 ID만 - https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ 에서 확인
},
},
}기능 설명
- 게이트웨이가 소유하는 Twitch 채널.
- 결정적 라우팅: 응답은 항상 Twitch로 돌아갑니다.
- 각 계정은 격리된 세션 키
agent:<agentId>:twitch:<accountName>에 매핑됩니다. username은 봇의 계정(인증 주체),channel은 참여할 채팅방입니다.
설정 (상세)
자격 증명 생성
Twitch Token Generator를 사용합니다:
- Bot Token을 선택합니다
chat:read와chat:write스코프가 선택되었는지 확인합니다- Client ID와 Access Token을 복사합니다
별도의 앱 등록이 필요 없습니다. 토큰은 몇 시간 후에 만료됩니다.
봇 설정
환경 변수 (기본 계정만):
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...또는 설정:
{
channels: {
twitch: {
enabled: true,
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
},
}환경 변수와 설정 모두 있으면 설정이 우선합니다.
접근 제어 (권장)
{
channels: {
twitch: {
allowFrom: ["123456789"], // (권장) 본인의 Twitch 사용자 ID만
},
},
}allowFrom을 하드 허용 목록으로 사용하세요. 역할 기반 접근을 원하면 대신 allowedRoles를 사용하세요.
사용 가능한 역할: "moderator", "owner", "vip", "subscriber", "all".
사용자 ID를 사용하는 이유: 사용자 이름은 변경 가능하여 사칭이 가능합니다. 사용자 ID는 영구적입니다.
Twitch 사용자 ID 찾기: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/
토큰 갱신 (선택)
Twitch Token Generator에서 발급한 토큰은 자동 갱신이 불가능합니다. 만료되면 재생성하세요.
자동 토큰 갱신을 위해 Twitch Developer Console에서 직접 Twitch 애플리케이션을 만들고 설정에 추가합니다:
{
channels: {
twitch: {
clientSecret: "your_client_secret",
refreshToken: "your_refresh_token",
},
},
}봇이 만료 전에 자동으로 토큰을 갱신하고 갱신 이벤트를 로그에 기록합니다.
다중 계정 지원
channels.twitch.accounts에 계정별 토큰을 사용합니다. 공유 패턴은 gateway/configuration을 참조하세요.
예시 (한 봇 계정을 두 채널에서 사용):
{
channels: {
twitch: {
accounts: {
channel1: {
username: "openclaw",
accessToken: "oauth:abc123...",
clientId: "xyz789...",
channel: "vevisk",
},
channel2: {
username: "openclaw",
accessToken: "oauth:def456...",
clientId: "uvw012...",
channel: "secondchannel",
},
},
},
},
}참고: 각 계정에는 자체 토큰이 필요합니다 (채널당 하나의 토큰).
접근 제어
역할 기반 제한
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator", "vip"],
},
},
},
},
}사용자 ID 허용 목록 (가장 안전)
{
channels: {
twitch: {
accounts: {
default: {
allowFrom: ["123456789", "987654321"],
},
},
},
},
}역할 기반 접근 (대안)
allowFrom은 하드 허용 목록입니다. 설정하면 해당 사용자 ID만 허용됩니다.
역할 기반 접근을 원하면 allowFrom을 설정하지 않고 대신 allowedRoles를 구성하세요:
{
channels: {
twitch: {
accounts: {
default: {
allowedRoles: ["moderator"],
},
},
},
},
}@멘션 요구 비활성화
기본적으로 requireMention은 true입니다. 모든 메시지에 응답하려면 비활성화하세요:
{
channels: {
twitch: {
accounts: {
default: {
requireMention: false,
},
},
},
},
}문제 해결
먼저 진단 명령을 실행하세요:
openclaw doctor
openclaw channels status --probe봇이 메시지에 응답하지 않는 경우
접근 제어 확인: 사용자 ID가 allowFrom에 있는지 확인하거나, 테스트를 위해 allowFrom을 일시적으로 제거하고 allowedRoles: ["all"]을 설정하세요.
봇이 채널에 있는지 확인: 봇은 channel에 지정된 채널에 참여해야 합니다.
토큰 문제
“Failed to connect” 또는 인증 오류:
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이 제공되었는지 확인
설정
계정 설정:
username- 봇 사용자 이름accessToken-chat:read와chat:write가 있는 OAuth 액세스 토큰clientId- Twitch Client ID (Token Generator 또는 직접 생성한 앱)channel- 참여할 채널 (필수)enabled- 이 계정 활성화 (기본값:true)clientSecret- 선택: 자동 토큰 갱신용refreshToken- 선택: 자동 토큰 갱신용expiresIn- 토큰 만료 시간 (초)obtainmentTimestamp- 토큰 발급 타임스탬프allowFrom- 사용자 ID 허용 목록allowedRoles- 역할 기반 접근 제어 ("moderator" | "owner" | "vip" | "subscriber" | "all")requireMention- @멘션 필요 (기본값:true)
제공자 옵션:
channels.twitch.enabled- 채널 시작 활성화/비활성화channels.twitch.username- 봇 사용자 이름 (단순화된 단일 계정 설정)channels.twitch.accessToken- OAuth 액세스 토큰 (단순화된 단일 계정 설정)channels.twitch.clientId- Twitch Client ID (단순화된 단일 계정 설정)channels.twitch.channel- 참여할 채널 (단순화된 단일 계정 설정)channels.twitch.accounts.<accountName>- 다중 계정 설정 (위의 모든 계정 필드)
전체 예시:
{
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"],
},
},
},
},
}도구 액션
에이전트가 twitch 액션을 호출할 수 있습니다:
send- 채널에 메시지 전송
예시:
{
action: "twitch",
params: {
message: "Hello Twitch!",
to: "#mychannel",
},
}보안 및 운영
- 토큰은 비밀번호처럼 취급하세요 - 토큰을 git에 커밋하지 마세요
- 장기 실행 봇에는 자동 토큰 갱신을 사용하세요
- 접근 제어에는 사용자 이름 대신 사용자 ID 허용 목록을 사용하세요
- 토큰 갱신 이벤트와 연결 상태를 로그로 모니터링하세요
- 토큰 스코프를 최소화하세요 -
chat:read와chat:write만 요청 - 문제가 발생하면: 다른 프로세스가 세션을 소유하지 않는 것을 확인한 후 게이트웨이를 재시작하세요
제한
- 메시지당 500자 (단어 경계에서 자동 분할)
- 마크다운은 분할 전에 제거됩니다
- 속도 제한 없음 (Twitch의 내장 속도 제한 사용)