Twitch (플러그인)

IRC 연결을 통한 Twitch 채팅 지원. OpenClaw는 Twitch 사용자(봇 계정)로 연결하여 채널에서 메시지를 수신하고 전송합니다.

플러그인 필요

Twitch는 플러그인으로 제공되며 코어 설치에 포함되어 있지 않습니다.

CLI를 통한 설치 (npm 레지스트리):

openclaw plugins install @openclaw/twitch

로컬 체크아웃 (git 저장소에서 실행 시):

openclaw plugins install ./extensions/twitch

자세한 내용: Plugins

빠른 설정 (초보자)

  1. 봇을 위한 전용 Twitch 계정을 생성합니다 (또는 기존 계정 사용).
  2. 자격 증명 생성: Twitch Token Generator
    • Bot Token 선택
    • chat:read 및 chat:write scope가 선택되었는지 확인
    • Client ID와 Access Token을 복사
  3. Twitch 사용자 ID 찾기: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. 토큰 구성:
    • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (기본 계정만)
    • 또는 config: channels.twitch.accessToken
    • 둘 다 설정된 경우 config가 우선합니다 (env 폴백은 기본 계정만).
  5. Gateway를 시작합니다.

⚠️ 중요: 무단 사용자가 봇을 트리거하지 못하도록 접근 제어(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/ 에서 가져오세요
    }
  }
}

무엇인가

  • Gateway가 소유한 Twitch 채널입니다.
  • 결정론적 라우팅: 답장은 항상 Twitch로 돌아갑니다.
  • 각 계정은 격리된 세션 키 agent:<agentId>:twitch:<accountName>에 매핑됩니다.
  • username은 봇의 계정(인증하는 사람)이고, channel은 참여할 채팅방입니다.

설정 (상세)

자격 증명 생성

Twitch Token Generator 사용:

  • Bot Token 선택
  • chat:read 및 chat:write scope가 선택되었는지 확인
  • Client ID와 Access Token을 복사

수동 앱 등록이 필요하지 않습니다. 토큰은 몇 시간 후 만료됩니다.

봇 구성

환경 변수 (기본 계정만):

OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

또는 config:

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

env와 config가 모두 설정된 경우 config가 우선합니다.

접근 제어 (권장)

{
  channels: {
    twitch: {
      allowFrom: ["123456789"],       // (권장) 귀하의 Twitch 사용자 ID만
      allowedRoles: ["moderator"]     // 또는 역할로 제한
    }
  }
}

사용 가능한 역할: "moderator", "owner", "vip", "subscriber", "all".

왜 사용자 ID인가? 사용자 이름은 변경될 수 있어 사칭이 가능합니다. 사용자 ID는 영구적입니다.

Twitch 사용자 ID 찾기: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ (Twitch 사용자 이름을 ID로 변환)

토큰 갱신 (선택 사항)

Twitch Token Generator의 토큰은 자동으로 갱신할 수 없습니다 - 만료 시 재생성하세요.

자동 토큰 갱신을 위해서는 Twitch Developer Console에서 자체 Twitch 애플리케이션을 생성하고 config에 추가하세요:

{
  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별 Allowlist (가장 안전)

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

Allowlist + 역할 조합

allowFrom의 사용자는 역할 체크를 우회합니다:

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

@멘션 요구사항 비활성화

기본적으로 requireMention은 true입니다. 비활성화하고 모든 메시지에 응답하려면:

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

문제 해결

먼저 진단 명령을 실행하세요:

openclaw doctor
openclaw channels status --probe

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

접근 제어 확인: 테스트를 위해 임시로 allowedRoles: ["all"]을 설정하세요.

봇이 채널에 있는지 확인: 봇은 channel에 지정된 채널에 참여해야 합니다.

토큰 문제

"Failed to connect" 또는 인증 오류:

  • accessToken이 OAuth access token 값인지 확인 (일반적으로 oauth: 접두사로 시작)
  • 토큰에 chat:read 및 chat:write scope가 있는지 확인
  • 토큰 갱신을 사용하는 경우 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이 제공되었는지 확인

Config

계정 config:

  • username - 봇 사용자 이름
  • accessToken - chat:read 및 chat:write를 포함한 OAuth access token
  • clientId - Twitch Client ID (Token Generator 또는 귀하의 앱에서)
  • channel - 참여할 채널 (필수)
  • enabled - 이 계정 활성화 (기본값: true)
  • clientSecret - 선택 사항: 자동 토큰 갱신용
  • refreshToken - 선택 사항: 자동 토큰 갱신용
  • expiresIn - 토큰 만료 시간(초)
  • obtainmentTimestamp - 토큰 획득 타임스탬프
  • allowFrom - 사용자 ID allowlist
  • allowedRoles - 역할 기반 접근 제어 ("moderator" | "owner" | "vip" | "subscriber" | "all")
  • requireMention - @멘션 필요 (기본값: true)

Provider 옵션:

  • channels.twitch.enabled - 채널 시작 활성화/비활성화
  • channels.twitch.username - 봇 사용자 이름 (단순화된 단일 계정 config)
  • channels.twitch.accessToken - OAuth access token (단순화된 단일 계정 config)
  • channels.twitch.clientId - Twitch Client ID (단순화된 단일 계정 config)
  • channels.twitch.channel - 참여할 채널 (단순화된 단일 계정 config)
  • channels.twitch.accounts.<accountName> - 다중 계정 config (위의 모든 계정 필드)

전체 예시:

{
  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

에이전트는 다음 action으로 twitch를 호출할 수 있습니다:

  • send - 채널에 메시지 전송

예시:

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

안전성 & 운영

  • 토큰을 비밀번호처럼 취급하세요 - 토큰을 git에 커밋하지 마세요
  • 장기 실행 봇에 자동 토큰 갱신 사용
  • 접근 제어를 위해 사용자 이름 대신 사용자 ID allowlist 사용
  • 토큰 갱신 이벤트 및 연결 상태 로그 모니터링
  • 토큰을 최소한으로 scope - chat:read 및 chat:write만 요청
  • 문제가 있는 경우: 다른 프로세스가 세션을 소유하지 않는지 확인한 후 Gateway를 재시작하세요

제한사항

  • 메시지당 500자 (단어 경계에서 자동 청킹)
  • 청킹 전에 Markdown이 제거됩니다
  • 속도 제한 없음 (Twitch의 내장 속도 제한 사용)
← 문서로 돌아가기