Configura tu bot de Feishu con OpenClaw

Feishu (Lark) es una plataforma de chat para equipos que las empresas utilizan para mensajería y colaboración. Este plugin conecta OpenClaw a un bot de Feishu/Lark mediante la suscripción de eventos por WebSocket de la plataforma, lo que permite recibir mensajes sin necesidad de exponer una URL de Gateway pública.

Plugin integrado

Feishu viene incluido en las versiones actuales de OpenClaw, por lo que no necesitas instalar el plugin por separado.

Si usas una versión antigua o una instalación personalizada que no incluya Feishu, instálalo manualmente:

openclaw plugins install @openclaw/feishu

Inicio rápido

Tienes dos formas de añadir el canal de Feishu:

Método 1: onboarding (recomendado)

Si acabas de instalar OpenClaw, ejecuta el onboarding:

openclaw onboard

El asistente te guiará para:

1. Crear una app en Feishu y obtener las credenciales
2. Configurar las credenciales de la app en OpenClaw
3. Iniciar el Gateway

✅ Tras la configuración, comprueba el estado del Gateway:

• openclaw gateway status
• openclaw logs --follow

Método 2: configuración por CLI

Si ya completaste la instalación inicial, añade el canal a través de la CLI:

openclaw channels add

Elige Feishu e introduce el App ID y el App Secret.

✅ Tras la configuración, gestiona el Gateway:

• openclaw gateway status
• openclaw gateway restart
• openclaw logs --follow

Paso 1: Crear una app en Feishu

1. Abre la Feishu Open Platform

Visita Feishu Open Platform e inicia sesión.

Los inquilinos de Lark (global) deben usar https://open.larksuite.com/app y configurar domain: "lark" en la configuración de Feishu.

2. Crea una app

1. Haz clic en Create enterprise app
2. Escribe el nombre y la descripción de la app
3. Elige un icono para la app

3. Copia las credenciales

En Credentials & Basic Info, copia:

• App ID (formato: cli_xxx)
• App Secret

❗ Importante: mantén el App Secret en privado.

4. Configura los permisos

En Permissions, haz clic en Batch import y pega lo siguiente:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

5. Activa la función de bot

En App Capability > Bot:

1. Activa la función de bot
2. Configura el nombre del bot

6. Configura la suscripción de eventos

⚠️ Importante: antes de configurar la suscripción de eventos, asegúrate de que:

1. Ya ejecutaste openclaw channels add para Feishu
2. El Gateway está funcionando (openclaw gateway status)

En Event Subscription:

1. Elige Use long connection to receive events (WebSocket)
2. Añade el evento: im.message.receive_v1
3. (Opcional) Para flujos de trabajo con comentarios en Drive, añade también: drive.notice.comment_add_v1

⚠️ Si el Gateway no está funcionando, es posible que la configuración de la conexión larga no se guarde correctamente.

7. Publica la app

1. Crea una versión en Version Management & Release
2. Envía a revisión y publica
3. Espera la aprobación del administrador (las apps de empresa suelen aprobarse automáticamente)

Paso 2: Configurar OpenClaw

Configurar con el asistente (recomendado)

openclaw channels add

Elige Feishu y pega tu App ID + App Secret.

Configurar mediante el archivo de configuración

Edita ~/.openclaw/openclaw.json:

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "My AI assistant",
        },
      },
    },
  },
}

Si usas connectionMode: "webhook", configura tanto verificationToken como encryptKey. El servidor de webhook de Feishu se vincula a 127.0.0.1 por defecto; configura webhookHost solo si necesitas una dirección de vinculación diferente.

Verification Token y Encrypt Key (modo webhook)

Cuando uses el modo webhook, configura channels.feishu.verificationToken y channels.feishu.encryptKey en tu archivo. Para obtener los valores:

1. En Feishu Open Platform, abre tu app
2. Ve a Development → Events & Callbacks (开发配置 → 事件与回调)
3. Abre la pestaña Encryption (加密策略)
4. Copia el Verification Token y el Encrypt Key

La siguiente captura muestra dónde encontrar el Verification Token. El Encrypt Key aparece en esa misma sección de Encryption.

Configurar mediante variables de entorno

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Dominio de Lark (global)

Si tu inquilino está en Lark (internacional), establece el dominio como lark (o una cadena de dominio completa). Puedes configurarlo en channels.feishu.domain o por cuenta (channels.feishu.accounts.<id>.domain).

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

Flags de optimización de cuota

Puedes reducir el uso de la API de Feishu con dos flags opcionales:

• typingIndicator (por defecto true): si es false, omite las llamadas de reacción de escritura.
• resolveSenderNames (por defecto true): si es false, omite las llamadas de búsqueda de perfil del remitente.

Configúralos a nivel general o por cuenta:

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

Paso 3: Iniciar + probar

1. Inicia el Gateway

openclaw gateway

2. Envía un mensaje de prueba

En Feishu, busca tu bot y envíale un mensaje.

3. Aprueba el emparejamiento

Por defecto, el bot responde con un código de emparejamiento. Apruébalo:

openclaw pairing approve feishu <CODE>

Después de la aprobación, puedes chatear normalmente.

---

Resumen

• Canal de bot de Feishu: bot de Feishu gestionado por el Gateway
• Enrutamiento determinista: las respuestas siempre vuelven a Feishu
• Aislamiento de sesiones: los mensajes directos comparten una sesión principal; los grupos están aislados
• Conexión WebSocket: conexión larga mediante el SDK de Feishu, no necesitas una URL pública

---

Control de acceso

Mensajes directos

• Por defecto: dmPolicy: "pairing" (los usuarios desconocidos reciben un código de emparejamiento)

• Aprobar emparejamiento:

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

• Modo lista permitida: configura channels.feishu.allowFrom con los Open IDs permitidos

Chats grupales

1. Política de grupo (channels.feishu.groupPolicy):

• "open" = permite a todos en los grupos
• "allowlist" = solo permite groupAllowFrom
• "disabled" = desactiva los mensajes de grupo

Por defecto: allowlist

2. Requisito de mención (channels.feishu.requireMention, se puede sobrescribir mediante channels.feishu.groups.<chat_id>.requireMention):

• true explícito = requiere @mención
• false explícito = responde sin menciones
• si no se define y groupPolicy: "open" = por defecto es false
• si no se define y groupPolicy no es "open" = por defecto es true

---

Ejemplos de configuración de grupos

Permitir todos los grupos, sin necesidad de @mención (por defecto para grupos abiertos)

{
  channels: {
    feishu: {
      groupPolicy: "open",
    },
  },
}

Permitir todos los grupos, pero seguir requiriendo @mención

{
  channels: {
    feishu: {
      groupPolicy: "open",
      requireMention: true,
    },
  },
}

Permitir solo grupos específicos

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Restringir qué remitentes pueden enviar mensajes en un grupo (lista permitida de remitentes)

Además de permitir el grupo en sí, todos los mensajes en ese grupo están filtrados por el open_id del remitente: solo los usuarios listados en groups.<chat_id>.allowFrom tienen sus mensajes procesados; los mensajes de otros miembros se ignoran (esto es un filtrado completo a nivel de remitente, no solo para comandos de control como /reset o /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu user IDs (open_id) look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

---

Obtener IDs de grupo/usuario

IDs de grupo (chat_id)

Los IDs de grupo tienen un formato tipo oc_xxx.

Método 1 (recomendado)

1. Inicia el Gateway y menciona al bot con un @ en el grupo.
2. Ejecuta openclaw logs --follow y busca el chat_id.

Método 2

Usa el debugger de la API de Feishu para listar los chats grupales.

IDs de usuario (open_id)

Los IDs de usuario tienen un formato tipo ou_xxx.

Método 1 (recomendado)

1. Inicia el Gateway y envía un mensaje directo (DM) al bot.
2. Ejecuta openclaw logs --follow y busca el open_id.

Método 2

Revisa las solicitudes de emparejamiento para encontrar los Open IDs de los usuarios:

openclaw pairing list feishu

---

Comandos comunes

Comando	Descripción
/status	Muestra el estado del bot
/reset	Reinicia la sesión
/model	Muestra o cambia el modelo

Nota: Feishu todavía no soporta menús de comandos nativos, así que los comandos deben enviarse como texto.

Comandos de gestión del Gateway

Comando	Descripción
openclaw gateway status	Muestra el estado del Gateway
openclaw gateway install	Instala o inicia el servicio del Gateway
openclaw gateway stop	Detiene el servicio del Gateway
openclaw gateway restart	Reinicia el servicio del Gateway
openclaw logs --follow	Sigue los logs del Gateway en tiempo real

---

Solución de problemas

El bot no responde en chats grupales

1. Asegúrate de que el bot haya sido añadido al grupo
2. Asegúrate de mencionar al bot con @ (comportamiento por defecto)
3. Revisa que groupPolicy no esté configurado como "disabled"
4. Revisa los logs: openclaw logs --follow

El bot no recibe mensajes

1. Asegúrate de que la app esté publicada y aprobada
2. Asegúrate de que la suscripción a eventos incluya im.message.receive_v1
3. Asegúrate de que la long connection esté activada
4. Asegúrate de que los permisos de la app estén completos
5. Asegúrate de que el Gateway esté corriendo: openclaw gateway status
6. Revisa los logs: openclaw logs --follow

Filtración del App Secret

1. Resetea el App Secret en la Feishu Open Platform
2. Actualiza el App Secret en tu configuración
3. Reinicia el Gateway

Errores al enviar mensajes

1. Asegúrate de que la app tenga el permiso im:message:send_as_bot
2. Asegúrate de que la app esté publicada
3. Revisa los logs para ver errores detallados

Configuración avanzada

Múltiples cuentas

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

defaultAccount controla qué cuenta de Feishu se utiliza cuando las API de salida no especifican un accountId de forma explícita.

Límites de mensajes

• textChunkLimit: tamaño del fragmento de texto de salida (por defecto: 2000 caracteres)
• mediaMaxMb: límite de subida/descarga de archivos multimedia (por defecto: 30MB)

Streaming

Feishu admite respuestas en streaming mediante tarjetas interactivas. Cuando activas esta opción, el bot actualiza una tarjeta a medida que genera el texto.

{
  channels: {
    feishu: {
      streaming: true, // enable streaming card output (default true)
      blockStreaming: true, // enable block-level streaming (default true)
    },
  },
}

Configura streaming: false si prefieres esperar a que la respuesta esté completa antes de enviarla.

Sesiones de ACP

Feishu admite ACP para:

• Mensajes directos (DMs)
• Conversaciones por temas en grupos (group topic conversations)

El ACP en Feishu funciona mediante comandos de texto. No existen menús nativos de slash-commands, así que utiliza mensajes /acp ... directamente en la conversación.

Vinculaciones de ACP persistentes

Usa vinculaciones de ACP tipadas de nivel superior para fijar un DM de Feishu o una conversación por temas a una sesión de ACP persistente.

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "direct", id: "ou_1234567890" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
      },
      acp: { label: "codex-feishu-topic" },
    },
  ],
}

Creación de ACP vinculado al hilo desde el chat

En un DM de Feishu o en una conversación por temas, puedes crear y vincular una sesión de ACP en el momento:

/acp spawn codex --thread here

Notas:

• --thread here funciona para DMs y temas de Feishu.
• Los mensajes de seguimiento en el DM o tema vinculado se dirigen directamente a esa sesión de ACP.
• La v1 no es compatible con grupos genéricos que no sean por temas.

Enrutamiento multi-agente

Utiliza bindings para enrutar DMs o grupos de Feishu a diferentes agentes.

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

Campos de enrutamiento:

• match.channel: "feishu"
• match.peer.kind: "direct" o "group"
• match.peer.id: Open ID del usuario (ou_xxx) o ID del grupo (oc_xxx)

Consulta Obtener IDs de grupo/usuario para ver consejos de búsqueda.

---

Referencia de configuración

Configuración completa: Gateway configuration

Opciones clave:

Ajuste	Descripción	Por defecto
channels.feishu.enabled	Activar/desactivar canal	true
channels.feishu.domain	Dominio de la API (feishu o lark)	feishu
channels.feishu.connectionMode	Modo de transporte de eventos	websocket
channels.feishu.defaultAccount	ID de cuenta por defecto para enrutamiento de salida	default
channels.feishu.verificationToken	Requerido para modo webhook	-
channels.feishu.encryptKey	Requerido para modo webhook	-
channels.feishu.webhookPath	Ruta del webhook	/feishu/events
channels.feishu.webhookHost	Host de escucha del webhook	127.0.0.1
channels.feishu.webhookPort	Puerto de escucha del webhook	3000
channels.feishu.accounts.<id>.appId	App ID	-
channels.feishu.accounts.<id>.appSecret	App Secret	-
channels.feishu.accounts.<id>.domain	Sobrescritura de dominio API por cuenta	feishu
channels.feishu.dmPolicy	Política de mensajes directos (DM)	pairing
channels.feishu.allowFrom	Lista de permitidos para DM (lista de open_id)	-
channels.feishu.groupPolicy	Política de grupo	allowlist
channels.feishu.groupAllowFrom	Lista de permitidos para grupos	-
channels.feishu.requireMention	Requiere mención @ por defecto	condicional
channels.feishu.groups.<chat_id>.requireMention	Sobrescritura de mención @ por grupo	heredado
channels.feishu.groups.<chat_id>.enabled	Activar grupo	true
channels.feishu.textChunkLimit	Tamaño de fragmento de mensaje	2000
channels.feishu.mediaMaxMb	Límite de tamaño de archivos multimedia	30
channels.feishu.streaming	Activar salida de tarjeta en streaming	true
channels.feishu.blockStreaming	Activar streaming por bloques	true

Referencia de dmPolicy

Valor	Comportamiento
"pairing"	Predeterminado. Los usuarios desconocidos reciben un código de vinculación; deben ser aprobados
"allowlist"	Solo los usuarios en allowFrom pueden chatear
"open"	Permite a todos los usuarios (requiere "*" en allowFrom)
"disabled"	Desactiva los DMs

---

Tipos de mensajes soportados

Recibir

• ✅ Texto
• ✅ Texto enriquecido (post)
• ✅ Imágenes
• ✅ Archivos
• ✅ Audio
• ✅ Video/media
• ✅ Stickers

Enviar

• ✅ Texto
• ✅ Imágenes
• ✅ Archivos
• ✅ Audio
• ✅ Video/media
• ✅ Tarjetas interactivas
• ⚠️ Texto enriquecido (formato estilo post y tarjetas, no funciones de autoría arbitrarias de Feishu)

Hilos y respuestas

• ✅ Respuestas en línea
• ✅ Respuestas en hilos de temas donde Feishu expone reply_in_thread
• ✅ Las respuestas multimedia mantienen el contexto del hilo al responder a un mensaje de hilo o tema (thread-aware)

Comentarios en Drive

Feishu puede activar al agente cuando alguien añade un comentario en un documento de Feishu Drive (Docs, Sheets, etc.). El agente recibe el texto del comentario, el contexto del documento y el hilo de comentarios para que pueda responder en el mismo hilo o realizar ediciones en el documento.

Requisitos:

• Suscríbete a drive.notice.comment_add_v1 en la configuración de suscripción de eventos de tu app de Feishu (junto con el ya existente im.message.receive_v1)
• La herramienta Drive está activada por defecto; desactívala con channels.feishu.tools.drive: false

La herramienta feishu_drive expone estas acciones de comentarios:

Action	Description
list_comments	List comments on a document
list_comment_replies	List replies in a comment thread
add_comment	Add a new top-level comment
reply_comment	Reply to an existing comment thread

Cuando el agente gestiona un evento de comentario en Drive, recibe:

• El texto del comentario junto con el remitente y los metadatos del documento (título, tipo, URL)
• El contexto del hilo de comentarios para respuestas internas

Después de realizar ediciones en el documento, el agente recibe instrucciones para usar feishu_drive.reply_comment para notificar a la persona que comentó y luego devolver NO_REPLY para evitar envíos duplicados.

Superficie de acciones en tiempo de ejecución

Feishu expone actualmente estas acciones en tiempo de ejecución:

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• react y reactions cuando las reacciones están activadas en la configuración
• Acciones de comentario de feishu_drive: list_comments, list_comment_replies, add_comment, reply_comment

Relacionado

• Channels Overview — todos los canales soportados
• Pairing — flujo de autenticación y emparejamiento de DM
• Groups — comportamiento de chats grupales y restricciones de menciones
• Channel Routing — enrutamiento de sesiones para mensajes
• Security — modelo de acceso y seguridad

AI Setup Assistant