bot de QQ

​

Instalar

openclaw plugins install @openclaw/qqbot

​

Configuración

1. Ve a QQ Open Platform y escanea el código QR con tu QQ del teléfono para registrarte / iniciar sesión.
2. Haz clic en Create Bot para crear un nuevo bot de QQ.
3. Busca AppID y AppSecret en la página de configuración del bot y cópialos.

4. Agrega el canal:

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

5. Reinicia el Gateway.

openclaw channels add

​

Configurar

{
  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 ... establece solo el AppSecret; appId ya debe estar establecido en la configuración o en QQBOT_APP_ID.
• clientSecret acepta una cadena de texto plano, una ruta de archivo (clientSecretFile) o un objeto SecretRef estructurado.
• Las cadenas de marcador heredadas secretref:... / secretref-env:... se rechazan para clientSecret; usa en su lugar un objeto SecretRef estructurado.

​

Política de acceso

• allowFrom / groupAllowFrom controlan quién puede chatear con el bot en contextos C2C / de grupo. dmPolicy / groupPolicy (open | allowlist | disabled) controlan el modo de aplicación. dmPolicy toma como valor predeterminado allowlist cuando allowFrom tiene una entrada concreta (sin comodín); de lo contrario, open. groupPolicy toma como valor predeterminado allowlist cuando groupAllowFrom o allowFrom tiene una entrada concreta; de lo contrario, open.
• Los comandos slash “Auth: allowlist” requieren una entrada explícita sin comodín en allowFrom (o groupAllowFrom para invocaciones de grupo) independientemente de dmPolicy / groupPolicy; consulta Comandos slash.

​

Configuración de múltiples cuentas

{
  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"

​

Chats de grupo

{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["member_openid"],
      groups: {
        "*": {
          requireMention: true,
          commandLevel: "all",
          historyLimit: 50,
          tools: { deny: ["exec", "read", "write"] },
        },
        GROUP_OPENID: {
          name: "Sala de lanzamientos",
          requireMention: false,
          ignoreOtherMentions: true,
          commandLevel: "safety",
          historyLimit: 20,
          prompt: "Mantén las respuestas breves y operativas.",
        },
      },
    },
  },
}

​

Voz (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

​

Formatos de destino

​

Comandos de barra

​

Medios y almacenamiento

• Los medios entrantes, salientes y del puente de Gateway comparten una única raíz de carga útil en ~/.openclaw/media/qqbot (respetando OPENCLAW_HOME cuando está configurado), de modo que las cargas, descargas y cachés de transcodificación permanecen bajo un único directorio protegido.
• La entrega de medios enriquecidos para destinos C2C y de grupo pasa por una única ruta sendMedia. Los archivos locales y los búferes en memoria de 5 MiB o más usan los endpoints de carga fragmentada de QQ; las cargas útiles más pequeñas y las fuentes de URL remota/Base64 usan la API de carga de una sola vez.
• Si una actualización en caliente interrumpe el Gateway antes de que termine de escribir openclaw.json, el Plugin restaura el último appId / clientSecret conocido para esa cuenta desde una instantánea interna en el siguiente inicio (sin sobrescribir nunca un cambio intencional de configuración), por lo que no es necesario volver a escanear el código QR.

​

Solución de problemas

• El Gateway no inicia / no hay mensajes entrantes: verifica que appId y clientSecret sean correctos y que el bot esté habilitado en QQ Open Platform. Una credencial faltante aparece como “QQBot no configurado (falta appId o clientSecret)”.
• La configuración con --token-file sigue apareciendo como no configurada: --token-file solo establece AppSecret. appId aún debe estar configurado en la configuración o en QQBOT_APP_ID.
• Las respuestas de grupo en ráfaga colisionan: la cola entrante expulsa los mensajes escritos por el bot antes que los humanos cuando se llena la cola de un par, y fusiona ráfagas de mensajes de grupo normales (no comandos) en un único turno atribuido, por lo que una avalancha de charla del bot no debería privar de atención a los mensajes humanos.
• No llegan los mensajes proactivos: QQ puede bloquear los mensajes iniciados por el bot si el usuario no ha interactuado recientemente.
• La voz no se transcribe: asegúrate de que STT esté configurado y de que el proveedor sea accesible.

​

Relacionado

• Emparejamiento
• Grupos
• Solución de problemas de canales