Conecta OpenClaw a QQ Bot: Configuración rápida en 5 minutos

¿Alguna vez has sentido que configurar un bot es más difícil que programar sus funciones? Lidiar con APIs complejas y configuraciones de red puede ser frustrante cuando solo quieres que tu bot responda mensajes.

Si buscas una forma directa de conectar tus servicios con QQ, OpenClaw es la mejor opción. Olvídate de configuraciones manuales tediosas; aquí te explico cómo ponerlo en marcha rápidamente para que tú y tu comunidad puedan interactuar sin fricciones.

QQ Bot

QQ Bot se conecta a OpenClaw mediante la API oficial de QQ Bot (WebSocket Gateway). El plugin soporta chats privados C2C, mensajes en grupos, mensajes en canales de guild y contenido multimedia como imágenes, voz, vídeo o archivos.

Estado: plugin de canal incluido. Soporta mensajes directos, chats grupales, canales de guild y multimedia. No soporta reacciones ni hilos.

Incluido con OpenClaw

Las instalaciones actuales de OpenClaw ya incluyen QQ Bot. No necesitas ejecutar un paso por separado de openclaw plugins install para una configuración normal.

Configuración inicial

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

El AppSecret no se guarda en texto plano; si sales de la página sin guardarlo, tendrás que generar 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 add
openclaw configure --section channels

Configuración

Configuración mínima:

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

Variables de entorno para la cuenta por defecto:

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret basado en archivo:

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

Notas:

• El respaldo (fallback) de variables de entorno solo se aplica a la cuenta de QQ Bot por defecto.
• openclaw channels add --channel qqbot --token-file ... solo proporciona el AppSecret; el AppID ya debe estar definido en la configuración o en QQBOT_APP_ID.
• clientSecret también acepta entradas de SecretRef, no solo strings en texto plano.

Configuración de múltiples cuentas

Puedes ejecutar 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 lanza su propia conexión WebSocket y mantiene un caché de tokens independiente (aislado por appId).

Añade un segundo bot mediante la CLI:

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

Voz (STT / TTS)

El soporte para STT y TTS utiliza una configuración de dos niveles con respaldo de prioridad:

Ajuste	Específico del plugin	Respaldo del framework
STT	channels.qqbot.stt	tools.media.audio.models[0]
TTS	channels.qqbot.tts	messages.tts

{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
    },
  },
}

Establece enabled: false en cualquiera de ellos para desactivarlo.

El comportamiento de subida y transcodificación de audio saliente también se puede ajustar con channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

Formatos de destino

Formato	Descripción
qqbot:c2c:OPENID	Chat privado (C2C)
qqbot:group:GROUP_OPENID	Chat de grupo
qqbot:channel:CHANNEL_ID	Canal de guild

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

Comandos de barra diagonal (Slash commands)

Comandos integrados que se interceptan antes de la cola de la AI:

Comando	Descripción
/bot-ping	Prueba de latencia
/bot-version	Muestra la versión del framework OpenClaw
/bot-help	Lista todos los comandos
/bot-upgrade	Muestra el enlace a la guía de actualización de QQBot
/bot-logs	Exporta los logs recientes del Gateway como un archivo

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

Resolución de problemas

• El bot responde “gone to Mars”: las credenciales no están configuradas o el Gateway no se ha iniciado.
• No llegan mensajes entrantes: verifica que el appId y el clientSecret sean correctos, y que el bot esté activado en la QQ Open Platform.
• La configuración con --token-file sigue apareciendo como no configurada: --token-file solo establece el AppSecret. Todavía necesitas el appId en la configuración o en 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 el STT esté configurado y que el proveedor sea accesible.

AI Setup Assistant

Siguientes pasos

• Configuración de canales
• Gestión de Gateway