Bot de Feishu

Feishu (Lark) es una plataforma de chat de equipo utilizada por empresas para mensajería y colaboración. Este plugin conecta OpenClaw a un bot de Feishu/Lark usando la suscripción de eventos por WebSocket de la plataforma, de modo que los mensajes se reciben sin necesidad de exponer una URL de webhook pública.

Plugin incluido

Feishu viene incluido en las versiones actuales de OpenClaw, por lo que no se requiere una instalación de plugin separada.

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

openclaw plugins install @openclaw/feishu

Inicio rápido

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

Método 1: asistente de configuración (recomendado)

Si acabas de instalar OpenClaw, ejecuta el asistente:

openclaw onboard

El asistente te guía a través de:

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

Después de la configuración, verifica 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 por CLI:

openclaw channels add

Elige Feishu, luego introduce el App ID y el App Secret.

Después de la configuración, gestiona el gateway:

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

Paso 1: Crear una app de Feishu

1. Abre Feishu Open Platform

Visita Feishu Open Platform e inicia sesión.

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

2. Crea una app

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

3. Copia las credenciales

Desde Credentials & Basic Info, copia:

• App ID (formato: cli_xxx)
• App Secret

Advertencia: mantén el App Secret privado.

4. Configura los permisos

En Permissions, haz clic en Batch import y pega:

{
  "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 capacidad de bot

En App Capability > Bot:

1. Activa la capacidad de bot
2. Establece el nombre del bot

6. Configura la suscripción de eventos

Advertencia: antes de configurar la suscripción de eventos, asegúrate de que:

1. Ya ejecutaste openclaw channels add para Feishu
2. El gateway está en ejecución (openclaw gateway status)

En Event Subscription:

1. Elige Use long connection to receive events (WebSocket)
2. Añade el evento: im.message.receive_v1

Advertencia: Si el gateway no está en ejecución, la configuración de conexión larga puede no guardarse.

7. Publica la app

1. Crea una versión en Version Management & Release
2. Envía para revisión y publica
3. Espera la aprobación del administrador (las apps empresariales suelen auto-aprobarse)

Paso 2: Configura OpenClaw

Configurar con el asistente (recomendado)

openclaw channels add

Elige Feishu y pega tu App ID + App Secret.

Configurar por archivo de configuración

Edita ~/.openclaw/openclaw.json:

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

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

Verification Token y Encrypt Key (modo webhook)

Cuando uses el modo webhook, establece tanto channels.feishu.verificationToken como channels.feishu.encryptKey en tu configuración. 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 Verification Token y Encrypt Key

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

Configurar por variables de entorno

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

Dominio Lark (global)

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

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

Indicadores de optimización de cuota

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

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

Establécelos a nivel superior o por cuenta:

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

Paso 3: Inicia + prueba

1. Inicia el gateway

openclaw gateway

2. Envía un mensaje de prueba

En Feishu, busca tu bot y envía 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 con normalidad.

Descripción general

• Canal de bot Feishu: bot Feishu gestionado por el gateway
• Enrutamiento determinístico: las respuestas siempre regresan a Feishu
• Aislamiento de sesiones: los mensajes directos comparten una sesión principal; los grupos están aislados
• Conexión WebSocket: conexión larga vía SDK de Feishu, sin necesidad de 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 de permitidos: establece channels.feishu.allowFrom con los Open IDs permitidos

Chats de grupo

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

• "open" = permitir a todos en grupos (por defecto)
• "allowlist" = solo permitir groupAllowFrom
• "disabled" = desactivar mensajes de grupo

2. Requisito de mención (channels.feishu.groups.<chat_id>.requireMention):

• true = requiere @mención (por defecto)
• false = responder sin menciones

Ejemplos de configuración de grupo

Permitir todos los grupos, requiere @mención (por defecto)

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

Permitir todos los grupos, sin @mención requerida

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

Permitir solo grupos específicos

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Los IDs de grupo de Feishu (chat_id) son como: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Restringir qué remitentes pueden enviar mensajes en un grupo (lista de permitidos por remitente)

Además de permitir el grupo en sí, todos los mensajes en ese grupo están controlados 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 control total a nivel de remitente, no solo para comandos de control como /reset o /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Los IDs de usuario de Feishu (open_id) son como: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Obtener IDs de grupo/usuario

IDs de grupo (chat_id)

Los IDs de grupo son como oc_xxx.

Método 1 (recomendado)

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

Método 2

Usa el depurador de API de Feishu para listar los chats de grupo.

IDs de usuario (open_id)

Los IDs de usuario son como ou_xxx.

Método 1 (recomendado)

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

Método 2

Revisa las solicitudes de emparejamiento para los Open IDs de usuario:

openclaw pairing list feishu

Comandos comunes

Nota: Feishu aún no admite menús de comandos nativos, por lo que los comandos deben enviarse como texto.

Comandos de gestión del gateway

Solución de problemas

El bot no responde en chats de grupo

1. Asegúrate de que el bot esté añadido al grupo
2. Asegúrate de @mencionar al bot (comportamiento por defecto)
3. Verifica que groupPolicy no esté establecido en "disabled"
4. Revisa los registros: 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 de eventos incluya im.message.receive_v1
3. Asegúrate de que la conexión larga esté activada
4. Asegúrate de que los permisos de la app estén completos
5. Asegúrate de que el gateway esté en ejecución: openclaw gateway status
6. Revisa los registros: openclaw logs --follow

Filtración del App Secret

1. Restablece el App Secret en Feishu Open Platform
2. Actualiza el App Secret en tu configuración
3. Reinicia el gateway

Fallos en el envío de 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 registros para errores detallados

Configuración avanzada

Múltiples cuentas

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

defaultAccount controla qué cuenta de Feishu se usa cuando las API salientes no especifican un accountId explícitamente.

Límites de mensajes

• textChunkLimit: tamaño del fragmento de texto saliente (por defecto: 2000 caracteres)
• mediaMaxMb: límite de carga/descarga de medios (por defecto: 30MB)

Streaming

Feishu admite respuestas en streaming a través de tarjetas interactivas. Cuando está activado, el bot actualiza una tarjeta a medida que genera texto.

{
  channels: {
    feishu: {
      streaming: true, // activar salida de tarjeta en streaming (por defecto true)
      blockStreaming: true, // activar streaming a nivel de bloque (por defecto true)
    },
  },
}

Establece streaming: false para esperar la respuesta completa antes de enviar.

Enrutamiento multiagente

Usa bindings para enrutar mensajes directos 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 consejos de búsqueda.

Referencia de configuración

Configuración completa: Configuración del gateway

Opciones clave:

Referencia de dmPolicy

Tipos de mensaje compatibles

Recepción

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

Envío

• Texto
• Imágenes
• Archivos
• Audio
• Texto enriquecido (soporte parcial)