Visión general del proyecto OpenClaw QQ

Documentación OpenClaw QQ
1

Fuente: repositorio constansino/openclaw_qq en README.md
Original: openclaw_qq/README.md at main · constansino/openclaw_qq · GitHub
Esta versión ya se ha sincronizado en el foro para facilitar la búsqueda, la discusión y el mantenimiento continuo.

OpenClaw QQ

Plugin OpenClaw QQ (OneBot v11)

Proporciona a OpenClaw una integración de canal QQ apta para producción: primero haz que funcione rápido, y luego habilita capacidades avanzadas según necesidad.

[Documentación en línea] [Inicio rápido en 3 minutos] [Referencia de configuración] [Despliegue de NapCat] [Capacidades avanzadas]

[!IMPORTANT]
Foro oficial de intercambio (único): https://aiya.de5.net/c/openclaw-qq/25
Los reportes de problemas, experiencias de configuración y anuncios de actualización se consolidan en el foro para facilitar la búsqueda y el seguimiento.

Actualizaciones recientes (2026-03)

  • La documentación del repositorio ahora se mantiene unificada en versión china; se han limpiado los Markdown en inglés del repositorio.
  • Se añadió documentación del modo OneBot HTTP, compatible con acceso mediante HTTP API + webhook; ver docs/http-transport.md.
  • La session key de chat privado de QQ volvió al estilo oficial de nombres: el peer id usa solo el número de QQ, ya no se escribe como qq:user:<id>; las sesiones locales antiguas se normalizarán automáticamente al iniciar.
  • Se añadió keywordOnlyTrigger: en chats grupales puede cambiarse a “solo disparo por palabra clave”, ignorando disparo por @ / respuesta, adecuado para compartir la misma cuenta de QQ con otros bots.
  • Se añadió showReplySessionSource: antes de responder se puede marcar la sesión de origen, para distinguir la sesión principal y la sesión /temporal.
  • Reintentos automáticos / Fast Fail / fusión de concurrencia / interrupción por nuevo mensaje / ocultar metadatos del gateway y otros controles avanzados ahora están desactivados por defecto; actívalos según necesidad.
  • Se reforzó la explicación de parámetros en WebUI; las explicaciones de configuración compleja se han unificado y trasladado a docs/advanced.md y docs/config-reference.md.

Actualizaciones recientes (2026-02)

  • Se corrigió el bucle de reinicio de channel restart / health-monitor, evitando que el canal se levante repetidamente tras juzgarse erróneamente como salido.
  • Se mejoró la detección del estado de conexión de OneBot: se añadió isConnected() para evitar arranques duplicados con la misma cuenta.
  • Si falla el envío, vuelve automáticamente a la cola y dispara la reconexión, reduciendo el caso de “en el log aparece respondido pero no se entregó en QQ”.
  • Se añadió reintento automático + Fast Fail + Active Model Failover (conexión a fallbacks de openclaw.json).
  • Se añadió una cola anti-pérdida por concurrencia y “nuevo mensaje interrumpe la respuesta anterior” en la misma sesión.
  • Se añadió análisis de contexto multinivel para reply/forward y fusión + reenvío automático de respuestas largas.

Posicionamiento de este proyecto

Muchos plugins de QQ solo hacen la “capa básica de canal”; el objetivo de openclaw_qq es:

  • Con la configuración por defecto se puede poner en marcha rápidamente.
  • Para chats grupales en producción, se pueden habilitar gradualmente capacidades de estabilidad y control de riesgos.
  • Convertir capacidades complejas en “habilitar bajo demanda”, en lugar de forzar a que todos las usen.

Si solo necesitas capacidades mínimas, usa directamente la configuración mínima; si necesitas alta concurrencia y baja tasa de respuestas perdidas, habilita luego las opciones avanzadas.

Resumen de funciones

Capacidades básicas de canal

  • Acceso OneBot v11 WebSocket (NapCat / Lagrange, etc.)
  • Envío/recepción de mensajes en chat privado y grupal
  • Soporte de QQ Channel (Guild)
  • Disparo por @, disparo por palabra clave, control de lista blanca/lista negra

Estabilidad y tolerancia a fallos

  • Autorreparación de conexión y reconexión con backoff exponencial
  • Reencolar al fallar el envío
  • Reintento automático del modelo (maxRetries / retryDelayMs)
  • Fast Fail: omitir rápidamente errores (fastFailErrors)
  • Active Model Failover (si falla el modelo principal, cambia a uno de respaldo)

Mejora de contexto e interacción

  • Análisis recursivo de reply/forward e inyección de contexto por capas
  • Inyección oculta de metadatos del gateway de QQ (injectGatewayMeta)
  • Marcado opcional de la sesión de origen de la respuesta (showReplySessionSource)
  • Cola anti-pérdida por concurrencia en la misma sesión (queueDebounceMs)
  • Nuevo mensaje interrumpe respuesta anterior (interruptOnNewMessage)
  • Respuestas largas: fusión y reenvío automático (forwardLongReplyThreshold)

Gestión y seguridad

  • Modelo de permisos de administrador (admins / adminOnlyChat)
  • Aprobación automática de solicitudes de amistad/invitaciones a grupo (opcional)
  • Asistencia básica de control de riesgos (limitación de velocidad, evasión de URL, fallback para respuestas vacías)

Progreso actual (ruta de lectura recomendada)

  1. Ya puede usarse de forma estable para la integración diaria de bots de QQ y operación de chats grupales.
  2. La documentación se ha dividido en una estructura de tres niveles: “inicio rápido / referencia de configuración / capacidades avanzadas”.
  3. Se sigue optimizando para multi-cuenta, contextos complejos y observabilidad de operaciones y mantenimiento.

Se recomienda leer en el siguiente orden:

  1. Inicio rápido en 3 minutos
  2. Referencia de configuración (versión agrupada)
  3. Capacidades avanzadas y parámetros completos
  4. Instrucciones de despliegue de NapCat (GitHub)

Inicio rápido en 3 minutos

1. Requisitos previos

  • OpenClaw ya instalado y en ejecución
  • Servidor OneBot v11 en ejecución (recomendado: NapCat / Lagrange)
  • En la configuración de OneBot: message_post_format = array

2. Instalación

cd openclaw/extensions
git clone https://github.com/constansino/openclaw_qq.git qq
cd ../..
pnpm install && pnpm build

3. Prioriza la configuración en WebUI (recomendado)

Configura directamente channels.qq en el OpenClaw WebUI: es más intuitivo que escribir JSON a mano y es menos probable que haya errores de formato.

Ejemplo de configuración en OpenClaw WebUI

Se recomienda completar primero estos elementos clave:

  • wsUrl
  • accessToken
  • requireMention
  • admins (opcional)
  • allowedGroups (opcional)

4. Configuración manual en JSON (opcional)

Edita ~/.openclaw/openclaw.json:

{
  "channels": {
    "qq": {
      "wsUrl": "ws://127.0.0.1:3001",
      "accessToken": "your_token",
      "requireMention": true
    }
  },
  "plugins": {
    "entries": {
      "qq": { "enabled": true }
    }
  }
}

5. Inicio y verificación

openclaw gateway restart

Verificación:

  • El bot puede responder en chat privado
  • En chat grupal, al @ al bot puede responder
  • En los logs no hay fallos de autenticación continuos/tormenta de reconexiones

Documentación

  • Centro de documentación: docs/index.md
  • Documento principal en chino: este /t/topic/124

Feedback y contribución

  • Reporte de problemas / experiencias de uso / sugerencias de requisitos:
  • Para problemas de código, puedes abrir directamente un GitHub Issue / PR.

License

MIT

OpenClaw QQ 文档中心