OpenClaw QQ Bot 연동: 5분 만에 봇 설정 완료하기

봇을 만들 때 가장 번거로운 게 바로 API 연동이죠. 특히 공식 API를 사용하려면 설정할 게 한두 개가 아니어서 시작하기도 전에 지치곤 합니다. OpenClaw를 사용하면 QQ Bot을 훨씬 쉽고 빠르게 연결할 수 있어요.

QQ Bot은 공식 QQ Bot API(WebSocket gateway)를 통해 OpenClaw에 연결됩니다. 이 플러그인은 C2C 개인 채팅, 그룹 @메시지, 그리고 이미지, 음성, 비디오, 파일을 포함한 리치 미디어가 지원되는 길드 채널 메시지를 지원해요.

현재 상태: 번들 채널 플러그인입니다. 다이렉트 메시지, 그룹 채팅, 길드 채널 및 미디어가 지원됩니다. 리액션과 스레드는 지원되지 않아요.

OpenClaw에 기본 포함

현재 OpenClaw 설치 버전에는 QQ Bot이 기본으로 포함되어 있어요. 일반적인 설정을 위해 별도로 openclaw plugins install 단계를 거칠 필요가 없습니다.

설정하기

1. QQ Open Platform에 접속해서 휴대폰 QQ로 QR 코드를 스캔해 등록하거나 로그인하세요.
2. Create Bot을 클릭해서 새로운 QQ 봇을 만듭니다.
3. 봇의 설정 페이지에서 AppID와 AppSecret을 찾아 복사하세요.

AppSecret은 평문으로 저장되지 않아요. 저장하지 않고 페이지를 나가면 새로운 비밀번호를 다시 생성해야 합니다.

4. 채널을 추가하세요:

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. Gateway를 재시작하세요.

대화형 설정 경로:

openclaw channels add
openclaw configure --section channels

구성하기

최소 설정:

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
}

기본 계정 환경 변수:

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

파일 기반 AppSecret:

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "/path/to/qqbot-secret.txt",
    },
  },
}

참고 사항:

• 환경 변수 fallback은 기본 QQ Bot 계정에만 적용됩니다.
• openclaw channels add --channel qqbot --token-file ...은 AppSecret만 제공해요. AppID는 설정 파일이나 QQBOT_APP_ID에 이미 설정되어 있어야 합니다.
• clientSecret은 평문 문자열뿐만 아니라 SecretRef 입력도 지원해요.

다중 계정 설정

단일 OpenClaw 인스턴스에서 여러 개의 QQ 봇을 실행할 수 있어요:

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "111111111",
      clientSecret: "secret-of-bot-1",
      accounts: {
        bot2: {
          enabled: true,
          appId: "222222222",
          clientSecret: "secret-of-bot-2",
        },
      },
    },
  },
}

각 계정은 자체 WebSocket 연결을 시작하고 독립적인 토큰 캐시를 유지합니다(appId로 구분).

CLI를 통해 두 번째 봇을 추가하는 방법:

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

음성 (STT / TTS)

STT와 TTS는 우선순위 fallback이 포함된 2단계 설정을 지원합니다:

설정	플러그인 전용	프레임워크 fallback
STT	channels.qqbot.stt	tools.media.audio.models[0]
TTS	channels.qqbot.tts	messages.tts

{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
    },
  },
}

비활성화하려면 둘 중 하나에 enabled: false를 설정하세요.

아웃바운드 오디오 업로드/트랜스코드 동작은 channels.qqbot.audioFormatPolicy로 조정할 수 있어요:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

대상 포맷

포맷	설명
qqbot:c2c:OPENID	개인 채팅 (C2C)
qqbot:group:GROUP_OPENID	그룹 채팅
qqbot:channel:CHANNEL_ID	길드 채널

각 봇은 고유한 사용자 OpenID 세트를 가집니다. 봇 A가 받은 OpenID를 사용해서 봇 B를 통해 메시지를 보낼 수는 없어요.

슬래시 명령어

AI 큐에 들어가기 전에 가로채는 내장 명령어들입니다:

명령어	설명
/bot-ping	지연 시간 테스트
/bot-version	OpenClaw 프레임워크 버전 표시
/bot-help	모든 명령어 목록 표시
/bot-upgrade	QQBot 업그레이드 가이드 링크 표시
/bot-logs	최근 gateway 로그를 파일로 내보내기

명령어 뒤에 ?를 붙이면 사용법 도움말을 볼 수 있어요 (예: /bot-upgrade ?).

문제 해결

• 봇이 “gone to Mars”라고 응답함: 인증 정보가 구성되지 않았거나 Gateway가 시작되지 않았습니다.
• 수신 메시지가 없음: appId와 clientSecret이 정확한지, 그리고 QQ Open Platform에서 봇이 활성화되어 있는지 확인하세요.
• --token-file로 설정했는데도 구성되지 않음으로 표시됨: --token-file은 AppSecret만 설정합니다. 설정 파일이나 QQBOT_APP_ID에 appId가 여전히 필요해요.
• 능동적 메시지(Proactive messages)가 도착하지 않음: 사용자가 최근에 상호작용하지 않은 경우 QQ에서 봇이 시작한 메시지를 차단할 수 있습니다.
• 음성이 텍스트로 변환되지 않음: STT가 구성되어 있고 제공자(provider)에 접속 가능한지 확인하세요.

AI Setup Assistant