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 con un bot de Feishu/Lark usando la suscripción de eventos WebSocket de la plataforma, de modo que los mensajes se puedan recibir sin exponer una URL pública de webhook.

Plugin requerido

Instale el plugin de Feishu:

openclaw plugins install @openclaw/feishu

Clonado local (cuando se ejecuta desde un repositorio git):

openclaw plugins install ./extensions/feishu

Inicio rápido

Hay dos formas de agregar el canal de Feishu:

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

Si acaba de instalar OpenClaw, ejecute el asistente:

openclaw onboard

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

Crear una app de Feishu y recopilar credenciales
Configurar las credenciales de la app en OpenClaw
Iniciar el Gateway

✅ Después de la configuración, verifique el estado del Gateway:

openclaw gateway status
openclaw logs --follow

Método 2: configuración por CLI

Si ya completó la instalación inicial, agregue el canal vía CLI:

openclaw channels add

Elija Feishu, luego ingrese el App ID y el App Secret. ✅ Después de la configuración, administre el Gateway:

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

Paso 1: Crear una app de Feishu

1. Abrir Feishu Open Platform

Visite Feishu Open Platform e inicie sesión. Los tenants de Lark (global) deben usar https://open.larksuite.com/app y establecer domain: "lark" en la configuración de Feishu.

2. Crear una app

Haga clic en Create enterprise app
Complete el nombre y la descripción de la app
Elija un icono para la app

3. Copiar credenciales

Desde Credentials & Basic Info, copie:

App ID (formato: cli_xxx)
App Secret

❗ Importante: mantenga el App Secret en privado. Get credentials

4. Configurar permisos

En Permissions, haga clic en Batch import y pegue:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu: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. Habilitar la capacidad de bot

En App Capability > Bot:

Habilite la capacidad de bot
Establezca el nombre del bot

6. Configurar la suscripción de eventos

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

Ya ejecutó openclaw channels add para Feishu
El Gateway está en ejecución (openclaw gateway status)

En Event Subscription:

Elija Use long connection to receive events (WebSocket)
Agregue el evento: im.message.receive_v1

⚠️ Si el Gateway no está en ejecución, la configuración de conexión larga puede no guardarse. Configure event subscription

7. Publicar la app

Cree una versión en Version Management & Release
Envíe a revisión y publique
Espere la aprobación del administrador (las apps empresariales suelen aprobarse automáticamente)

Paso 2: Configurar OpenClaw

Configurar con el asistente (recomendado)

openclaw channels add

Elija Feishu y pegue su App ID y App Secret.

Configurar mediante archivo de configuración

Edite ~/.openclaw/openclaw.json:

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

Configurar mediante variables de entorno

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

Dominio de Lark (global)

Si su tenant está en Lark (internacional), establezca el dominio en lark (o una cadena de dominio completa). Puede configurarlo en channels.feishu.domain o por cuenta (channels.feishu.accounts.<id>.domain).

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

Paso 3: Iniciar y probar

1. Iniciar el Gateway

openclaw gateway

2. Enviar un mensaje de prueba

En Feishu, encuentre su bot y envíe un mensaje.

3. Aprobar el emparejamiento

De forma predeterminada, el bot responde con un código de emparejamiento. Apruébelo:

openclaw pairing approve feishu <CODE>

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

Descripción general

Canal de bot de Feishu: bot de Feishu administrado por el Gateway
Enrutamiento determinista: 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, no se requiere URL pública

Control de acceso

Mensajes directos

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

Aprobar emparejamiento:

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

Modo de lista de permitidos: establezca channels.feishu.allowFrom con los Open ID permitidos

Chats grupales

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

"open" = permitir a todos en grupos (predeterminado)
"allowlist" = permitir solo groupAllowFrom
"disabled" = deshabilitar mensajes de grupos

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

true = requerir @mención (predeterminado)
false = responder sin menciones

Ejemplos de configuración de grupos

Permitir todos los grupos, requerir @mención (predeterminado)

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

Permitir todos los grupos, sin requerir @mención

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

Permitir solo usuarios específicos en grupos

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

Obtener IDs de grupo/usuario

IDs de grupo (chat_id)

Los IDs de grupo se ven como oc_xxx. Método 1 (recomendado)

Inicie el Gateway y @mencione al bot en el grupo
Ejecute openclaw logs --follow y busque chat_id

Método 2 Use el depurador de la API de Feishu para listar los chats de grupo.

IDs de usuario (open_id)

Los IDs de usuario se ven como ou_xxx. Método 1 (recomendado)

Inicie el Gateway y envíe un mensaje directo al bot
Ejecute openclaw logs --follow y busque open_id

Método 2 Revise las solicitudes de emparejamiento para obtener los Open ID de usuario:

openclaw pairing list feishu

Comandos comunes

Comando	Descripción
`/status`	Mostrar estado del bot
`/reset`	Restablecer la sesión
`/model`	Mostrar/cambiar modelo

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

Comando	Descripción
`openclaw gateway status`	Mostrar estado del Gateway
`openclaw gateway install`	Instalar/iniciar el servicio del Gateway
`openclaw gateway stop`	Detener el servicio del Gateway
`openclaw gateway restart`	Reiniciar el servicio del Gateway
`openclaw logs --follow`	Ver logs del Gateway

Solución de problemas

El bot no responde en chats grupales

Asegúrese de que el bot esté agregado al grupo
Asegúrese de @mencionar al bot (comportamiento predeterminado)
Verifique que groupPolicy no esté configurado en "disabled"
Revise los logs: openclaw logs --follow

El bot no recibe mensajes

Asegúrese de que la app esté publicada y aprobada
Asegúrese de que la suscripción de eventos incluya im.message.receive_v1
Asegúrese de que la conexión larga esté habilitada
Asegúrese de que los permisos de la app estén completos
Asegúrese de que el Gateway esté en ejecución: openclaw gateway status
Revise los logs: openclaw logs --follow

Fuga del App Secret

Restablezca el App Secret en Feishu Open Platform
Actualice el App Secret en su configuración
Reinicie el Gateway

Fallos al enviar mensajes

Asegúrese de que la app tenga el permiso im:message:send_as_bot
Asegúrese de que la app esté publicada
Revise los logs para ver errores detallados

Configuración avanzada

Múltiples cuentas

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

Límites de mensajes

textChunkLimit: tamaño del bloque de texto saliente (predeterminado: 2000 caracteres)
mediaMaxMb: límite de carga/descarga de medios (predeterminado: 30 MB)

Streaming

Feishu admite respuestas en streaming mediante tarjetas interactivas. Cuando está habilitado, el bot actualiza una tarjeta a medida que genera texto.

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

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

Enrutamiento multiagente

Use 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" or "group"
match.peer.id: Open ID de usuario (ou_xxx) o ID de grupo (oc_xxx)

Consulte Obtener IDs de grupo/usuario para obtener consejos de búsqueda.

Referencia de configuración

Configuración completa: Configuración del Gateway Opciones clave:

Configuración	Descripción	Predeterminado
`channels.feishu.enabled`	Habilitar/deshabilitar canal	`true`
`channels.feishu.domain`	Dominio de API (`feishu` o `lark`)	`feishu`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	Anulación de dominio de API por cuenta	`feishu`
`channels.feishu.dmPolicy`	Política DM	`pairing`
`channels.feishu.allowFrom`	Lista de permitidos de mensajes directos (lista de open_id)	-
`channels.feishu.groupPolicy`	Política de grupos	`open`
`channels.feishu.groupAllowFrom`	Lista de permitidos de grupos	-
`channels.feishu.groups.<chat_id>.requireMention`	Requerir @mención	`true`
`channels.feishu.groups.<chat_id>.enabled`	Habilitar grupos	`true`
`channels.feishu.textChunkLimit`	Tamaño del bloque de mensajes	`2000`
`channels.feishu.mediaMaxMb`	Límite de tamaño de medios	`30`
`channels.feishu.streaming`	Habilitar salida de tarjeta en streaming	`true`
`channels.feishu.blockStreaming`	Habilitar block streaming	`true`

Referencia de dmPolicy

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

Tipos de mensajes compatibles

Recibir

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

Enviar

✅ Texto
✅ Imágenes
✅ Archivos
✅ Audio
⚠️ Texto enriquecido (soporte parcial)

Resumen

Plataformas de mensajería

Configuración

​Bot de Feishu

​Plugin requerido

​Inicio rápido

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

​Método 2: configuración por CLI

​Paso 1: Crear una app de Feishu

​1. Abrir Feishu Open Platform

​2. Crear una app

​3. Copiar credenciales

​4. Configurar permisos

​5. Habilitar la capacidad de bot

​6. Configurar la suscripción de eventos

​7. Publicar la app

​Paso 2: Configurar OpenClaw

​Configurar con el asistente (recomendado)

​Configurar mediante archivo de configuración

​Configurar mediante variables de entorno

​Dominio de Lark (global)

​Paso 3: Iniciar y probar

​1. Iniciar el Gateway

​2. Enviar un mensaje de prueba

​3. Aprobar el emparejamiento

​Descripción general

​Control de acceso

​Mensajes directos

​Chats grupales

​Ejemplos de configuración de grupos

​Permitir todos los grupos, requerir @mención (predeterminado)

​Permitir todos los grupos, sin requerir @mención

​Permitir solo usuarios específicos en grupos

​Obtener IDs de grupo/usuario

​IDs de grupo (chat_id)

​IDs de usuario (open_id)

​Comandos comunes

​Comandos de gestión del Gateway

​Solución de problemas

​El bot no responde en chats grupales

​El bot no recibe mensajes

​Fuga del App Secret

​Fallos al enviar mensajes

​Configuración avanzada

​Múltiples cuentas

​Límites de mensajes

​Streaming

​Enrutamiento multiagente

​Referencia de configuración

​Referencia de dmPolicy

​Tipos de mensajes compatibles

​Recibir

​Enviar