Integracion de OpenClaw con Feishu/Lark: Guia Completa de Configuracion

Feishu vs Lark: Dos Plataformas, Una Sola Integracion

Feishu y Lark son las plataformas de mensajeria empresarial de ByteDance: Feishu para China continental, Lark para el mercado internacional. Comparten la misma arquitectura base, lo que significa que el proceso de integracion es practicamente identico sin importar cual use tu organizacion.

OpenClaw ofrece dos formas de conectar con Feishu/Lark:

Esta guia se centra en el plugin integrado, que cubre aproximadamente el 90% de los casos de uso. Si necesitas integracion completa con el workspace (leer documentos, gestionar calendarios, crear tareas), consulta la seccion del Plugin Oficial de Feishu mas adelante.

Requisitos Previos para la Configuracion de OpenClaw con Feishu

Antes de empezar, asegurate de tener:

• OpenClaw instalado y funcionando (version >= 2026.2). Si aun no lo has configurado, sigue la guia de instalacion.
• Una cuenta de desarrollador en Feishu en open.feishu.cn (o open.larksuite.com para Lark).
• Gateway accesible — verificalo con:

openclaw gateway status

No necesitas IP publica ni dominio. El plugin integrado usa el modo WebSocket por defecto, que establece una conexion saliente hacia los servidores de Feishu. Funciona detras de NATs, firewalls y la mayoria de redes corporativas sin necesidad de redireccion de puertos.

Paso 1: Crear una App Bot en Feishu/Lark

Acceder a la Consola de Desarrollador

Navega al portal de desarrolladores de tu plataforma:

• Feishu (China): open.feishu.cn → Developer Console
• Lark (Internacional): open.larksuite.com → Developer Console

Crear la Aplicacion

1. Haz clic en Create Custom App (o "Enterprise Self-Built Application" segun el idioma de tu consola)
2. Rellena el nombre de la app — algo descriptivo como "OpenClaw Assistant"
3. Opcionalmente, agrega un icono y una descripcion (es lo que los usuarios ven en el directorio del bot)

Copiar tus Credenciales

1. Ve a Credentials & Basic Info en la barra lateral izquierda
2. Copia el App ID (tiene un formato como cli_a5xxxxxxxxxxxxx)
3. Copia el App Secret

Manten tu App Secret seguro. Nunca lo subas a control de versiones, lo pegues en un chat ni lo incluyas en capturas de pantalla. Si se filtra, rotalo inmediatamente desde la consola de desarrollador.

Paso 2: Configurar los Permisos del Bot en Feishu

Tu app necesita permisos especificos (scopes) para enviar y recibir mensajes. Hay dos formas de configurarlos.

Opcion A: Importacion por Lotes (Recomendada)

Este es el metodo mas rapido: pegas un bloque JSON y todos los permisos se activan de una vez.

1. En la configuracion de tu app, ve a Development Settings → Permission Management
2. Haz clic en Batch Enable (o "Batch Import Scopes")
3. Pega el siguiente JSON:

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message:send_as_bot",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:message.group_msg", "im:message:readonly", "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly",
      "application:application:self_manage", "application:bot.menu:write",
      "cardkit:card:write",
      "docs:document.content:read", "sheets:spreadsheet",
      "wiki:wiki:readonly", "event:ip_list"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

4. Haz clic en Confirm para aplicar

Opcion B: Seleccion Manual

Si la importacion por lotes no esta disponible en tu version de la consola, activa estos permisos individualmente en Permission Management:

• im:message — Enviar y recibir mensajes
• im:message:send_as_bot — Enviar mensajes como bot
• im:message.p2p_msg:readonly — Leer mensajes directos
• im:message.group_at_msg:readonly — Leer mensajes con @mencion en grupos
• im:message.group_msg — Leer todos los mensajes de grupo
• im:resource — Acceder a recursos de mensajes (imagenes, archivos)
• im:chat — Acceder a metadatos del chat
• im:chat.members:bot_access — Verificar membresia del bot en chats
• contact:user.employee_id:readonly — Leer IDs de usuario
• docs:document.content:read — Leer contenido de documentos (opcional, para resumenes)
• sheets:spreadsheet — Acceder a hojas de calculo (opcional)
• wiki:wiki:readonly — Leer paginas de wiki (opcional)

Los permisos de documentos, hojas de calculo y wiki son opcionales. Activalos solo si quieres que el bot pueda leer y resumir documentos que los usuarios compartan en el chat.

Paso 3: Activar el Bot y las Suscripciones de Eventos en Feishu

Activar la Capacidad de Bot

1. En la barra lateral, ve a App Capabilities → Bot
2. Activa la capacidad de bot
3. Opcionalmente, configura una descripcion y texto de ayuda para el bot

Configurar Suscripciones de Eventos

Este es el paso clave que le indica a Feishu que reenvie los mensajes a tu instancia de OpenClaw.

1. Ve a Events & Callbacks → Event Subscriptions
2. En Connection Mode, selecciona Long Connection (WebSocket)
3. Agrega los siguientes eventos:

El evento im.message.receive_v1 es el unico estrictamente requerido; sin el, tu bot no recibira ningun mensaje. Los eventos de reacciones son utiles si quieres activar acciones basadas en emojis (por ejemplo, un pulgar arriba para confirmar una accion).

Sin suscripciones de eventos, el cuadro de texto no aparecera cuando los usuarios abran una conversacion con tu bot en Feishu/Lark. Si los usuarios ven el perfil del bot pero no pueden escribir, este es casi siempre el problema.

Esta es la causa numero 1 del error "app has not established a long connection". Si ves este error en tus logs, verifica que hayas agregado al menos el evento im.message.receive_v1 y seleccionado el modo Long Connection.

Paso 4: Publicar la App en Feishu

Tu app no sera visible para los usuarios hasta que la publiques.

1. Ve a Version Management en la barra lateral
2. Haz clic en Create Version
3. Introduce un numero de version (por ejemplo, 1.0.0) y notas de la release
4. Haz clic en Submit for Review

Para apps internas de empresa, la aprobacion suele ser automatica si eres administrador del tenant (o un admin con alcance completo). Si eres un desarrollador regular, la app puede pasar por el proceso de revision de tu organizacion — consulta con tu administrador.

Una vez publicada:

1. Abre Feishu (o Lark) en escritorio o movil
2. Ve al directorio de apps o la barra de busqueda
3. Busca el nombre de tu app
4. Deberias ver el bot listado, pero no le envies mensajes todavia. Primero configura OpenClaw.

Paso 5: Configurar el Canal Feishu en OpenClaw

Configuracion Rapida via CLI

La forma mas rapida de conectar:

openclaw channels add    # Selecciona "Feishu", luego pega tu App ID y Secret
openclaw gateway restart

El CLI te guia por las opciones esenciales de forma interactiva.

Configuracion Manual

Para mayor control, edita ~/.openclaw/openclaw.json directamente:

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",            // Usa "lark" para Lark internacional
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "open",
      requireMention: true,
      streaming: true,
      typingIndicator: true,
      accounts: {
        main: {
          appId: "cli_a5xxxxxxxxxxxxx",
          appSecret: "tu-app-secret",
          botName: "AI Assistant"
        }
      }
    }
  }
}

Referencia de Configuracion

Feishu vs Lark en la configuracion: La unica diferencia es el campo domain. Configuralo como "feishu" si tu organizacion usa Feishu (China), o "lark" si usas Lark (internacional). Todo lo demas — credenciales, permisos, eventos — funciona exactamente igual.

Paso 6: Iniciar el Gateway de OpenClaw y Vincular Feishu

Lanzar el Gateway

openclaw gateway           # Inicia el gateway (en primer plano)

En otra terminal, observa los logs:

openclaw logs --follow     # Transmite los logs en tiempo real

Deberias ver algo como:

[feishu] WebSocket connected to wss://open.feishu.cn/...
[feishu] Bot "AI Assistant" is online

Vincular tu Cuenta

La politica de DM por defecto es pairing, lo que significa que los nuevos usuarios deben ser aprobados antes de poder chatear con el bot. Esto previene accesos no autorizados.

1. Abre Feishu (o Lark) y busca tu bot
2. Envia cualquier mensaje — "hola" funciona
3. Revisa tu terminal. Veras una solicitud de vinculacion con un codigo:

[feishu] New pairing request from user_xxxxx (Code: ABC123)

4. Aprueba la vinculacion:

openclaw pairing approve feishu ABC123

5. Vuelve a Feishu/Lark y envia otro mensaje
6. La IA deberia responder

Verificar la Conexion

openclaw gateway status

Salida esperada:

Feishu: connected (websocket)
  Account: main
  Bot: AI Assistant
  Paired users: 1
  Active groups: 0

Si el estado muestra disconnected, consulta la seccion de Solucion de Problemas mas abajo.

Configuracion de Chat Grupal en Feishu

Por defecto, groupPolicy: "open" permite al bot unirse a cualquier grupo donde lo agreguen. Para mayor control, usa una lista de permitidos:

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      requireMention: true,
      groups: {
        "oc_xxxxxxxxx": {           // ID de chat de Feishu
          agentId: "main",
          requireMention: false      // Override: responder a todos los mensajes en este grupo
        },
        "oc_yyyyyyyyy": {
          agentId: "support",        // Enrutar a un agente diferente
          requireMention: true
        }
      }
    }
  }
}

Para encontrar el ID de un grupo, agrega el bot al grupo y revisa los logs — el ID se muestra cuando el bot se une.

Consejo: Configura requireMention: true de forma global y haz override por grupo. Esto evita que el bot sea ruidoso en canales grandes mientras permite conversacion libre en grupos dedicados a IA.

Modo Webhook para OpenClaw y Feishu

WebSocket es el modo de conexion recomendado, pero algunas redes corporativas bloquean las conexiones WebSocket salientes persistentes. En ese caso, cambia al modo webhook:

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "desde-la-consola-feishu",
      encryptKey: "desde-la-consola-feishu",
      webhookPath: "/feishu/events",
      webhookPort: 3000
    }
  }
}

Para obtener el token de verificacion y la clave de encriptacion:

1. En la configuracion de tu app de Feishu, ve a Events & Callbacks → Encryption Strategy
2. Copia el Verification Token y el Encrypt Key

Luego configura la URL de solicitud en la consola de Feishu:

1. En Events & Callbacks → Event Subscriptions, cambia a Push to URL
2. Configura la URL como https://tu-dominio.com/feishu/events
3. Haz clic en Verify — Feishu envia una solicitud de challenge y OpenClaw responde automaticamente

El modo webhook requiere una URL accesible publicamente. Necesitaras un dominio, certificado TLS y reglas de firewall adecuadas. Para la mayoria de configuraciones, WebSocket es mucho mas sencillo.

Enrutamiento Multi-Agente en OpenClaw para Feishu

Si ejecutas multiples agentes de IA, puedes enrutar diferentes conversaciones a diferentes agentes:

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "support", match: { channel: "feishu", peer: { kind: "direct", id: "ou_xxxxx" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxxxxxxxx" } } }
  ]
}

Por defecto, los mensajes directos se enrutan al agente principal (main). Puedes asignar usuarios especificos o grupos concretos a agentes diferentes usando su ID. Esto es util para organizaciones que quieren un asistente de proposito general, un agente de soporte al cliente y un agente de herramientas para desarrolladores — todos funcionando a traves del mismo bot de Feishu pero respaldados por diferentes modelos y prompts.

Plugin Oficial de Feishu para OpenClaw

El plugin oficial de Feishu esta mantenido por el equipo de Feishu/Lark de ByteDance. A diferencia del plugin integrado (que opera como bot), el plugin oficial usa OAuth para actuar en nombre de un usuario. Esto le da acceso al workspace completo: documentos, calendarios, tareas, hojas de calculo y wikis.

Requisitos

• OpenClaw >= 2026.2.26 (Linux/macOS) o >= 2026.3.2 (Windows)
• Node.js >= 22
• npm disponible en el PATH

Instalacion

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-plugin.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu-plugin.tgz -g
rm /tmp/feishu-plugin.tgz
feishu-plugin-onboard install

El comando feishu-plugin-onboard install lanza un asistente de configuracion interactivo que:

1. Te pide tu App ID y App Secret de Feishu
2. Abre una ventana del navegador para autorizacion OAuth
3. Genera un archivo de configuracion en ~/.openclaw/plugins/feishu/config.json
4. Registra el plugin en tu instancia de OpenClaw

Post-Instalacion

Despues de la instalacion, verifica que el plugin se haya cargado:

openclaw plugins list

Deberias ver feishu-official en la salida. Pruebalo pidiendo al bot que realice una accion del workspace:

@Bot Resume el ultimo documento en el espacio wiki "Engineering"

Diagnosticos

Si el plugin no funciona:

feishu-plugin-onboard doctor           # Verificar problemas comunes
feishu-plugin-onboard doctor --fix     # Corregir automaticamente los problemas detectados
feishu-plugin-onboard info --all       # Ver informacion completa del plugin

Consideracion de seguridad: El plugin oficial accede a los datos de tu workspace a traves de tu token OAuth personal. Esto significa que el bot puede leer cualquier documento, evento de calendario o tarea a la que tu tengas acceso. No uses el plugin oficial en bots o maquinas compartidas — usalo solo en instancias personales y seguras.

Usar Ambos Plugins

Puedes ejecutar el plugin integrado y el oficial al mismo tiempo. El integrado se encarga de la mensajeria, mientras que el oficial maneja las acciones del workspace. OpenClaw enruta las solicitudes al plugin adecuado automaticamente.

Para desactivar el plugin oficial sin desinstalarlo:

feishu-plugin-onboard disable

Solucion de Problemas con la Integracion Feishu

"No aparece el cuadro de texto" — los usuarios no pueden escribir al bot

Causa: Faltan suscripciones de eventos o la app no esta publicada.

Solucion:

1. Confirma que im.message.receive_v1 esta agregado en Events & Callbacks
2. Confirma que el modo de conexion esta configurado como Long Connection
3. Confirma que la app esta publicada (Version Management → verifica que hay una version activa)
4. Reinicia el gateway: openclaw gateway restart

Error "App has not established a long connection"

Causa: La suscripcion de eventos de Feishu espera una conexion WebSocket, pero OpenClaw aun no se ha conectado.

Solucion:

1. Asegurate de que connectionMode es "websocket" en tu configuracion
2. Reinicia el gateway: openclaw gateway restart
3. Revisa los logs: openclaw logs --follow — busca mensajes de conexion WebSocket
4. Si estas detras de un proxy estricto, verifica si las conexiones WebSocket salientes estan bloqueadas

El bot esta en linea pero no responde a los mensajes

Causa: Generalmente un problema de vinculacion o una politica de DM mal configurada.

Solucion:

1. Verifica si el usuario esta vinculado: openclaw pairing list feishu
2. Si usas el modo pairing, aprueba al usuario: openclaw pairing approve feishu <CODIGO>
3. Si quieres que cualquiera chatee sin vinculacion, configura dmPolicy: "open"
4. Revisa los logs en busca de errores: openclaw logs --follow

El bot no responde en chats grupales

Causa: El bot requiere @mencion pero no fue mencionado, o la politica de grupo bloquea el grupo.

Solucion:

1. Asegurate de que groupPolicy es "open" o que el grupo esta en la lista de permitidos
2. Si requireMention es true, los usuarios deben @mencionar al bot
3. Verifica que el bot sea realmente miembro del grupo
4. Confirma que el permiso im:message.group_msg esta activado

Errores "Message send failed" o "send_as_bot"

Causa: Falta el permiso im:message:send_as_bot, o la app no se ha republicado despues de agregar permisos.

Solucion:

1. Confirma que el permiso esta activado en la consola de desarrollador
2. Crea una nueva version y publicala — los cambios de permisos requieren una nueva release
3. Reinicia el gateway

Conflicto entre el plugin integrado y el oficial

Causa: Ambos plugins intentan manejar el mismo evento.

Solucion:

1. Esto normalmente no es un problema — OpenClaw deduplica eventos. Si ves respuestas dobles, desactiva uno:

feishu-plugin-onboard disable    # Desactivar plugin oficial
# O
openclaw channels disable feishu  # Desactivar plugin integrado

2. Evalua cual plugin realmente necesitas — la mayoria de usuarios solo necesitan el plugin integrado

Windows: Error ENOENT al instalar el plugin oficial

Causa: npm no puede encontrar el archivo .tgz descargado, generalmente un problema de ruta en Windows.

Solucion:

1. Usa una ruta absoluta completa:

npm install C:\Users\TuNombre\Downloads\feishu-plugin.tgz -g

2. Asegurate de ejecutar la terminal como Administrador
3. Verifica Node.js >= 22: node --version

Referencia de Comandos de OpenClaw para Feishu

FAQ

Necesito una IP publica o un dominio?

No. El modo WebSocket (por defecto) conecta de forma saliente desde tu maquina hacia los servidores de Feishu. No hay trafico entrante, ni redireccion de puertos, ni registros DNS. La unica excepcion es el modo webhook, que si requiere una URL accesible publicamente.

Cual es la diferencia entre Feishu y Lark?

Feishu es para China continental. Lark es la version internacional. Funcionan en infraestructura separada pero tienen las mismas funcionalidades y APIs. La unica diferencia en la configuracion es el campo domain — configuralo como "feishu" o "lark". Tu App ID y Secret funcionan en la plataforma donde los hayas creado.

Deberia usar el plugin integrado o el oficial?

Para mensajeria — enviar y recibir mensajes, leer contenido compartido en chat — el plugin integrado es todo lo que necesitas. Para acciones del workspace — leer documentos, gestionar calendarios, crear tareas, consultar hojas de calculo — usa el plugin oficial. Puedes ejecutar ambos simultaneamente.

Puedo usar Feishu junto con otros canales?

Si. OpenClaw soporta multiples canales de forma simultanea. Puedes tener Feishu, Telegram, Discord, WhatsApp y otros funcionando al mismo tiempo, cada uno conectado al mismo agente o a agentes diferentes. Agregalos con openclaw channels add.

Las respuestas son lentas — como las acelero?

1. Activa streaming (streaming: true) — esto muestra respuestas parciales mientras se generan, asi los usuarios ven el texto aparecer inmediatamente
2. Revisa tu modelo — los modelos mas grandes son mas lentos. Prueba un modelo mas rapido para consultas rutinarias
3. Revisa la latencia de red — si tu instancia de OpenClaw esta lejos de los servidores de Feishu, las respuestas se sentiran mas lentas
4. Revisa tu prompt — los prompts de sistema largos aumentan el tiempo de procesamiento

Mi App Secret se ha comprometido — que hago?

1. Ve a la consola de desarrollador de Feishu inmediatamente
2. Navega a Credentials & Basic Info
3. Haz clic en Reset junto al App Secret
4. Copia el nuevo secret
5. Actualiza ~/.openclaw/openclaw.json con el nuevo valor
6. Reinicia el gateway: openclaw gateway restart
7. El secret anterior se invalida al instante — no es necesario revocar sesiones individuales

Siguientes Pasos Despues de Configurar Feishu con OpenClaw

Ahora que tu integracion con Feishu/Lark esta funcionando, explora que mas puede hacer OpenClaw:

• Consulta los 50+ canales soportados — conecta plataformas adicionales
• Directorio de Skills — descubre lo que tu asistente de IA puede hacer
• Guia de solucion de problemas — resuelve problemas comunes en todos los canales
• Guia completa para principiantes — aprende OpenClaw desde cero
• Integracion con Telegram — agrega Telegram como otro canal
• Integracion con Discord — configura Discord con Gateway Intents