Plugin de Canal Feishu para Clawdbot – Rápido y Ricamente Funcional

Clawdbot es un framework de chatbot ligero pero potente, y su ecosistema de plugins permite conectarlo a una variedad de plataformas. Una de las nuevas incorporaciones es el plugin de canal Feishu (Lark) (@m1heng-clawd/feishu). Convierte Clawdbot en un bot Feishu totalmente funcional capaz de:

• Enviar y recibir mensajes en chats directos y canales de grupo
• Subir y descargar imágenes, PDFs, hojas de Excel y otros archivos
• Renderizar respuestas como texto plano, tarjetas Markdown o mensajes sin formatear
• Soportar contextos con medios pesados (imágenes + texto incrustado)
• Gestionar permisos, suscripciones a eventos y flujos de emparejamiento de DM a través de la Plataforma Abierta de Feishu

A continuación, una guía paso a paso para poner en marcha este plugin, seguida de una referencia rápida a sus opciones de configuración más útiles y preguntas frecuentes.

1. Prerequisitos

Asegúrate de tener acceso de administrador en la Plataforma Abierta de Feishu para crear una nueva app y otorgar los alcances necesarios.

2. Instalar el Plugin

Puedes instalar el plugin directamente a través del gestor de plugins de Clawdbot o usando npm.

A. Gestor de Plugins de Clawdbot

clawdbot plugins install @m1heng-clawd/feishu

Esto descarga la última versión desde npm, la instala y registra el plugin.

B. Instalación NPM Manual

Si el comando anterior falla por problemas de entorno, descarga el tarball y instala localmente:

curl -O https://registry.npmjs.org/@m1heng-clawd/feishu/-/feishu-0.1.1.tgz
clawdbot plugins install ./feishu-0.1.1.tgz

3. Crear y Configurar una App Feishu

1. Ir a la Plataforma Abierta de Feishu y crear una nueva App auto construida.
2. En la página de Credenciales, anota el App ID y el App Secret.
3. Habilitar Permisos como se muestra a continuación:

Requeridos | Permiso | Alcance | Descripción | |------------|-------|-------------| | contact:user.base:readonly | Información de usuario | Obtener información básica del usuario | | im:message | Mensajería | Enviar y recibir mensajes | | im:message.p2p_msg:readonly | DM | Leer mensajes privados | | im:message.group_at_msg:readonly | Grupo | Recibir menciones @ | | im:message:send_as_bot | Enviar | Enviar mensajes como el bot | | im:resource | Medios | Subir/descargar imágenes/archivos |

Opcionales (habilitar si necesitas acceso extendido) | Permiso | Alcance | Descripción | |------------|-------|-------------| | im:message.group_msg | Grupo | Leer todos los mensajes de grupo | | im:message:readonly | Lectura | Obtener historial de mensajes | | im:message:update | Edición | Editar mensajes enviados | | im:message:recall | Retiro | Retirar mensajes enviados | | im:message.reactions:read | Reacciones | Ver reacciones |

1. Configurar Suscripciones a Eventos:
2. Selecciona Long Connection (recomendado).
3. Suscríbete a los siguientes eventos:
   • im.message.receive_v1 – obligatorio para recibir mensajes.
   • im.message.message_read_v1 – recibos de lectura (opcional).
   • im.chat.member.bot.added_v1 – bot añadido a un grupo.
   • im.chat.member.bot.deleted_v1 – bot eliminado de un grupo.

4. Asegúrate de que todos los permisos de evento estén aprobados por el proceso de revisión de Feishu.

5. Publicar la App – al menos en el ámbito Test para que puedas añadir el bot a los chats.

4. Configurar el Plugin en Clawdbot

Abre tu archivo de configuración de Clawdbot (normalmente clawdbot.yml o equivalente) y agrega:

channels:
  feishu:
    enabled: true
    appId: "cli_xxxxx"
    appSecret: "your_app_secret"
    domain: "feishu"          # usar "lark" para el dominio internacional
    connectionMode: "websocket"  # "websocket" o "webhook"
    dmPolicy: "pairing"         # "pairing", "open" o "allowlist"
    groupPolicy: "allowlist"    # "open", "allowlist" o "disabled"
    requireMention: true
    mediaMaxMb: 30
    renderMode: "auto"          # "auto", "raw" o "card"

Tip – El flujo de dmPolicy pairing requiere que el usuario apruebe los mensajes directos. Si deseas acceso instantáneo a DM, usa open.

5. Características Clave y Cómo Funcionan

6. Problemas Comunes y Solución

7. Comandos de Referencia

# Verificar estado del plugin
clawdbot plugins list

# Desinstalar el plugin
clawdbot plugins uninstall @m1heng-clawd/feishu

# Reiniciar Clawdbot para aplicar cambios de configuración
clawdbot restart

# Reiniciar historial de conversación en un chat
/​new

8. Extender el Plugin

El plugin expone una sencilla API TypeScript a través de clawdbot.plugin. Para casos de uso avanzados, bifurca el repositorio, agrega manejadores de mensajes personalizados o integra otras funciones del SDK de Feishu. ¡Las contribuciones son bienvenidas vía pull requests!

9. Resumen

El plugin de canal Feishu para Clawdbot combina potentes capacidades de IA con el ecosistema colaborativo de Feishu. Con una instalación sencilla, opciones de configuración robustas y manejo de medios enriquecido, puedes desplegar rápidamente un chatbot que se sienta nativo a Feishu. Ya sea que estés construyendo un asistente de equipo, un asistente de aprendizaje o simplemente experimentando, este plugin te brinda una base sólida para comenzar a crear conversaciones inteligentes.

¡Feliz codificación— y que tus bots nunca fallen al recibir mensajes!