QQ 봇

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

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

설치

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

openclaw plugins install @openclaw/qqbot

설정

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

환경 변수 SecretRef AppSecret:

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

참고:

• 환경 변수 폴백은 기본 QQ Bot 계정에만 적용됩니다.
• openclaw channels add --channel qqbot --token-file ...은 AppSecret만 제공합니다. AppID는 구성 또는 QQBOT_APP_ID에 이미 설정되어 있어야 합니다.
• clientSecret은 일반 텍스트 문자열뿐 아니라 SecretRef 입력도 허용합니다.
• 레거시 secretref:/... 마커 문자열은 유효한 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"

그룹 채팅

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

{  channels: {    qqbot: {      groupPolicy: "allowlist",      groupAllowFrom: ["member_openid"],      groups: {        "*": {          requireMention: true,          commandLevel: "all",          historyLimit: 50,          tools: { deny: ["exec", "read", "write"] },        },        GROUP_OPENID: {          name: "Release room",          requireMention: false,          ignoreOtherMentions: true,          commandLevel: "safety",          historyLimit: 20,          prompt: "Keep replies short and operational.",        },      },    },  },}

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

• requireMention: 봇이 응답하기 전에 @멘션을 요구합니다. 기본값: true.
• commandLevel: 그룹에서 실행할 수 있는 내장 슬래시 명령을 제어합니다. 기본값: all이며, 설정이 생략되었을 때 기존 QQBot 그룹 동작을 보존합니다.
• ignoreOtherMentions: 봇이 아닌 다른 사람을 멘션한 메시지를 버립니다.
• historyLimit: 다음 멘션된 턴의 컨텍스트로 최근 비멘션 그룹 메시지를 유지합니다. 비활성화하려면 0으로 설정합니다.
• tools: 전체 그룹에 대해 도구를 허용하거나 거부합니다.
• toolsBySender: 발신자별 그룹 도구 재정의입니다. 그룹을 참조하세요.
• name: 로그와 그룹 컨텍스트에 사용되는 친숙한 레이블입니다.
• prompt: 에이전트 컨텍스트에 추가되는 그룹별 동작 프롬프트입니다.

commandLevel은 다음을 허용합니다.

• all: 인식된 내장 명령을 이전처럼 사용할 수 있게 유지합니다. 일부 명령은 메뉴에서 계속 숨겨질 수 있지만, 권한이 있는 사용자는 그룹에서 여전히 실행할 수 있습니다.
• safety: /help, /btw, /stop 같은 일반 협업 명령을 허용하고, /config, /tools, /bash 같은 민감한 명령은 비공개 채팅에서 실행하도록 사용자에게 안내합니다.
• strict: 엄격한 그룹 운영에 필요한 그룹 세션 제어만 허용합니다. /stop은 권한이 있는 발신자가 활성 실행을 중단할 수 있도록 여전히 긴급 상태로 유지됩니다.

이전 QQBot toolPolicy 항목은 폐기되었습니다. openclaw doctor --fix를 실행하여 tools로 마이그레이션하세요.

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

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

음성(STT / TTS)

STT와 TTS는 우선순위 폴백이 있는 2단계 구성을 지원합니다.

{  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

대상 형식

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

슬래시 명령

AI 큐 전에 가로채는 내장 명령:

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

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

QQ Bot exec 승인이 기본 동일 채팅 폴백을 사용할 때, 네이티브 승인 버튼 클릭은 동일한 명시적 비와일드카드 명령 허용 목록을 따릅니다. 더 넓은 명령 접근 없이 승인 전용 접근 권한을 부여하려면 channels.qqbot.execApprovals.approvers를 구성하세요.

엔진 아키텍처

QQ Bot은 Plugin 내부에 자체 완결형 엔진으로 제공됩니다.

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

QR 코드 온보딩

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

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

봇 자체가 생성한 승인 프롬프트(예: 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만 설정합니다. 구성의 appId 또는 QQBOT_APP_ID도 여전히 필요합니다.
• 사전 메시지가 도착하지 않음: 사용자가 최근에 상호작용하지 않았다면 QQ가 bot 시작 메시지를 가로챌 수 있습니다.
• 음성이 전사되지 않음: STT가 구성되어 있고 제공자에 연결할 수 있는지 확인하세요.

관련 항목

• 페어링
• 그룹
• 채널 문제 해결