QQ 봇

​

설치

openclaw plugins install @openclaw/qqbot

​

설정

1. QQ Open Platform으로 이동한 후 휴대전화의 QQ로 QR 코드를 스캔하여 등록하거나 로그인하십시오.
2. 새 QQ 봇을 만들려면 Create Bot을 클릭하십시오.
3. 봇의 설정 페이지에서 AppID와 AppSecret을 찾아 복사하십시오.

4. 채널을 추가하십시오.

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

5. Gateway를 다시 시작하십시오.

openclaw channels add

​

구성

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

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

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

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

• openclaw channels add --channel qqbot --token-file ...은 AppSecret만 설정합니다. appId는 구성 또는 QQBOT_APP_ID에 이미 설정되어 있어야 합니다.
• clientSecret은 평문 문자열, 파일 경로(clientSecretFile) 또는 구조화된 SecretRef 객체를 허용합니다.
• 레거시 secretref:... / secretref-env:... 마커 문자열은 clientSecret에서 거부됩니다. 대신 구조화된 SecretRef 객체를 사용하십시오.

​

스트리밍

{
  channels: {
    qqbot: {
      streaming: {
        mode: "partial", // 블록 스트리밍: "partial"(기본값) 또는 "off"
        nativeTransport: true, // DM에 QQ의 공식 C2C stream_messages API 사용
      },
    },
  },
}

• streaming.mode: "off"은 계정의 블록 스트리밍을 비활성화합니다.
• streaming.nativeTransport: true은 QQ의 공식 stream_messages API를 통해 C2C(DM) 응답을 스트리밍합니다. 그룹/채널 대상에는 영향을 주지 않습니다.
• 레거시 streaming: true|false 스칼라와 streaming.c2cStreamApi 키는 openclaw doctor --fix을 통해 이 형태로 마이그레이션됩니다.
• /bot-streaming on|off은 DM에서 동일한 구성을 전환합니다.

​

접근 정책

• allowFrom / groupAllowFrom은 C2C / 그룹 컨텍스트에서 봇과 채팅할 수 있는 사용자를 제한합니다. dmPolicy / groupPolicy (open | allowlist | disabled)은 적용 모드를 제어합니다. dmPolicy는 allowFrom에 구체적인(와일드카드가 아닌) 항목이 있으면 allowlist이 기본값이고, 그렇지 않으면 open이 기본값입니다. groupPolicy는 groupAllowFrom 또는 allowFrom 중 하나에 구체적인 항목이 있으면 allowlist이 기본값이고, 그렇지 않으면 open이 기본값입니다.
• “인증: 허용 목록” 슬래시 명령은 dmPolicy / groupPolicy과 관계없이 allowFrom(또는 그룹에서 호출할 경우 groupAllowFrom)에 명시적인 비와일드카드 항목이 있어야 합니다. 슬래시 명령을 참조하십시오.

​

다중 계정 설정

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

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

​

그룹 채팅

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

​

음성(STT / 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" },
            },
          },
        },
      },
    },
  },
}

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

​

대상 형식

​

슬래시 명령

​

미디어 및 저장소

• 인바운드, 아웃바운드 및 Gateway 브리지 미디어는 ~/.openclaw/media/qqbot 아래의 단일 페이로드 루트를 공유하므로(OPENCLAW_HOME이 설정된 경우 이를 따름), 업로드, 다운로드 및 트랜스코딩 캐시가 하나의 보호된 디렉터리 아래에 유지됩니다.
• C2C 및 그룹 대상에 대한 리치 미디어 전송은 단일 sendMedia 경로를 거칩니다. 5 MiB 이상의 로컬 파일과 메모리 내 버퍼는 QQ의 청크 업로드 엔드포인트를 사용하며, 더 작은 페이로드와 원격 URL/Base64 소스는 일회성 업로드 API를 사용합니다.
• Gateway가 openclaw.json 쓰기를 완료하기 전에 핫 업그레이드로 중단된 경우, Plugin은 다음 시작 시 내부 스냅샷에서 해당 계정의 마지막으로 확인된 appId / clientSecret을 복원하므로(의도적인 구성 변경은 절대 덮어쓰지 않음) QR 코드를 다시 스캔할 필요가 없습니다.

​

문제 해결

• Gateway가 시작되지 않음 / 인바운드 메시지가 없음: appId 및 clientSecret이 올바른지, QQ Open Platform에서 봇이 활성화되어 있는지 확인하십시오. 자격 증명이 없으면 “QQBot not configured (missing appId or clientSecret)“이 표시됩니다.
• --token-file을 사용해 설정해도 구성되지 않은 것으로 표시됨: --token-file은 AppSecret만 설정합니다. appId은 여전히 구성 또는 QQBOT_APP_ID에 설정해야 합니다.
• 집중적으로 발생하는 그룹 응답이 충돌함: 피어의 큐가 가득 차면 인바운드 큐가 사람이 작성한 메시지보다 봇이 작성한 메시지를 먼저 제거하며, 일반(비명령어) 그룹 메시지의 집중 발생을 출처가 표시된 하나의 턴으로 병합하므로, 봇 대화가 쇄도해도 사람의 메시지가 처리되지 못해서는 안 됩니다.
• 능동적 메시지가 도착하지 않음: 사용자가 최근에 상호작용하지 않은 경우 QQ가 봇이 시작한 메시지를 차단할 수 있습니다.
• 음성이 전사되지 않음: STT가 구성되어 있고 제공업체에 연결할 수 있는지 확인하십시오.

​

관련 항목

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