Guía Práctica de Despliegue de AstrBot: Configuración de Bots para QQ, Telegram y Feishu

Construye en 30 minutos un chatbot de IA compatible con múltiples plataformas de mensajería, incluyendo Telegram, Feishu, QQ y otras aplicaciones líderes.

Audiencia objetivo: Desarrolladores backend con 1-3 años de experiencia que deseen implementar rápidamente su propio chatbot de IA.

Dependencias principales: Python 3.10+, gestor de paquetes uv, cuentas de desarrollador en plataformas de mensajería.

Aprendizaje: Dominar el proceso completo de despliegue de AstrBot y ser capaz de configurar asistentes de IA multiplataforma.

---

1. Introducción al proyecto y arquitectura

AstrBot es una plataforma de chatbot de Agentes de IA de código abierto desarrollada en Python, que permite la integración con diversos softwares de mensajería instantánea. Su filosofía de diseño es que «la compañía y la capacidad no deben ser opuestas»: debe tener tanto la capacidad de brindar acompañamiento emocional como de completar diversas tareas de manera confiable.

1.1 Plataformas de mensajería compatibles

1.2 Características principales

• Soporte multimodelo: OpenAI, Claude, Gemini, DeepSeek, etc.
• Capacidad de Agente: Soporte para el protocolo MCP, permitiendo llamadas a herramientas externas.
• Configuración de personalidad: Sistema de Persona integrado para personalizar el carácter de la IA.
• Base de conocimientos: Soporte para RAG, permitiendo importar documentos para dotar a la IA de conocimientos especializados.
• WebUI: Consola visual para una configuración más intuitiva.

---

2. Preparación del entorno

2.1 Instalar uv

AstrBot recomienda el uso de uv para la instalación, un gestor de paquetes de Python de nueva generación que es hasta 10 veces más rápido que pip.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Tras la instalación, verifique la versión:

uv --version
# Salida similar a: uv 0.5.0

2.2 Instalar AstrBot

Instalación completa con un solo comando:

uv tool install astrbot

2.3 Inicializar el proyecto

astrbot init

Este comando creará la estructura de directorios del proyecto:

.
├── data/              # Directorio de datos
│   ├── cmd_config.json  # Archivo de configuración principal
│   └── config/         # Directorio de múltiples configuraciones
├── logs/              # Directorio de registros
└── plugins/           # Directorio de complementos

Acceda al directorio del proyecto:

cd astrbot

---

3. Configuración de adaptadores de plataforma

AstrBot soporta múltiples plataformas. Aquí demostramos cómo configurar tres de las principales.

3.1 Configuración de bot de Telegram

Telegram es el método más sencillo, solo requiere un Bot Token.

3.1.1 Crear el Bot

1. Busque a @BotFather en Telegram.
2. Envíe /newbot para crear un nuevo robot.
3. Siga las instrucciones para configurar el nombre y el nombre de usuario.
4. Copie el Bot Token (ej. 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11).

3.1.2 Archivo de configuración

Abra data/cmd_config.json y añada lo siguiente en el array platform:

{
    "platform": [
        {
            "type": "telegram",
            "enable": true,
            "token": "TU_BOT_TOKEN"
        }
    ]
}

3.1.3 Obtener el Chat ID

Inicie el bot, envíele un mensaje y luego acceda a:

https://api.telegram.org/bot<TOKEN>/getUpdates

Busque "chat":{"id":123456789} en el JSON devuelto; ese será su Chat ID.

3.2 Configuración de bot de Feishu

Feishu es común en entornos corporativos; su configuración es algo más compleja.

3.2.1 Crear la aplicación

1. Acceda a Feishu Open Platform.
2. Cree una aplicación empresarial.
3. En «Gestión de permisos», añada:
   • im:chat:readonly - Leer información del grupo.
   • im:message:send_as_bot - Enviar mensajes como bot.
   • im:message:receive - Recibir mensajes.

3.2.2 Crear el bot

1. Añada la capacidad de «Robot» a la aplicación.
2. Copie el App ID y el App Secret.

3.2.3 Archivo de configuración

{
    "platform": [
        {
            "type": "lark",
            "enable": true,
            "app_id": "TU_APP_ID",
            "app_secret": "TU_APP_SECRET",
            "verification_token": "TU_VERIFICATION_TOKEN"
        }
    ]
}

3.3 Configuración de bot de QQ (OneBot)

El bot de QQ requiere el uso de NapCat o LLOneBot.

3.3.1 Instalar NapCat

Se recomienda NapCat como cliente de QQ:

# Opción 1: Despliegue con Docker (Recomendado)
docker pull napneko/napcat:latest

# Opción 2: Instalación directa
# Consulte https://napneko.github.io/

3.3.2 Archivo de configuración

{
    "platform": [
        {
            "type": "onebot",
            "enable": true,
            "ws_host": "127.0.0.1",
            "ws_port": 3001,
            "http_port": 3000
        }
    ]
}

3.3.3 Iniciar NapCat

docker run -d \
  --name napcat \
  -p 3000:3000 \
  -p 3001:3001 \
  -v ./data:/app/data \
  napneko/napcat:latest

---

4. Configuración del Modelo de Lenguaje Grande (LLM)

Sin un modelo de lenguaje, el bot es solo un mensajero. Este paso es crucial.

4.1 Uso de Defapi (Recomendado)

Defapi es una plataforma agregadora de modelos de IA con precios competitivos y buena velocidad de acceso.

4.1.1 Registrarse en Defapi

1. Visite Defapi y cree una cuenta.
2. Obtenga su API Key en la consola.

4.1.2 Archivo de configuración

Añada la configuración del proveedor en cmd_config.json:

{
    "provider": [
        {
            "id": "defapi",
            "type": "openai_chat_completion",
            "model": "claude-sonnet-4-20250514",
            "key": ["TU_API_KEY_DEFAPI"],
            "api_base": "https://api.defapi.org/v1",
            "enable": true
        }
    ],
    "provider_settings": {
        "default_provider_id": "defapi",
        "enable": true
    }
}

4.2 Uso oficial de OpenAI

Si dispone de una API Key de OpenAI:

{
    "provider": [
        {
            "id": "openai",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["sk-xxx"],
            "api_base": "https://api.openai.com/v1",
            "proxy": "http://127.0.0.1:7890",
            "enable": true
        }
    ]
}

4.3 Uso de DeepSeek

Recomendado para desarrolladores por su alta relación costo-beneficio:

{
    "provider": [
        {
            "id": "deepseek",
            "type": "openai_chat_completion",
            "model": "deepseek-chat",
            "key": ["sk-xxx"],
            "api_base": "https://api.deepseek.com/v1",
            "enable": true
        }
    ]
}

---

5. Inicio y verificación

5.1 Iniciar el servicio

astrbot

Verá una salida similar a esta:

INFO - AstrBot iniciándose...
INFO - WebUI: http://localhost:6185
INFO - Adaptadores de plataforma cargados: telegram, lark, onebot
INFO - Proveedor cargado: defapi
INFO - ¡AstrBot se ha iniciado correctamente!

5.2 Acceder a la consola

Abra su navegador en http://localhost:6185. Credenciales por defecto:

• Usuario: astrbot
• Contraseña: astrbot

5.3 Probar el diálogo

Envíe un mensaje al bot en la plataforma configurada:

¡Hola! ¿Quién eres?

Si todo es correcto, el bot responderá utilizando el modelo configurado.

---

6. Solución de problemas comunes

6.1 Fallo al iniciar el bot

Problema: ModuleNotFoundError: No module named 'astrbot'

Solución:

# Reinstalar
uv tool uninstall astrbot
uv tool install astrbot

6.2 No se reciben mensajes

Problema: Se envía un mensaje al bot pero no hay respuesta.

Pasos de verificación:

1. Compruebe si el adaptador de plataforma está habilitado:

astrbot -p

1. Revise los registros:

tail -f logs/astrbot.log

1. Confirme que la configuración de la plataforma y el Token/llave son correctos.

6.3 Fallo en la llamada al modelo

Problema: Error: API request failed

Pasos de verificación:

1. Confirme que la API Key es correcta.
2. Verifique la conexión de red (necesita proxy en ciertas regiones).
3. Verifique que el nombre del modelo sea correcto.
4. Confirme que tiene saldo suficiente en la cuenta.

6.4 Límite de velocidad (Rate Limit)

Problema: 429 Too Many Requests

Solución: Configure múltiples API Keys para lograr un balanceo de carga:

{
    "provider": [
        {
            "id": "openai-multi",
            "type": "openai_chat_completion",
            "model": "gpt-4o",
            "key": ["key1", "key2", "key3"],
            "api_base": "https://api.openai.com/v1",
            "enable": true
        }
    ]
}

6.5 El bot de Telegram no responde en chat privado

Problema: Funciona en grupos pero no en chats privados.

Solución: Debe hablar con BotFather, enviar /start para activar el bot y luego el chat privado funcionará.

6.6 El bot de Feishu no recibe mensajes

Problema: Configuración correcta pero sin recepción.

Solución:

1. Confirme que la aplicación ha sido publicada.
2. Asegúrese de haber añadido el bot al grupo o habilitado el chat privado.
3. Verifique que el acceso público al servidor funciona correctamente.

---

7. Extensiones avanzadas

7.1 Desarrollo de complementos (Plugins)

AstrBot admite extensiones. Cree plugins/mi_plugin/main.py:

from astrbot.api.event import filter, EventMessage

@filter()
async def handle_hello(event: EventMessage):
    if event.message_str == "hola":
        await event.reply("¡Hola! ¡Soy tu asistente de IA!")

7.2 Configuración de personalidad

En la página de «Personalidad» de la consola, cree una persona y defina el prompt del sistema:

Eres un asistente de IA amigable que prefiere responder de forma concisa.

7.3 Integración con MCP

AstrBot soporta el protocolo MCP para llamar a herramientas externas. Configure los servicios MCP en la página de «Habilidades» de la consola.

7.4 Base de conocimientos RAG

Cree una base de conocimientos en la consola y cargue documentos para que la IA posea conocimientos de un dominio específico.

---

Lecturas adicionales

• Documentación oficial de AstrBot
• AstrBot en GitHub
• Guía de despliegue de NapCat QQ
• Documentación de Feishu Open Platform
• Especificación del protocolo OneBot