Despliegue e integración de GenericAgent: robots en toda la plataforma WeChat/QQ/Feishu

Introducción del proyecto

GenericAgent es un framework de agentes autónomos minimalista y capaz de evolucionar por sí mismo. Su núcleo es solo ~3K líneas de código: mediante 9 herramientas atómicas + un Agent Loop de ~100 líneas, otorga a cualquier LLM la capacidad de control a nivel de sistema del ordenador local.

Su filosofía de diseño es muy interesante: no predefine habilidades; las obtiene mediante la evolución. Cada vez que resuelve una tarea nueva, GenericAgent fija automáticamente el camino de ejecución como una Skill. Cuanto más tiempo lo uses, más habilidades se van acumulando, hasta formar un árbol de habilidades totalmente tuyo, que crece desde un “seed” de 3K líneas de código.

En comparación con OpenClaw（~530K líneas de código）, GenericAgent sigue una ruta extremadamente minimalista: despliegue sencillo（pip install + API Key）, sin necesidad de orquestar muchos servicios, pero aun así conserva capacidades esenciales como el control completo del navegador, la manipulación de teclado y ratón y el control de dispositivos móviles mediante ADB.

---

Dificultad / Duración / Beneficios

• Dificultad: Nivel inicial, no requiere experiencia profunda en programación
• Duración: Aproximadamente 30 minutos
• Beneficios: Dominar la configuración de despliegue de GenericAgent + integración en las tres principales plataformas IM (WeChat/QQ/Feishu), para controlar la IA del ordenador con el móvil en cualquier momento y en cualquier lugar

---

Perfil de lectores objetivo

• Desarrolladores backend o full-stack con 1 a 5 años de experiencia
• Usuarios que quieren montar un asistente de IA personal y flujos de trabajo de automatización
• Desarrolladores interesados en la tecnología de agentes, que quieran probar rápido la experiencia de “que la IA realmente haga cosas por ti”
• Requisitos de integración IM en múltiples plataformas (por ejemplo, controlar el ordenador de forma remota por WeChat/QQ)

---

Dependencias principales y entorno

---

Estructura completa del proyecto

GenericAgent/
├── agentmain.py              # Punto de entrada principal, admite modo de línea de comandos
├── launch.pyw                # Script de arranque para GUI de escritorio
├── agent_loop.py             # Agent Loop central（~100 líneas）
├── llmcore.py                # Gestión de la sesión LLM
├── ga.py                     # GenericAgentHandler: memoria y programación de herramientas
├── frontends/                # Adaptadores para plataformas IM
│   ├── wechatapp.py         # Bot de WeChat
│   ├── qqapp.py             # Bot de QQ
│   ├── fsapp.py             # Bot de Feishu
│   ├── tgapp.py             # Bot de Telegram
│   ├── wecomapp.py          # Bot de WeChat Enterprise
│   ├── dingtalkapp.py       # Bot de DingTalk
│   ├── tuiapp.py            # UI de terminal
│   └── ...
├── assets/
│   ├── mykey_template.py    # Plantilla de configuración de API Key
│   ├── tools_schema.json    # Definición de 9 herramientas atómicas
│   ├── sys_prompt*.txt      # Prompts del sistema
│   └── tmwd_cdp_bridge/    # Plugin de inyección del navegador
├── memory/                   # Directorio de almacenamiento de memoria
└── temp/                     # Archivos temporales y logs

---

Pasos paso a paso

Step 1: Instalar el proyecto y dependencias

Primero clona el repositorio e instala las dependencias base:

# Clonar el repositorio
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# Instalar dependencias base
pip install requests

# Instalar dependencias para la GUI（modo de escritorio）
pip install streamlit pywebview

# O instalar dependencias para la UI de terminal
pip install requests textual

Step 2: Configurar la API Key

Copia la plantilla de configuración:

cp assets/mykey_template.py mykey.py

Edita mykey.py e introduce tu configuración de LLM. Aquí tienes un ejemplo usando Defapi（por ejemplo con Claude）:

# Usar Defapi para intermediación de Claude（mitad de precio oficial）
native_claude_config = {
    'name': 'claude-defapi',                    # Nombre visible
    'apikey': 'sk-ant-your-defapi-key',         # Key proporcionada por Defapi
    'apibase': 'https://api.defapi.org',        # Endpoint de Defapi
    'model': 'claude-sonnet-4-6',               # o claude-opus-4-7
    'fake_cc_system_prompt': True,              # Requiere activarlo para el servicio intermediado
    'thinking_type': 'adaptive',
    'max_tokens': 16384,
}

GenericAgent determina automáticamente el formato del protocolo según el nombre de las variables:

• Incluye native + claude → NativeClaudeSession（campo tool nativo）
• Incluye native + oai → NativeOAISession（campo tool nativo de OpenAI）
• Incluye claude（sin native）→ ClaudeSession（herramientas con protocolo de texto）

Step 3: Iniciar GenericAgent

Primero prueba que el modo de línea de comandos funciona bien:

python agentmain.py

Deberías ver el prompt de interacción >; escribe una frase para probar:

> En el escritorio crea un hello.txt, y el contenido es Hello World

Si todo está correcto, el Agent ejecutará la tarea y te devolverá el resultado.

Cambia al modo GUI de escritorio:

python launch.pyw

---

Step 4: Integrar Bot de WeChat

El Bot de WeChat admite inicio de sesión con escaneo de código QR para usuarios personales; la integración es la más sencilla.

Instala dependencias adicionales:

pip install pycryptodome qrcode requests

Configuración（opcional; aunque no la configures también funciona, se recomienda configurar una lista blanca）：

En mykey.py, añade:

# Lista blanca de WeChat; introduce el ID de WeChat; si no se rellena, se permiten todos los usuarios
wechat_allowed_users = []

Iniciar el Bot de WeChat:

python frontends/wechatapp.py

En el primer arranque aparecerá una ventana con un código QR; confirma con el escaneo desde WeChat. Tras iniciar sesión con éxito, tu WeChat se convertirá en la interfaz de conversación con GenericAgent.

Step 5: Integrar Bot de QQ

El Bot de QQ usa la API oficial de robots de QQ: no necesita webhook público, y recibe mensajes mediante una conexión persistente de WebSocket.

Instalar dependencias:

pip install qq-botpy

Configuración:

1. Ve a QQ Open Platform para crear un robot y obtener AppID y AppSecret
2. Añade en mykey.py:

qq_app_id = "TU_APP_ID"
qq_app_secret = "TU_APP_SECRET"
qq_allowed_users = ["openid_del_usuario"]  # o ['*'] para permitir a todos

Iniciar el Bot de QQ:

python frontends/qqapp.py

Después del primer mensaje al robot, el openid del usuario se registrará en temp/qqapp.log.

Step 6: Integrar Bot de Feishu

El Bot de Feishu admite múltiples formatos de mensaje, como texto, rich text, imágenes, archivos, audio y tarjetas de interacción.

Instalar dependencias:

pip install lark-oapi

Configuración:

1. Crea una aplicación empresarial autoconstruida en la plataforma abierta de Feishu y obtén AppID y AppSecret
2. Añade en mykey.py:

fs_app_id = "cli_xxxxxxxxxxxxxxxx"
fs_app_secret = "xxxxxxxxxxxxxxxx"
fs_allowed_users = ["ou_xxxxxxxxxxxxxxxx"]  # o ['*'] para permitir a todos

Iniciar el Bot de Feishu:

python frontends/fsapp.py

Step 7: Verificar y ajustar

Todos los Bots admiten estos comandos universales:

• /new - iniciar una conversación nueva, borrando el contexto actual
• /continue - listar instantáneas de sesiones que se pueden restaurar
• /continue N - restaurar la sesión histórica número N

Verificar integración simultánea en múltiples plataformas:

Si quieres ejecutar varios Bots al mismo tiempo, abre varias ventanas de terminal:

# Terminal 1：WeChat
python frontends/wechatapp.py

# Terminal 2：QQ
python frontends/qqapp.py

# Terminal 3：Feishu
python frontends/fsapp.py

---

Solución de problemas frecuentes

1. Tras configurar la API Key, aparece un error de autenticación

Causa: nombre de variable escrito incorrectamente o configuración incorrecta de fake_cc_system_prompt

Solución:

• Verifica que el nombre de la variable contenga las palabras clave correctas（native_claude, oai_config, etc.）
• El servicio intermediado debe ser fake_cc_system_prompt: True
• Comprueba que apibase sea correcto（por ejemplo, Defapi usa https://api.defapi.org）

2. Tras escanear con WeChat, indica que el inicio de sesión falla

Causa: restricciones de riesgo de WeChat para inicios de sesión desde dispositivos nuevos

Solución:

• Intenta confirmar el inicio de sesión desde el móvil（a veces requiere verificación secundaria en el teléfono）
• Asegúrate de que la cuenta de WeChat no tenga comportamientos anómalos
• Reduce la frecuencia de uso del Bot para evitar activar el control de riesgo

3. El Bot de QQ no recibe mensajes

Causa: el robot no está habilitado o la configuración de permisos es incorrecta

Solución:

• En la plataforma abierta de QQ, confirma que el robot esté habilitado
• Revisa si has añadido correctamente la suscripción a eventos（es necesario suscribirse al evento 私聊消息）
• Consulta temp/qqapp.log para confirmar que el openid del usuario se registró correctamente

4. El Bot de Feishu responde con mucha demora

Causa: la inferencia del LLM es en sí lenta o hay latencia de red

Solución:

• Usa un modelo más rápido（por ejemplo GPT-4o-mini, MiniMax-M2）
• Revisa la latencia de red hacia la API de LLM
• Ajusta adecuadamente max_tokens para acelerar la respuesta del primer token

5. El Bot no puede recordar el contexto de la conversación

Causa: ejecutaste el comando /new o la sesión expiró

Solución:

• Usa el comando /continue para restaurar sesiones históricas
• Confirma que tienes permisos de escritura en el directorio memory/
• Revisa si existe un registro de sesiones en el directorio temp/model_responses/

6. Aparece ModuleNotFoundError al ejecutar

Causa: falta el paquete de dependencias

Solución:

# Haz que el Agent instale todo
> Por favor, ayúdame a instalar todas las dependencias de Python necesarias

# O instala manualmente dependencias comunes
pip install requests pycryptodome qrcode streamlit pywebview

---

Lecturas ampliadas / Direcciones de mejora

Capacidades de automatización del navegador

Después de desbloquear la herramienta Web, GenericAgent puede operar dentro de un** navegador real con tu sesión de inicio iniciada**:

> Ejecuta web setup sop y desbloquea la herramienta web

Luego puedes usarlo así:

> Abre Taobao, busca iPhone 16 y ordena por precio
> Ve a Bilibili y consulta los videos que vi recientemente

Los plugins del navegador están en assets/tmwd_cdp_bridge/ y admiten navegadores principales como Chrome/Edge.

Explicación detallada del mecanismo de autoevolución

La diferencia central de GenericAgent es que** tras completar cada tarea, consolida automáticamente la ruta de ejecución como Skill**. La próxima vez que te enfrentes a una tarea similar, se llama directamente, sin necesidad de volver a explorar.

Esto significa que:

• Cuanto más lo uses, más entiende tu flujo de trabajo
• El árbol de habilidades es completamente tuyo y no se parece a las “skills predefinidas” de otras personas
• Con un seed de 3K líneas de código, puedes crecer hacia posibilidades infinitas

Ecosistema de la Skill Library

La comunidad ya ha acumulado una Skill Library con escala de millones（artículo de WeChat Official Account），y puedes:

• Pedir al Agent que busque: Encuentra una skill que sirva para hacer XXX
• Importar directamente: Accede a XXX y hazlo siguiendo esta skill

Modo avanzado

Todas las funciones avanzadas de GenericAgent son autodocumentadas: solo pregunta al Agent.

Comparación de capacidades de programación: Claude Code vs GenericAgent

Muchos desarrolladores se preguntan esto: ¿GenericAgent puede reemplazar a Claude Code o Codex?

La respuesta es: puede programar, pero no puede reemplazarlos completamente.

Capacidad de programación de GenericAgent

GenericAgent ejecuta código arbitrario mediante la herramienta code_run, y combinado con operaciones de archivos como file_read/file_write/file_patch, la capacidad de programación es completa. Mientras uses un modelo experto en programación（por ejemplo Claude o GPT-4o）, puede:

• Leer y escribir archivos
• Ejecutar comandos de línea
• Depurar código
• Explicar la lógica del código

# Configurar Claude como backend
native_claude_config = {
    'apikey': 'your-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,
}

Luego programa directamente con lenguaje natural:

> Escribe una función de quicksort rápida y luego ejecuta las pruebas
> Implementa un servidor HTTP con Python
> Explica cómo funciona este componente React

Diferencias con Claude Code / Codex

La diferencia clave es que: Claude Code funciona con sus propios protocolos y cadena de herramientas（similar a MCP）, y GenericAgent no puede llamarlos directamente. Pero hay formas indirectas:

Forma 1：Uso en paralelo con Codeg

Codeg puede iniciar simultáneamente GenericAgent + Claude Code + Codex, colaborando en una misma interfaz UI:

# Coloca GenericAgent y Codeg en el mismo nivel de directorio
/workspace/
  ├── GenericAgent/
  └── codeg/

# Codeg detectará automáticamente GenericAgent y se usará en paralelo

Forma 2：A través de intermediación por API

La NativeClaudeSession de GenericAgent sigue un protocolo compatible con Claude Code. Si el servicio intermediado（por ejemplo Defapi）soporta la transmisión transparente de Claude Code, entonces puedes usar GenericAgent para aprovechar la capacidad de programación de Claude:

# GenericAgent usa las capacidades de Claude para programar
native_claude_config = {
    'name': 'claude-defapi',
    'apikey': 'your-defapi-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,  # Transmisión transparente del protocolo de Claude Code
}

Conclusión

---

Referencia

• GitHub: lsdefine/GenericAgent
• Technical Report: arXiv:2604.17091
• Tutorial de inicio: Datawhale Hello GenericAgent
• Guía de configuración de Feishu: assets/SETUP_FEISHU.md