Requisitos previos

Antes de comenzar, verifique que su entorno cumpla con los siguientes requisitos para evitar errores posteriores:

• Node.js 18+ (se recomienda instalar Node.js 20 LTS)
• Git (para clonar archivos de configuración)
• .NET 6 Runtime (obligatorio para usuarios de Windows, ya que la versión de escritorio de WorkBuddy depende de él)
• Una conexión de red estable y accesible (los webhooks deben ser alcanzables para integrarse con las plataformas de mensajería)
• Permisos de desarrollaodr en cada plataforma de mensajería (Feishu y DingTalk requieren aprobación del administrador para la aplicación)

En macOS, si al iniciar WorkBuddy por primera vez aparece un mensaje de "no se puede abrir", vaya a "Configuración del Sistema → Privacidad y Seguridad → Abrir de todas formas" para permitir la ejecución. Esto se debe a que Gatekeeper bloquea aplicaciones no firmadas, no a un problema del propio software.

Instalación de un solo paso de WorkBuddy

WorkBuddy está disponible en dos versiones: cliente de escritoroi y línea de comandos. Se recomienda la versión de escritorio por su interfaz de configuración más amigable.

Descargue el paquete de instalación correspondiente a su sistema desde el sitio web oficial: .exe para Windows, .dmg para macOS (distinga entre Intel y Apple Silicon), y .AppImage para Linux.

Al iniciar por primera vez, se le pedirá crear un espacio de trabajo local, que por defecto se ubicará en ~/.workbuddy/. Dentro de esta carpeta se generarán varios archivos clave:

~/.workbuddy/
├── config.yaml      # Configuración principal
├── models.yaml      # Configuración de modelos
├── adapters/        # Adaptadores de plataforma
└── logs/            # Registros de ejecución

Si el inicio se queda en la pantalla de carga durante más de 30 segundos, es probable que el puerto esté ocupado. WorkBuddy escucha en el puerto 23333 por defecto. Use lsof -i :23333 (en Windows, netstat -ano | findstr 23333) para verificar si otro proceso lo está usando. Mátelo y reinicie la aplicación.

Configuración de múltiples modelos (Hunyuan / DeepSeek / Kimi)

WorkBuddy gestiona la configuración de múltiples modelos en el archivo ~/.workbuddy/models.yaml. La estructura es sencilla:

llm_models:
  - name: hunyuan
    provider: tencent
    api_key: "tu-clave-hunyuan"
    model_id: "hunyuan-pro"
    is_default: true

  - name: deepseek
    provider: openai_compatible
    base_url: "https://api.deepseek.com/v1"
    api_key: "tu-clave-deepseek"
    model_id: "deepseek-chat"

  - name: kimi
    provider: openai_compatible
    base_url: "https://api.moonshot.cn/v1"
    api_key: "tu-clave-kimi"
    model_id: "moonshot-v1-32k"

routing:
  primary: hunyuan
  fallback_chain: [deepseek, kimi]

El campo is_default: true indica que este es el modelo predeterminado. fallback_chain define una cadena de respaldo: si el modelo principal falla, se cambiará automáticamente al siguiente. Se recomienda establecer Hunyuan como predeterminado (por su mejor compatibilidad con el ecosistema Tencent) y usar DeepSeek y Kimi como respaldos.

Un detalle importante: es mejor envolver el valor de api_key entre comillas dobles, ya que el analizador YAML a veces tiene problemas con cadenas que comienzan con sk-.

¿Cansado de solicitar claves individualmente? Considere una solución agregada

Si no desea solicitar claves en tres plataformas diferentes (Hunyuan en la consola de Tencent Cloud, DeepSeek en platform.deepseek.com y Kimi en platform.moonshot.cn), puede utilizar un servicio de agregación. Una sola clave API puede ofrecer acceso a más de 50 modelos, como GPT-4o, Claude Opus 4.6, Gemini, DeepSeek, Kimi y Hunyuan, con un protocolo compatible con OpenAI SDK, baja latencia y facturación basada en el consumo.

Su archivo models.yaml se modificaría así:

llm_models:
  - name: hunyuan
    provider: openai_compatible
    base_url: "https://api.ejemplo-agregador.com/v1"
    api_key: "sk-ejemplo"
    model_id: "hunyuan-pro"

  - name: deepseek
    provider: openai_compatible
    base_url: "https://api.ejemplo-agregador.com/v1"
    api_key: "sk-ejemplo"
    model_id: "deepseek-chat"

  - name: kimi
    provider: openai_compatible
    base_url: "https://api.ejemplo-agregador.com/v1"
    api_key: "sk-ejemplo"
    model_id: "moonshot-v1-32k"

La ventaja es la redundancia entre múltiples proveedores: si uno falla, se cambia automáticamente, y toda la facturación se centraliza.

Integración con WeChat

WeChat es un caso especial, ya que las cuentas personales oficiales no tienen una API abierta. WorkBuddy utiliza un esquema de "Hook del cliente de escritorio de WeChat", que se inyecta en el proceso local de WeChat para leer mensajes.

Pasos:

1. Cierre WeChat por completo.
2. Abra WorkBuddy → Adaptadores → WeChat → Iniciar.
3. WorkBuddy iniciará WeChat automáticamente y le pedirá escanear un código QR para iniciar sesión.
4. Después de escanear, configure en WorkBuddy una palabra clave de activación, por ejemplo, @asistente +pregunta, para que solo responda cuando se use esa palabra.

Agregue esta sección en config.yaml:

adapters:
  wechat:
    enabled: true
    command_prefix: "@asistente"
    allowed_groups: ["Grupo de desarrolladores", "Chat de IA"]
    model: hunyuan

allowed_groups es una lista blanca de grupos. Si no se completa, WorkBuddy responderá en todos los grupos, lo que podría resultar en ser expulsado, así que úselo con precaución.

Integración con QQ

QQ utiliza el protocolo OneBot v11. Necesita instalar un cliente de protocolo como NapCat o Lagrange.

Ejemplo con NapCat:

# Mac/Linux
curl -fsSL https://napcat.qq.com/install.sh | bash

# Iniciar
napcat -q tu-numero-de-qq

Después de iniciar, escanee el código QR para iniciar sesión. Luego, configure en WorkBuddy el WebSocket inverso de OneBot:

adapters:
  qq:
    enabled: true
    protocol: onebot_v11
    ws_url: "ws://127.0.0.1:3001"
    access_token: "tu-token-aqui"
    command_prefix: "/ai"
    model: deepseek

Integración con Feishu

Feishu es la más estandarizada de estas plataformas. Utiliza una aplicación empresarial personalizada con suscripción a eventos.

1. En la plataforma abierta de Feishu (open.feishu.cn), cree una aplicación empresarial personalizada.
2. En "Capacidades de la aplicación", agregue un robot.
3. En "Suscripción a eventos", configure la URL de solicitud (obligatoriamente HTTPS): https://tu-dominio.com/workbuddy/feishu/event.
4. Suscríbase al evento im.message.receive_v1.
5. En "Gestión de permisos", solicite permisos como im:message e im:message.group_at_msg.

Configuración en WorkBuddy:

adapters:
  feishu:
    enabled: true
    app_id: "cli_ejemplo"
    app_secret: "ejemplo"
    verification_token: "ejemplo"
    encrypt_key: ""   # Opcional, para transmisión cifrada
    model: hunyuan

Si no tiene un servidor HTTPS público, puede usar cloudflared para un túnel inverso durante el desarrollo local:

cloudflared tunnel --url http://localhost:23333

Esto le proporcionará un dominio temporal que puede usar en la suscripción de eventos.

Integración con DingTalk

DingTalk sigue un proceso similar al de Feishu: crear una aplicación en la plataforma abierta y configurar una devolución de llamada de eventos.

1. En open.dingtalk.com, cree una aplicación empresarial interna.
2. Agregue la capacidad de robot.
3. En "Suscripción a eventos", seleccione "Modo HTTP" y configure la URL de devolución de llamada.
4. Suscríbase al evento "Recibir mensaje de @robot en chat grupal".

adapters:
  dingtalk:
    enabled: true
    app_key: "ding-ejemplo"
    app_secret: "ejemplo"
    robot_code: "ejemplo"
    model: kimi

Tenga en cuenta que la devolución de llamada del robot de DingTalk tiene un límite de tiempo de espera de 3 segundos. Si su modelo de IA es lento, active el modo "responder primero con marcador y luego enviar respuesta asíncrona" en WorkBuddy:

adapters:
  dingtalk:
    async_reply: true
    placeholder: "Pensando..."

Problemas comunes de conexión y sus soluciones

Ordenados por frecuencia de aparición, estos son algunos problemas que pueden surgir:

1. Error al iniciar WorkBuddy: "Cannot find module 'xxx'"

Faltan dependencias. Vaya al directorio de instalación de WorkBuddy, elimine la carpeta node_modules y vuelva a ejecutar:

cd /ruta/a/workbuddy
rm -rf node_modules
npm install --force

2. El adaptador de WeChat muestra "Error de inyección de proceso / Hook fallido"

La versión de WeChat no es compatible. WorkBuddy solo es estable con la serie WeChat 3.9.x. La versión 4.0 aún no tiene un Hook completamente adaptado. Degrade la versión de WeChat o espere una actualización oficial.

3. La suscripción de eventos de Feishu muestra "Error de verificación" constantemente

El 99% de las veces se debe a que la URL no es accesible o el token no coincide. Verifique la conectividad de la devolución de llamada con curl:

curl -X POST https://tu-dominio.com/workbuddy/feishu/event \
  -H "Content-Type: application/json" \
  -d '{"type":"url_verification","challenge":"test123"}'

Debería devolver {"challenge":"test123"}. Si devuelve un 404, WorkBuddy no se está ejecutando o la ruta del proxy inverso es incorrecta.

4. La devolución de llamada de DingTalk muestra "Error de verificación de firma"

La firma de DingTalk se calcula con HmacSHA256 usando app_secret y una marca de tiempo. WorkBuddy lo verifica automáticamente. Si cambió app_secret pero no reinició WorkBuddy, el secreto antiguo aún está en caché. Reinicie el servicio.

5. Las llamadas a modelos siempre dan timeout

Primero, verifique si la URL base es accesible:

curl https://api.deepseek.com/v1/models -H "Authorization: Bearer tu-clave"

Si curl falla, es un problema de configuración de red. Una solución agregada simplifica este paso al usar una única URL base.

6. El cliente de protocolo QQ es expulsado o se desconecta con frecuencia

Los clientes de protocolo basados en NTQQ, como NapCat, son sensibles al entorno de inicio de sesión. Se recomienda:

• Usar un dispositivo que haya iniciado sesión durante mucho tiempo como host del cliente de protocolo.
• No usar cuentas recién registradas.
• Evitar cambiar de dispositivo con frecuencia en una semana.

7. Conflictos de puertos al tener múltiples adaptadores activos

Cada adaptador de WorkBuddy ocupa un puerto interno, comenzando desde el 23333 en adelante. Si su máquina tiene otros servicios webhook (como n8n o Dify local), puede especificar los puertos manualmente en config.yaml:

adapters:
  wechat:
    internal_port: 23334
  feishu:
    internal_port: 23335