OpenClaw 한국어 문서

다크 모드

트위치(플러그인) ​

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

플러그인이 필요합니다 ​

Twitch는 플러그인으로 제공되며 핵심 설치와 함께 번들로 제공되지 않습니다.

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

bash
openclaw plugins install @openclaw/twitch

로컬 체크아웃(git repo에서 실행하는 경우):

bash
openclaw plugins install ./extensions/twitch

세부정보: 플러그인

빠른 설정(초보자) ​

  1. 봇 전용 Twitch 계정을 만듭니다(또는 기존 계정 사용).
  2. 자격 증명 생성: Twitch 토큰 생성기
    • 봇 토큰을 선택하세요.
    • 범위 chat:read 및 chat:write가 선택되었는지 확인합니다.
    • 클라이언트 ID 및 액세스 토큰을 복사합니다.
  3. Twitch 사용자 ID를 찾으세요: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
  4. 토큰을 구성합니다.
    • Env: OPENCLAW_TWITCH_ACCESS_TOKEN=... (기본 계정만 해당)
    • 또는 구성: channels.twitch.accessToken
    • 둘 다 설정된 경우 구성이 우선 적용됩니다(환경 폴백은 기본 계정에만 해당).
  5. 게이트웨이를 시작합니다.

⚠️ 중요: 승인되지 않은 사용자가 봇을 트리거하는 것을 방지하려면 액세스 제어(allowFrom 또는 allowedRoles)를 추가하세요. requireMention의 기본값은 true입니다.

최소 구성:

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

그게 뭐야? ​

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

설정(상세) ​

자격 증명 생성 ​

Twitch 토큰 생성기 사용:

  • 봇 토큰을 선택하세요.
  • 범위 chat:read 및 chat:write가 선택되었는지 확인합니다.
  • 클라이언트 ID 및 액세스 토큰을 복사합니다.

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

봇 구성 ​

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

bash
OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123...

또는 구성:

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

env와 config가 모두 설정된 경우 config가 우선 적용됩니다.

접근 제어(권장) ​

json5
{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
    },
  },
}

하드 허용 목록의 경우 allowFrom를 선호합니다. 역할 기반 액세스를 원하는 경우 allowedRoles를 대신 사용하세요.

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

사용자 ID가 필요한 이유는 무엇입니까? 사용자 이름은 변경되어 명의 도용이 허용될 수 있습니다. 사용자 ID는 영구적입니다.

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

토큰 새로고침(선택사항) ​

Twitch 토큰 생성기의 토큰은 자동으로 새로 고칠 수 없습니다. 만료되면 다시 생성됩니다.

자동 토큰 새로고침을 위해서는 Twitch 개발자 콘솔에서 자신만의 Twitch 애플리케이션을 만들고 구성에 추가하세요.

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

봇은 만료되기 전에 자동으로 토큰을 새로 고치고 새로 고침 이벤트를 기록합니다.

다중 계정 지원 ​

계정별 토큰과 함께 channels.twitch.accounts를 사용하세요. 공유 패턴은 gateway/configuration을 참조하세요.

예(두 채널에 하나의 봇 계정):

json5
{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "openclaw",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "vevisk",
        },
        channel2: {
          username: "openclaw",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel",
        },
      },
    },
  },
}

참고: 각 계정에는 자체 토큰이 필요합니다(채널당 토큰 1개).

접근 제어 ​

역할 기반 제한 ​

json5
{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator", "vip"],
        },
      },
    },
  },
}

사용자 ID별 허용 목록(가장 안전함) ​

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

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

allowFrom는 하드 허용 목록입니다. 설정되면 해당 사용자 ID만 허용됩니다. 역할 기반 액세스를 원할 경우 allowFrom를 설정하지 않고 대신 allowedRoles를 구성합니다.

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

@멘션 요구 사항 비활성화 ​

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

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

문제 해결 ​

먼저 진단 명령을 실행합니다.

bash
openclaw doctor
openclaw channels status --probe

봇이 메시지에 응답하지 않습니다. ​

접근 제어 확인: 사용자 ID가 allowFrom에 있는지 확인하거나 임시로 삭제하세요. allowFrom 및 allowedRoles: ["all"]를 설정하여 테스트합니다.

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

토큰 문제 ​

"연결 실패" 또는 인증 오류:

  • accessToken가 OAuth 액세스 토큰 값인지 확인합니다(일반적으로 oauth: 접두사로 시작함).
  • 토큰에 chat:read 및 chat:write 범위가 있는지 확인하세요.
  • 토큰 새로 고침을 사용하는 경우 clientSecret 및 refreshToken가 설정되어 있는지 확인하세요.

토큰 새로 고침이 작동하지 않습니다. ​

새로고침 이벤트 로그를 확인하세요.

Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)

"토큰 새로 고침 비활성화됨(새로 고침 토큰 없음)"이 표시되는 경우:

  • clientSecret가 제공되었는지 확인하세요.
  • refreshToken가 제공되었는지 확인하세요.

구성 ​

계정 구성:

  • username - 봇 사용자 이름
  • accessToken - chat:read 및 chat:write를 사용한 OAuth 액세스 토큰
  • clientId - Twitch 클라이언트 ID(토큰 생성기 또는 앱에서)
  • 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 클라이언트 ID(단순화된 단일 계정 구성)
  • channels.twitch.channel - 가입할 채널(단순 계정 구성)
  • channels.twitch.accounts.<accountName> - 다중 계정 구성(위의 모든 계정 필드)

전체 예:

json5
{
  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 - 채널에 메시지 보내기

예:

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

안전 및 운영 ​

  • 토큰을 비밀번호처럼 취급하세요 - Git에 토큰을 커밋하지 마세요.
  • 장기 실행 봇의 경우 자동 토큰 새로 고침 사용
  • 액세스 제어를 위해 사용자 이름 대신 사용자 ID 허용 목록 사용
  • 토큰 새로 고침 이벤트 및 연결 상태에 대한 모니터 로그
  • 범위 토큰은 최소화 - chat:read 및 chat:write만 요청
  • 멈춘 경우: 세션을 소유한 다른 프로세스가 없는지 확인한 후 게이트웨이를 다시 시작합니다.

한도 ​

  • 메시지당 500자(단어 경계에서 자동 청크됨)
  • 마크다운은 청크 전에 제거됩니다.
  • 속도 제한 없음(Twitch에 내장된 속도 제한 사용)

비공식 커뮤니티 번역 · 공식 영문 문서

OpenClaw 프로젝트에 의해 MIT 라이선스로 배포됨