OpenClaw Twitch 연동: 5분 만에 봇 채팅 연결하기

트위치 봇을 만들 때마다 IRC 연결이나 복잡한 인증 과정 때문에 머리 아픈 적 많으시죠? OpenClaw를 사용하면 트위치 채팅 연동을 아주 간단하게 끝낼 수 있어요.

직접 코드를 짜느라 고생할 필요 없이, 플러그인 설치와 몇 가지 설정만으로 여러분의 에이전트를 트위치 생태계에 바로 투입할 수 있습니다. 지금부터 그 방법을 친절하게 설명해 드릴게요.

Twitch (플러그인)

IRC 연결을 통해 트위치 채팅을 지원합니다. OpenClaw는 트위치 사용자(봇 계정)로 접속하여 채널에서 메시지를 주고받습니다.

플러그인 설치 (Plugin required)

Twitch는 플러그인 형태로 제공되며 기본 설치 항목에 포함되어 있지 않아요.

CLI를 통해 설치하세요 (npm 레지스트리):

openclaw plugins install @openclaw/twitch

로컬 체크아웃 (git 저장소에서 실행 중인 경우):

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

상세 내용: Plugins

빠른 설정 (초보자용) (Quick setup (beginner))

1. 봇으로 사용할 전용 트위치 계정을 만드세요 (기존 계정도 가능해요).
2. 자격 증명을 생성하세요: Twitch Token Generator
   • Bot Token을 선택하세요.
   • chat:read와 chat:write 스코프가 선택되었는지 확인하세요.
   • Client ID와 Access Token을 복사하세요.
3. 여러분의 트위치 사용자 ID를 찾으세요: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
4. 토큰을 설정하세요:
   • 환경 변수: OPENCLAW_TWITCH_ACCESS_TOKEN=... (기본 계정 전용)
   • 또는 설정 파일: channels.twitch.accessToken
   • 둘 다 설정된 경우, 설정 파일의 우선순위가 더 높습니다 (환경 변수는 기본 계정의 폴백 용도예요).
5. Gateway를 시작하세요.

⚠️ 중요: 권한이 없는 사용자가 봇을 작동시키지 못하도록 액세스 제어(allowFrom 또는 allowedRoles)를 추가하는 것이 좋습니다. requireMention은 기본적으로 true로 설정되어 있어요.

최소 설정 예시:

{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // Bot's Twitch account
      accessToken: "oauth:abc123...", // OAuth Access Token (or use OPENCLAW_TWITCH_ACCESS_TOKEN env var)
      clientId: "xyz789...", // Client ID from Token Generator
      channel: "vevisk", // Which Twitch channel's chat to join (required)
      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
    },
  },
}

기능 소개 (What it is)

• Gateway가 소유한 트위치 채널입니다.
• 결정론적 라우팅: 답장은 항상 트위치로 다시 전송됩니다.
• 각 계정은 독립된 세션 키 agent:<agentId>:twitch:<accountName>에 매핑됩니다.
• username은 인증을 받는 봇의 계정이고, channel은 참여할 채팅방을 의미해요.

상세 설정 (Setup (detailed))

자격 증명 생성

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"], // (recommended) Your Twitch user ID only
    },
  },
}

엄격한 허용 목록을 원한다면 allowFrom을 사용하세요. 역할 기반 액세스를 원한다면 대신 allowedRoles를 사용하면 됩니다.

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

왜 사용자 ID를 쓰나요? 사용자 이름은 변경될 수 있어서 사칭 위험이 있지만, 사용자 ID는 영구적이라 안전해요.

트위치 사용자 ID 찾기: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/

토큰 갱신 (선택 사항) (Token refresh (optional))

Twitch Token Generator에서 받은 토큰은 자동으로 갱신되지 않아요. 만료되면 다시 생성해야 합니다.

자동 토큰 갱신을 원한다면 Twitch Developer Console에서 직접 트위치 애플리케이션을 만들고 설정에 추가하세요:

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

봇이 만료 전에 토큰을 자동으로 갱신하고 관련 이벤트를 로그에 기록합니다.

다중 계정 지원 (Multi-account support)

계정별 토큰과 함께 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",
        },
      },
    },
  },
}

참고: 각 계정은 고유한 토큰이 필요합니다 (채널당 토큰 한 개).

액세스 제어 (Access control)

역할 기반 제한

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

문제 해결 (Troubleshooting)

먼저 진단 명령어를 실행해 보세요:

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이 제공되었는지 확인하세요.

설정 (Config)

계정 설정 (Account config):

• username - 봇 사용자 이름
• accessToken - chat:read 및 chat:write 권한이 있는 OAuth 액세스 토큰
• clientId - 트위치 Client ID (Token Generator 또는 직접 만든 앱에서 확인)
• channel - 참여할 채널 (필수)
• enabled - 계정 활성화 여부 (기본값: true)
• clientSecret - 선택 사항: 자동 토큰 갱신용
• refreshToken - 선택 사항: 자동 토큰 갱신용
• expiresIn - 토큰 만료 시간(초)
• obtainmentTimestamp - 토큰 획득 타임스탬프
• allowFrom - 사용자 ID 허용 목록
• allowedRoles - 역할 기반 액세스 제어 ("moderator" | "owner" | "vip" | "subscriber" | "all")
• requireMention - @멘션 필요 여부 (기본값: true)

프로바이더 옵션 (Provider options):

• channels.twitch.enabled - 채널 시작 활성화/비활성화
• channels.twitch.username - 봇 사용자 이름 (단일 계정 간편 설정)
• channels.twitch.accessToken - OAuth 액세스 토큰 (단일 계정 간편 설정)
• channels.twitch.clientId - 트위치 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"],
        },
      },
    },
  },
}

도구 액션 (Tool actions)

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

• send - 채널에 메시지 전송

예시:

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

보안 및 운영 (Safety & ops)

• 토큰을 비밀번호처럼 취급하세요 - 절대로 git에 토큰을 커밋하지 마세요.
• 장시간 실행되는 봇의 경우 자동 토큰 갱신을 사용하세요.
• 액세스 제어 시 사용자 이름 대신 사용자 ID 허용 목록을 사용하세요.
• 토큰 갱신 이벤트와 연결 상태를 확인하기 위해 로그를 모니터링하세요.
• 토큰 권한을 최소화하세요 - chat:read와 chat:write만 요청하세요.
• 문제가 생기면: 다른 프로세스가 세션을 점유하고 있지 않은지 확인한 후 Gateway를 재시작하세요.

제한 사항 (Limits)

• 메시지당 500자 제한 (단어 경계에서 자동으로 나뉩니다).
• 메시지를 나누기 전에 Markdown은 제거됩니다.
• 별도의 속도 제한(Rate limiting)은 없으며, 트위치 자체의 속도 제한 정책을 따릅니다.

관련 문서 (Related)

• Channels Overview — 지원되는 모든 채널
• Pairing — DM 인증 및 페어링 흐름
• Groups — 그룹 채팅 동작 및 멘션 게이팅
• Channel Routing — 메시지 세션 라우팅
• Security — 액세스 모델 및 보안 강화

AI Setup Assistant