Bot de QQ

QQ Bot conecta QQ con OpenClaw mediante la API oficial de QQ Bot (Gateway WebSocket). El Plugin admite chat privado C2C, @mensajes de grupo y mensajes de canales de guild con medios enriquecidos (imágenes, voz, video, archivos).

Estado: Plugin descargable. Se admiten mensajes directos, chats de grupo, canales de guild y medios. No se admiten reacciones ni hilos.

Instalar

Instala QQ Bot antes de la configuración:

openclaw plugins install @openclaw/qqbot

Configuración

1. Ve a la 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.

AppSecret no se almacena en texto sin formato; si sales de la página sin guardarlo, tendrás que regenerar uno nuevo.

4. Añade el canal:

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

5. Reinicia el Gateway.

Rutas de configuración interactiva:

openclaw channels addopenclaw configure --section channels

Configurar

Configuración mínima:

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

Variables de entorno de cuenta predeterminada:

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret respaldado por archivo:

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

AppSecret SecretRef de entorno:

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

Notas:

• La reserva de entorno se aplica solo a la cuenta predeterminada de QQ Bot.
• openclaw channels add --channel qqbot --token-file ... proporciona solo el AppSecret; el AppID ya debe estar definido en la configuración o en QQBOT_APP_ID.
• clientSecret también acepta entrada SecretRef, no solo una cadena de texto sin formato.
• Las cadenas de marcador heredadas secretref:/... no son valores válidos de clientSecret; usa objetos SecretRef estructurados como en el ejemplo anterior.

Configuración de varias cuentas

Ejecuta varios bots de QQ bajo una sola instancia de OpenClaw:

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

Cada cuenta inicia su propia conexión WebSocket y mantiene una caché de token independiente (aislada por appId).

Añade un segundo bot mediante la CLI:

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

Chats de grupo

El soporte de chat de grupo de QQ Bot usa OpenIDs de grupos QQ, no nombres visibles. Añade el bot a un grupo y luego menciónalo o configura el grupo para ejecutarse sin mención.

{  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["*"] establece valores predeterminados para cada grupo, y una entrada concreta groups.GROUP_OPENID anula esos valores predeterminados para un grupo. La configuración de grupo incluye:

• requireMention: requiere una @mención antes de que el bot responda. Predeterminado: true.
• commandLevel: controla qué comandos slash integrados pueden ejecutarse en grupos. Predeterminado: all, que conserva el comportamiento de grupo preexistente de QQBot cuando se omite el ajuste.
• ignoreOtherMentions: descarta mensajes que mencionan a otra persona pero no al bot.
• historyLimit: conserva los mensajes recientes de grupo sin mención como contexto para el siguiente turno mencionado. Usa 0 para deshabilitarlo.
• tools: permite/deniega herramientas para todo el grupo.
• toolsBySender: anulaciones de herramientas de grupo por remitente; consulta Grupos.
• name: etiqueta descriptiva usada en los registros y en el contexto de grupo.
• prompt: prompt de comportamiento por grupo añadido al contexto del agente.

commandLevel acepta:

• all: mantiene disponibles los comandos integrados reconocidos como antes. Algunos comandos pueden permanecer ocultos en los menús, pero los usuarios autorizados aún pueden ejecutarlos en el grupo.
• safety: permite comandos comunes de colaboración como /help, /btw y /stop; pide a los usuarios que ejecuten comandos sensibles como /config, /tools y /bash en chat privado.
• strict: solo permite los controles de sesión de grupo necesarios para una operación estricta de grupo. /stop sigue siendo urgente para que un remitente autorizado pueda interrumpir una ejecución activa.

Las entradas antiguas toolPolicy de QQBot están retiradas. Ejecuta openclaw doctor --fix para migrarlas a tools.

Los modos de activación son mention y always. requireMention: true se asigna a mention; requireMention: false se asigna a always. Una anulación de activación a nivel de sesión, cuando existe, prevalece sobre la configuración.

La cola entrante es por par. Los pares de grupo reciben un límite de cola mayor, mantienen los mensajes humanos por delante de la conversación generada por bots cuando se llena, y fusionan ráfagas de mensajes normales de grupo en un solo turno atribuido. Los comandos slash siguen ejecutándose uno por uno.

Voz (STT / TTS)

El soporte de STT y TTS usa configuración de dos niveles con reserva por prioridad:

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

Establece enabled: false en cualquiera de los dos para deshabilitarlo. Las anulaciones de TTS a nivel de cuenta usan la misma forma que messages.tts y se fusionan en profundidad sobre la configuración TTS del canal/global.

Los adjuntos de voz entrantes de QQ se exponen a los agentes como metadatos de medios de audio mientras se mantienen los archivos de voz sin procesar fuera de los MediaPaths genéricos. Las respuestas de texto sin formato [[audio_as_voice]] sintetizan TTS y envían un mensaje de voz nativo de QQ cuando TTS está configurado.

El comportamiento de carga/transcodificación de audio saliente también puede ajustarse con channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Formatos de destino

Cada bot tiene su propio conjunto de OpenIDs de usuario. Un OpenID recibido por el Bot A no puede usarse para enviar mensajes mediante el Bot B.

Comandos slash

Comandos integrados interceptados antes de la cola de IA:

Añade ? a cualquier comando para obtener ayuda de uso (por ejemplo /bot-upgrade ?).

Los comandos de administrador (/bot-me, /bot-upgrade, /bot-logs, /bot-clear-storage, /bot-streaming, /bot-approve) son solo para mensajes directos y requieren el openid del remitente en una lista explícita allowFrom sin comodines. Un comodín allowFrom: ["*"] permite el chat pero no concede acceso a comandos de administrador. Los mensajes de grupo se comparan primero con groupAllowFrom y recurren a allowFrom. Ejecutar un comando de administrador en un grupo devuelve una sugerencia en lugar de descartarlo silenciosamente.

Cuando las aprobaciones de ejecución de QQ Bot usan la reserva predeterminada del mismo chat, los clics en botones de aprobación nativos siguen la misma lista explícita de comandos permitidos sin comodines. Para conceder acceso solo a aprobaciones sin acceso más amplio a comandos, configura channels.qqbot.execApprovals.approvers.

Arquitectura del motor

QQ Bot se entrega como un motor autónomo dentro del Plugin:

• Cada cuenta posee una pila de recursos aislada (conexión WebSocket, cliente de API, caché de token, raíz de almacenamiento de medios) indexada por appId. Las cuentas nunca comparten estado entrante/saliente.
• El registrador de varias cuentas etiqueta las líneas de registro con la cuenta propietaria para que los diagnósticos sigan siendo separables cuando ejecutas varios bots bajo un Gateway.
• Las rutas entrantes, salientes y de puente del Gateway comparten una sola raíz de carga útil de medios bajo ~/.openclaw/media, por lo que las cargas, descargas y cachés de transcodificación se ubican bajo un único directorio protegido en lugar de un árbol por subsistema.
• La entrega de medios enriquecidos pasa por una sola ruta sendMedia para destinos C2C y de grupo. Los archivos locales y búferes por encima del umbral de archivo grande usan los endpoints de carga fragmentada de QQ, mientras que las cargas útiles más pequeñas usan la API de medios de una sola operación.
• Las credenciales pueden respaldarse y restaurarse como parte de las instantáneas de credenciales estándar de OpenClaw; el motor vuelve a adjuntar la pila de recursos de cada cuenta al restaurar sin requerir un nuevo par de código QR.

Incorporación con código QR

Como alternativa a pegar AppID:AppSecret manualmente, el motor admite un flujo de incorporación con código QR para vincular un QQ Bot con OpenClaw:

1. Ejecuta la ruta de configuración de QQ Bot (por ejemplo openclaw channels add --channel qqbot) y elige el flujo de código QR cuando se te solicite.
2. Escanea el código QR generado con la aplicación del teléfono asociada al QQ Bot de destino.
3. Aprueba el emparejamiento en el teléfono. OpenClaw conserva las credenciales devueltas en credentials/ bajo el ámbito de cuenta correcto.

Los prompts de aprobación generados por el propio bot (por ejemplo, flujos de "¿permitir esta acción?" expuestos por la API de QQ Bot) aparecen como prompts nativos de OpenClaw que puedes aceptar con /bot-approve en lugar de responder mediante el cliente QQ sin procesar.

Solución de problemas

• El bot responde "gone to Mars": las credenciales no están configuradas o el Gateway no se ha iniciado.
• No hay mensajes entrantes: verifica que appId y clientSecret sean correctos, y que el bot esté habilitado en QQ Open Platform.
• Respuestas repetidas a sí mismo: OpenClaw registra los índices de referencia salientes de QQ como creados por el bot e ignora los eventos entrantes cuyo msgIdx actual coincide con esa misma cuenta del bot. Esto evita bucles de eco de la plataforma y, al mismo tiempo, permite que los usuarios citen o respondan a mensajes anteriores del bot.
• La configuración con --token-file aún aparece como no configurada: --token-file solo establece el AppSecret. Todavía necesitas appId en la configuración o QQBOT_APP_ID.
• Los mensajes proactivos no llegan: QQ puede interceptar 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 se pueda acceder al proveedor.

Relacionado

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