메인 콘텐츠로 건너뛰기

​
Twitch

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

​
번들 plugin

Twitch는 현재 OpenClaw 릴리스에 번들 plugin으로 포함되어 있으므로 일반 패키지 빌드에서는 별도 설치가 필요하지 않습니다. 이전 빌드 또는 Twitch가 제외된 사용자 지정 설치를 사용하는 경우 수동으로 설치하세요. CLI를 통해 설치(npm 레지스트리): 
openclaw plugins install @openclaw/twitch
로컬 체크아웃(git 리포지토리에서 실행하는 경우): 
openclaw plugins install ./path/to/local/twitch-plugin
자세한 내용: Plugins

​
빠른 설정(초보자용)

  1. Twitch plugin을 사용할 수 있는지 확인합니다.
    • 현재 패키지된 OpenClaw 릴리스에는 이미 번들로 포함되어 있습니다.
    • 이전/사용자 지정 설치에서는 위 명령으로 수동 추가할 수 있습니다.
  2. 봇용 전용 Twitch 계정을 생성합니다(또는 기존 계정을 사용합니다).
  3. 자격 증명을 생성합니다: Twitch Token Generator
    • Bot Token을 선택합니다
    • chat:read 및 chat:write 스코프가 선택되었는지 확인합니다
    • Client ID 및 Access Token을 복사합니다
  4. Twitch 사용자 ID를 찾습니다: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  5. 토큰을 구성합니다.
    • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (기본 계정 전용)
    • 또는 config: channels.twitch.accessToken
    • 둘 다 설정된 경우 config가 우선합니다(env 폴백은 기본 계정 전용).
  6. gateway를 시작합니다.
⚠️ 중요: 승인되지 않은 사용자가 봇을 트리거하지 못하도록 액세스 제어(allowFrom 또는 allowedRoles)를 추가하세요. requireMention의 기본값은 true입니다. 최소 구성: 
{
  channels: {
    twitch: {
      enabled: true,
      username: "openclaw", // 봇의 Twitch 계정
      accessToken: "oauth:abc123...", // OAuth 액세스 토큰(또는 OPENCLAW_TWITCH_ACCESS_TOKEN env var 사용)
      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 스코프가 선택되었는지 확인합니다
  • Client ID 및 Access Token을 복사합니다
수동 앱 등록은 필요하지 않습니다. 토큰은 몇 시간 후 만료됩니다.

​
봇 구성

Env var(기본 계정 전용): 
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만 허용
    },
  },
}
강력한 허용 목록에는 allowFrom을 우선 사용하세요. 역할 기반 액세스를 원하면 대신 allowedRoles를 사용하세요. 사용 가능한 역할: "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별 허용 목록(가장 안전함)

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

​
역할 기반 액세스(대안)

allowFrom은 강력한 허용 목록입니다. 설정하면 해당 사용자 ID만 허용됩니다. 역할 기반 액세스를 원하면 allowFrom은 설정하지 말고 대신 allowedRoles를 구성하세요. 
{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator"],
        },
      },
    },
  },
}

​
@mention 요구 사항 비활성화

기본적으로 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이 제공되었는지 확인하세요

​
Config

계정 config:
  • 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 - @mention 필요(기본값: true)
Provider 옵션:
  • channels.twitch.enabled - 채널 시작 활성화/비활성화
  • channels.twitch.username - 봇 사용자 이름(단순화된 단일 계정 config)
  • channels.twitch.accessToken - OAuth 액세스 토큰(단순화된 단일 계정 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"],
        },
      },
    },
  },
}

​
도구 작업

에이전트는 다음 작업으로 twitch를 호출할 수 있습니다.
  • send - 채널에 메시지 보내기
예시: 
{
  action: "twitch",
  params: {
    message: "Hello Twitch!",
    to: "#mychannel",
  },
}

​
안전 및 운영

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

​
제한

  • 메시지당 500자(단어 경계 기준 자동 청킹)
  • 청킹 전에 Markdown이 제거됩니다
  • 속도 제한 없음(Twitch의 내장 rate limit 사용)

​
관련 문서