Regional platforms

QQ 봇

QQ Bot은 공식 QQ Bot API(WebSocket Gateway)를 통해 OpenClaw에 연결됩니다. 이 Plugin은 C2C 비공개 채팅, 그룹 @메시지, 길드 채널 메시지와 리치 미디어(이미지, 음성, 비디오, 파일)를 지원합니다.

상태: 다운로드 가능한 Plugin. 다이렉트 메시지, 그룹 채팅, 길드 채널 및 미디어가 지원됩니다. 반응과 스레드는 지원되지 않습니다.

설치

설정 전에 QQ Bot을 설치하세요.

openclaw plugins install @openclaw/qqbot

설정

QQ Open Platform으로 이동한 뒤 휴대폰 QQ로 QR 코드를 스캔하여 등록 / 로그인합니다.
Create Bot을 클릭하여 새 QQ Bot을 만듭니다.
Bot 설정 페이지에서 AppID와 AppSecret을 찾아 복사합니다.

AppSecret은 일반 텍스트로 저장되지 않습니다. 저장하지 않고 페이지를 떠나면 새로 다시 생성해야 합니다.

채널을 추가합니다.

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

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

Env SecretRef AppSecret:

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },
    },
  },
}

참고:

Env 대체는 기본 QQ Bot 계정에만 적용됩니다.
openclaw channels add --channel qqbot --token-file ...은 AppSecret만 제공합니다. AppID는 이미 구성이나 QQBOT_APP_ID에 설정되어 있어야 합니다.
clientSecret은 일반 텍스트 문자열뿐 아니라 SecretRef 입력도 허용합니다.
기존 secretref:/... 마커 문자열은 유효한 clientSecret 값이 아닙니다. 위 예시처럼 구조화된 SecretRef 객체를 사용하세요.

다중 계정 설정

단일 OpenClaw 인스턴스에서 여러 QQ Bot을 실행합니다.

{
  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로 두 번째 Bot을 추가합니다.

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

그룹 채팅

QQ Bot 그룹 채팅 지원은 표시 이름이 아니라 QQ 그룹 OpenID를 사용합니다. Bot을 그룹에 추가한 다음 멘션하거나, 멘션 없이 실행되도록 그룹을 구성하세요.

{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["member_openid"],
      groups: {
        "*": {
          requireMention: true,
          historyLimit: 50,
          toolPolicy: "restricted",
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          ignoreOtherMentions: true,
          historyLimit: 20,
          prompt: "Keep replies short and operational.",
        },
      },
    },
  },
}

groups["*"]는 모든 그룹의 기본값을 설정하고, 구체적인 groups.GROUP_OPENID 항목은 한 그룹에 대해 해당 기본값을 재정의합니다. 그룹 설정에는 다음이 포함됩니다.

requireMention: Bot이 답장하기 전에 @멘션을 요구합니다. 기본값: true.
ignoreOtherMentions: 다른 사람을 멘션하지만 Bot은 멘션하지 않은 메시지를 삭제합니다.
historyLimit: 다음 멘션된 차례의 컨텍스트로 최근 비멘션 그룹 메시지를 유지합니다. 비활성화하려면 0으로 설정합니다.
toolPolicy: 그룹 범위 도구에 대해 full, restricted 또는 none.
name: 로그와 그룹 컨텍스트에 사용되는 친숙한 레이블입니다.
prompt: 에이전트 컨텍스트에 추가되는 그룹별 동작 프롬프트입니다.

활성화 모드는 mention과 always입니다. requireMention: true는 mention에 매핑되고, requireMention: false는 always에 매핑됩니다. 세션 수준 활성화 재정의가 있으면 구성보다 우선합니다.

인바운드 큐는 피어별입니다. 그룹 피어는 더 큰 큐 한도를 가지며, 가득 찼을 때 Bot이 작성한 잡담보다 사람 메시지를 앞에 유지하고, 일반 그룹 메시지의 버스트를 하나의 귀속된 차례로 병합합니다. 슬래시 명령은 여전히 하나씩 실행됩니다.

음성(STT / TTS)

STT와 TTS는 우선순위 대체가 있는 2단계 구성을 지원합니다.

설정	Plugin별	프레임워크 대체값
STT	`channels.qqbot.stt`	`tools.media.audio.models[0]`
TTS	`channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts`	`messages.tts`

{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
      accounts: {
        "qq-main": {
          tts: {
            providers: {
              openai: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

비활성화하려면 둘 중 하나에 enabled: false를 설정합니다. 계정 수준 TTS 재정의는 messages.tts와 동일한 형태를 사용하며 채널/전역 TTS 구성 위에 딥 병합됩니다.

인바운드 QQ 음성 첨부 파일은 원시 음성 파일을 일반 MediaPaths 밖에 유지하면서 오디오 미디어 메타데이터로 에이전트에 노출됩니다. [[audio_as_voice]] 일반 텍스트 답장은 TTS를 합성하고, TTS가 구성되어 있으면 네이티브 QQ 음성 메시지를 전송합니다.

아웃바운드 오디오 업로드/트랜스코딩 동작은 channels.qqbot.audioFormatPolicy로도 조정할 수 있습니다.

sttDirectFormats
uploadDirectFormats
transcodeEnabled

대상 형식

형식	설명
`qqbot:c2c:OPENID`	비공개 채팅(C2C)
`qqbot:group:GROUP_OPENID`	그룹 채팅
`qqbot:channel:CHANNEL_ID`	길드 채널

각 Bot은 자체 사용자 OpenID 집합을 가집니다. Bot A가 받은 OpenID는 Bot B를 통해 메시지를 보내는 데 사용할 수 없습니다.

슬래시 명령

AI 큐 전에 가로채는 기본 제공 명령:

명령	설명
`/bot-ping`	지연 시간 테스트
`/bot-version`	OpenClaw 프레임워크 버전 표시
`/bot-help`	모든 명령 나열
`/bot-me`	`allowFrom`/`groupAllowFrom` 설정을 위한 보낸 사람의 QQ 사용자 ID(openid) 표시
`/bot-upgrade`	QQBot 업그레이드 가이드 링크 표시
`/bot-logs`	최근 Gateway 로그를 파일로 내보내기
`/bot-approve`	네이티브 흐름을 통해 보류 중인 QQ Bot 작업 승인(예: C2C 또는 그룹 업로드 확인).

사용법 도움말을 보려면 아무 명령에나 ?를 추가하세요(예: /bot-upgrade ?).

관리자 명령(/bot-me, /bot-upgrade, /bot-logs, /bot-clear-storage, /bot-streaming, /bot-approve)은 다이렉트 메시지 전용이며, 보낸 사람의 openid가 명시적인 비와일드카드 allowFrom 목록에 있어야 합니다. 와일드카드 allowFrom: ["*"]는 채팅을 허용하지만 관리자 명령 접근 권한은 부여하지 않습니다. 그룹 메시지는 먼저 groupAllowFrom과 일치시키고, 없으면 allowFrom으로 대체합니다. 그룹에서 관리자 명령을 실행하면 조용히 삭제하는 대신 힌트를 반환합니다.

엔진 아키텍처

QQ Bot은 Plugin 내부의 독립형 엔진으로 제공됩니다.

각 계정은 appId를 키로 하는 격리된 리소스 스택(WebSocket 연결, API 클라이언트, 토큰 캐시, 미디어 저장소 루트)을 소유합니다. 계정은 인바운드/아웃바운드 상태를 절대 공유하지 않습니다.
다중 계정 로거는 소유 계정으로 로그 줄에 태그를 지정하므로 하나의 Gateway에서 여러 Bot을 실행할 때도 진단을 분리해 유지할 수 있습니다.
인바운드, 아웃바운드 및 Gateway 브리지 경로는 ~/.openclaw/media 아래의 단일 미디어 페이로드 루트를 공유하므로 업로드, 다운로드 및 트랜스코딩 캐시가 서브시스템별 트리가 아니라 하나의 보호된 디렉터리 아래에 위치합니다.
리치 미디어 전달은 C2C 및 그룹 대상에 대해 하나의 sendMedia 경로를 거칩니다. 대용량 파일 임계값을 초과하는 로컬 파일과 버퍼는 QQ의 청크 업로드 엔드포인트를 사용하고, 더 작은 페이로드는 원샷 미디어 API를 사용합니다.
자격 증명은 표준 OpenClaw 자격 증명 스냅샷의 일부로 백업 및 복원할 수 있습니다. 엔진은 복원 시 새 QR 코드 페어가 필요하지 않도록 각 계정의 리소스 스택을 다시 연결합니다.

QR 코드 온보딩

AppID:AppSecret을 수동으로 붙여넣는 대신, 엔진은 QQ Bot을 OpenClaw에 연결하는 QR 코드 온보딩 흐름을 지원합니다.

QQ Bot 설정 경로(예: openclaw channels add --channel qqbot)를 실행하고 프롬프트가 표시되면 QR 코드 흐름을 선택합니다.
대상 QQ Bot에 연결된 휴대폰 앱으로 생성된 QR 코드를 스캔합니다.
휴대폰에서 페어링을 승인합니다. OpenClaw는 반환된 자격 증명을 올바른 계정 범위 아래의 credentials/에 유지합니다.

Bot 자체에서 생성된 승인 프롬프트(예: QQ Bot API가 노출하는 "이 작업을 허용하시겠습니까?" 흐름)는 원시 QQ 클라이언트를 통해 답장하는 대신 /bot-approve로 수락할 수 있는 네이티브 OpenClaw 프롬프트로 표시됩니다.

문제 해결

Bot이 "gone to Mars"라고 답장함: 자격 증명이 구성되지 않았거나 Gateway가 시작되지 않았습니다.
인바운드 메시지가 없음: appId와 clientSecret이 올바른지, 그리고 Bot이 QQ Open Platform에서 활성화되어 있는지 확인하세요.
반복되는 자기 답장: OpenClaw는 QQ 아웃바운드 참조 인덱스를 Bot 작성으로 기록하고, 현재 msgIdx가 동일한 Bot 계정과 일치하는 인바운드 이벤트를 무시합니다. 이렇게 하면 플랫폼 에코 루프를 방지하면서도 사용자가 이전 Bot 메시지를 인용하거나 답장할 수 있습니다.
--token-file로 설정해도 여전히 구성되지 않음으로 표시됨: --token-file은 AppSecret만 설정합니다. 구성 또는 QQBOT_APP_ID에 appId가 여전히 필요합니다.
사전 메시지가 도착하지 않음: 사용자가 최근에 상호작용하지 않았다면 QQ가 Bot 시작 메시지를 가로챌 수 있습니다.
음성이 전사되지 않음: STT가 구성되어 있고 공급자에 연결할 수 있는지 확인하세요.

QQ 봇

설치

설정

구성

다중 계정 설정

그룹 채팅

음성(STT / TTS)

대상 형식

슬래시 명령

엔진 아키텍처

QR 코드 온보딩

문제 해결

관련 항목

Ask OpenClaw

# 설치

# 설정

# 구성

# 다중 계정 설정

# 그룹 채팅

# 음성(STT / TTS)

# 대상 형식

# 슬래시 명령

# 엔진 아키텍처

# QR 코드 온보딩

# 문제 해결

# 관련 항목

설치

설정

구성

다중 계정 설정

그룹 채팅

음성(STT / TTS)

대상 형식

슬래시 명령

엔진 아키텍처

QR 코드 온보딩

문제 해결

관련 항목