Integración de plugins OpenClaw + QQ y revisión retrospectiva de depuración ultralarga (proceso completo)

AIDO debug
, ,
1

Integración del plugin OpenClaw + QQ y retrospectiva de depuración ultra larga (proceso completo)

Nota: Esta retrospectiva está organizada según los pasos que se ejecutaron; se centra en registrar todo el flujo desde la integración, la depuración conjunta hasta la localización del problema central, así como cada conclusión clave.

I. Contexto y objetivos

El objetivo esta vez fue integrar OpenClaw en el canal de QQ (basado en NapCat + el plugin openclaw_qq) y lograr:

  • Envío/recepción normal en chats privados y de grupo de QQ
  • Enrutamiento de sesiones y registros visibles en la WebUI
  • Estrategias controlables de administrador/lista negra (para evitar el abuso/robo de Token)
  • La configuración puede guardarse de forma estable en la Control UI

II. Entorno y línea temporal (aproximada)

Según las marcas de tiempo de los logs del gateway, esta investigación cubrió varias fases, con una depuración continua de alta intensidad de varias horas (aprox. 4+ horas).

III. Flujo de trabajo principal (por fases)

1) Integración del canal QQ y depuración básica conjunta

Primero completé el despliegue básico del plugin QQ y NapCat:

  • Instalar y habilitar el plugin openclaw_qq
  • Desplegar NapCat con Docker
  • Corregir el modo de conexión de NapCat a Forward WS Server (OpenClaw se conecta como cliente)
  • Tras alinear el Token de OneBot y la cuenta, el estado del canal QQ volvió a OK

2) Corrección de problemas de sesión y enrutamiento

Durante la depuración conjunta apareció el fenómeno de “la sesión de QQ se mezcla con la sesión principal/la de TG”; realicé una corrección del enrutamiento:

  • Corregir el parseo de rutas de QQ group/direct
  • Evitar que las escrituras de QQ sobrescriban los metadatos de la sesión principal
  • Garantizar que las sesiones de QQ y TG puedan separarse y rastrearse

Resultado: la visibilidad de las sesiones de QQ en la WebUI mejoró significativamente.

3) Ajuste de la estrategia de contexto y mensajes duplicados

Para el problema de “QQ trae un historial muy largo cada vez y genera ruido”:

  • Cambiar el valor por defecto de historyLimit a 0
  • Documentar claramente: por defecto se depende del sistema de sesiones de OpenClaw, no se fuerza el pegado del texto original del grupo
  • Solo habilitar el pegado de historial cuando el usuario lo necesite explícitamente

Al mismo tiempo se corrigió la lógica relacionada con disparos duplicados y avisos repetidos:

  • Ajustar el orden de comprobación de restricciones de administrador a: primero condiciones de disparo (@/palabra clave) y luego autorización
  • Añadir enfriamiento/antirrebote a los avisos a no administradores (por defecto 10 segundos)
  • Corregir el posible bucle de avisos en el escenario reply-to-bot

4) Mejora de capacidades de administrador/lista negra

Para evitar el abuso, añadí y reforcé capacidades:

  • adminOnlyChat
  • notifyNonAdminBlocked
  • nonAdminBlockedMessage
  • blockedNotifyCooldownMs

La lógica de lista negra finalmente se confirmó como:

  • Los mensajes de usuarios que coinciden con blockedUsers se ignoran directamente (sin respuesta, sin aviso)

5) Control UI y problema de guardado de configuración (clave)

El problema más costoso y crítico fue:

  • En la página /config, con solo cambiar la lista blanca/negra de QQ, aún aparecía invalid config
  • El error sin embargo apuntaba a models.providers.*.models[0].maxTokens

Conclusión final tras localizar el origen:

  1. /config guarda el paquete completo, no solo envía channels.qq
  2. Durante la validación del paquete completo, si cualquier campo es anómalo, falla todo el guardado
  3. maxTokens se procesa erróneamente en ciertas rutas (se convierte a string / es afectado por la “línea roja”), causando que falle la validación del paquete completo
  4. Por eso parece “cambiar el QQ provoca un error del modelo”, pero en esencia es “la validación del paquete completo arrastra a todos”

IV. Por qué parece que “cambiar el QQ arrastra a maxTokens”

En una frase: no es una relación de negocio, es una relación del mecanismo de guardado.

  • Lo que se cambia es un campo de QQ
  • Se dispara la escritura de toda la configuración
  • En toda la configuración, el tipo del campo del modelo deriva (por ejemplo maxTokens pasa a string / inválido)
  • La validación falla y el error burbujea al frontend

V. Acciones de sincronización del repositorio y local

Hice correcciones continuas en el repositorio del plugin y las envié varias veces, incluyendo:

  • Corrección de la estrategia de administrador
  • Corrección del enrutamiento de sesiones
  • Ajuste del valor por defecto de la inyección de historial
  • Mejora de compatibilidad del schema del frontend
  • Refuerzo de la documentación (ejemplos en chino)
  • Complemento de archivos de despliegue Docker de NapCat
  • Ignorar directorios en tiempo de ejecución para evitar contaminar el repositorio

Al mismo tiempo, el .openclaw/extensions/qq local se mantuvo sincronizado con la rama principal remota.

VI. Sobre “¿modificando solo el plugin QQ se puede resolver por completo?”

Conclusión:

  • Se puede resolver el comportamiento interno del plugin QQ y la mayoría de los problemas de usabilidad
  • Pero no se puede corregir desde la capa del plugin el problema del enlace central de guardado del paquete completo en OpenClaw
  • Porque la validación de models.* pertenece al OpenClaw Core y no está dentro del alcance del plugin QQ

VII. Recomendaciones ejecutables (final)

Disponible a corto plazo (sin tocar el Core)

  • Usar CLI para modificar la lista blanca/negra de QQ, evitando la ruta de guardado del paquete completo de /config:
openclaw config set channels.qq.admins '\"1838552185\"' --json
openclaw config set channels.qq.blockedUsers '\"342571216\"' --json
openclaw gateway restart

Recomendación a medio plazo (solución de raíz)

  • Esperar/seguir el arreglo oficial de OpenClaw para este tipo de issue (maxTokens + redaction + config save)
  • O enviar a los oficiales una reproducción mínima y un PR con parche

VIII. Lecciones

  1. Al depurar la página /config, hay que pensar siempre en “validación del paquete completo”, no solo en el ítem modificado
  2. Si la redacción (redaction) usa emparejamiento amplio (como /token/i), puede dañar por error maxTokens
  3. En plugins de chat, el orden de autorización (primero disparo y luego autorización) es crucial; si no, genera ruido en el grupo
  4. El antirrebote y la deduplicación deben estar habilitados por defecto; de lo contrario, los problemas se amplifican rápidamente en chats grupales