Feishu

OpenClaw se conecta a Feishu/Lark (la plataforma de colaboración todo en uno) mediante el Plugin oficial @openclaw/feishu: mensajes directos del bot, chats grupales, respuestas de tarjetas en streaming y herramientas de documentos, wikis, unidades y Bitable de Feishu.

Estado: listo para producción para mensajes directos del bot y chats grupales. WebSocket es el transporte de eventos predeterminado (no se necesita una URL pública); el modo Webhook es opcional.

Inicio rápido

openclaw channels login --channel feishu

openclaw gateway restart

Durabilidad de entradas

OpenClaw pone de forma duradera en cola los sobres autenticados im.message.receive_v1 y drive.notice.comment_add_v1 antes de enviarlos al agente. Los eventos pendientes o reintentables sobreviven a un reinicio del Gateway, permanecen serializados por chat o documento y utilizan el ID de evento de Feishu para evitar entradas duplicadas en la cola mientras exista el registro de finalización activo o conservado.

Si no se puede conservar un evento de WebSocket después de un número limitado de reintentos, OpenClaw cierra ese socket y fuerza una nueva conexión autenticada en lugar de continuar después de un turno no confirmado. Otros tipos de eventos de Feishu, incluidas las reacciones y las invitaciones a reuniones de VC, utilizan sus rutas de eventos normales y no reciben esta garantía de cola duradera.

Control de acceso

Mensajes directos

Configure channels.feishu.dmPolicy (valor predeterminado: pairing) para controlar quién puede enviar mensajes directos al bot:

Aprobar una solicitud de vinculación:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Chats grupales

Política de grupos (channels.feishu.groupPolicy, valor predeterminado: allowlist):

Requisito de mención (channels.feishu.requireMention):

• Valor predeterminado: se requiere una @mención, excepto cuando la política de grupos efectiva es "open"; en ese caso, el valor predeterminado es false para que los mensajes que no pueden incluir menciones (por ejemplo, las imágenes) sigan llegando al agente.
• Establezca explícitamente true o false para anularlo; anulación por grupo: channels.feishu.groups.<chat_id>.requireMention.
• Las menciones solo para difusión @all y @_all no se consideran menciones al bot. Un mensaje que mencione tanto @all como directamente al bot sigue contando como una mención al bot.

Ejemplos de configuración de grupos

Permitir todos los grupos sin requerir @mención

{  channels: {    feishu: {      groupPolicy: "open", // requireMention defaults to false under "open"    },  },}

Permitir todos los grupos y seguir requiriendo @mención

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

Permitir solo grupos específicos

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Group IDs look like: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

En el modo allowlist, también se puede admitir un grupo añadiendo una entrada explícita de groups.<chat_id>. Las entradas explícitas no anulan groupPolicy: "disabled". Los valores predeterminados con comodín de groups.* configuran los grupos coincidentes, pero no admiten grupos por sí solos.

{  channels: {    feishu: {      groupPolicy: "allowlist",      groups: {        oc_xxx: {          requireMention: false,        },      },    },  },}

Restringir remitentes dentro de un grupo

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // User open_ids look like: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

channels.feishu.groupSenderAllowFrom establece la misma lista de remitentes permitidos para todos los grupos; un valor allowFrom por grupo tiene prioridad.

Mensajes escritos por bots

Feishu ignora de forma predeterminada los mensajes escritos por otros bots. Para permitir conversaciones grupales entre bots, conceda a la aplicación los ámbitos im:message.group_at_msg.include_bot:readonly y im:message:readonly y, a continuación, establezca allowBots:

{  channels: {    feishu: {      allowBots: true,    },  },}

Feishu solo entrega eventos grupales escritos por bots cuando otro bot menciona a este bot. Se siguen aplicando la política de grupos existente, las listas de remitentes permitidos y los requisitos de mención. OpenClaw descarta los mensajes escritos por sí mismo, menciona al bot homólogo en cada respuesta de texto o tarjeta y aplica la protección compartida channels.defaults.botLoopProtection.

Obtener los ID de grupos y usuarios

ID de grupos (chat_id, formato: oc_xxx)

Abra el grupo en Feishu/Lark, haga clic en el icono de menú de la esquina superior derecha y vaya a Settings. El ID del grupo (chat_id) aparece en la página de configuración.

ID de usuarios (open_id, formato: ou_xxx)

Inicie el Gateway, envíe un mensaje directo al bot y consulte los registros:

openclaw logs --follow

Busque open_id en la salida del registro. También se pueden consultar las solicitudes de vinculación pendientes:

openclaw pairing list feishu

Comandos habituales

Solución de problemas

El bot no responde en los chats grupales

1. Asegúrese de que el bot esté añadido al grupo
2. Asegúrese de @mencionar al bot (se requiere de forma predeterminada)
3. Compruebe que groupPolicy no sea "disabled"
4. Consulte los registros: openclaw logs --follow

El bot no recibe mensajes

1. Asegúrese de que el bot esté publicado y aprobado en Feishu Open Platform / Lark Developer
2. Asegúrese de que la suscripción de eventos incluya im.message.receive_v1
3. Para la incorporación automática a invitaciones de reuniones, suscríbase también a vc.bot.meeting_invited_v1
4. Asegúrese de que esté seleccionada la persistent connection (WebSocket)
5. Asegúrese de que se hayan concedido todos los ámbitos de permisos necesarios
6. Asegúrese de que el Gateway esté en ejecución: openclaw gateway status
7. Consulte los registros: openclaw logs --follow

Suscribirse a vc.bot.meeting_invited_v1 solo entrega el evento. Las incorporaciones automáticas están desactivadas de forma predeterminada. Para habilitarlas globalmente:

{  channels: {    feishu: {      vcAutoJoin: true,    },  },}

Para habilitarlas solo en una cuenta, omita el conmutador de nivel superior y establezca la anulación de la cuenta:

{  channels: {    feishu: {      accounts: {        meetings: { vcAutoJoin: true },      },    },  },}

Los remitentes de invitaciones siguen pasando por la política normal de mensajes directos de Feishu, la lista de permitidos o vinculación, la sesión y el enrutamiento de respuestas antes de que el agente reciba un turno de incorporación. La incorporación también requiere una herramienta disponible para unirse a VC de Feishu configurada para la identidad de la aplicación con el ámbito vc:meeting.bot.join:write. Por ejemplo, la Skills oficial lark-cli del agente de VC proporciona vc +meeting-join.

La configuración mediante QR no reacciona en la aplicación móvil Feishu

1. Vuelva a ejecutar la configuración: openclaw channels login --channel feishu
2. Elija la configuración manual
3. En Feishu Open Platform, cree una aplicación propia y copie su App ID y App Secret
4. Pegue esas credenciales en el asistente de configuración

Se ha filtrado el App Secret

1. Restablezca el App Secret en Feishu Open Platform / Lark Developer
2. Actualice el valor en la configuración
3. Reinicie el Gateway: openclaw gateway restart

Configuración avanzada

Varias cuentas

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

defaultAccount controla qué cuenta se utiliza cuando las API de salida no especifican un accountId. Las entradas de cuenta heredan la configuración de nivel superior; la mayoría de las claves de nivel superior se pueden anular por cuenta. accounts.<id>.tts utiliza la misma estructura que tts y se combina en profundidad con la configuración global de TTS, por lo que las configuraciones de Feishu con varios bots pueden mantener globalmente las credenciales compartidas del proveedor y anular solo la voz, el modelo, la personalidad o el modo automático por cuenta.

Límites de mensajes

• textChunkLimit - tamaño de los fragmentos de texto saliente (valor predeterminado: 4000 caracteres)
• streaming.chunkMode - "length" (valor predeterminado) divide al alcanzar el límite; "newline" da prioridad a los límites de línea nueva
• mediaMaxMb - límite de carga y descarga de contenido multimedia (valor predeterminado: 30 MB)

Streaming

Feishu/Lark admite respuestas en streaming mediante tarjetas interactivas (API de streaming de Card Kit). Cuando está habilitado, el bot actualiza la tarjeta en tiempo real a medida que genera texto.

{  channels: {    feishu: {      streaming: {        mode: "partial", // streaming card output (default: "partial")        block: { enabled: true }, // opt into completed-block streaming      },    },  },}

Configura streaming.mode: "off" para enviar la respuesta completa en un solo mensaje; renderMode: "raw" (texto sin formato en lugar de tarjetas) también desactiva las tarjetas en streaming. streaming.block.enabled está desactivado de forma predeterminada; actívalo solo cuando quieras que los bloques completados del asistente se envíen antes de la respuesta final. El booleano heredado streaming y las claves planas blockStreaming / blockStreamingCoalesce / chunkMode se migran a esta estructura anidada mediante openclaw doctor --fix.

Optimización de la cuota

Reduce el número de llamadas a la API de Feishu/Lark con dos indicadores opcionales:

• typingIndicator (valor predeterminado: true): configura false para omitir las llamadas de reacción de escritura
• resolveSenderNames (valor predeterminado: true): configura false para omitir las consultas de perfiles de remitentes

{  channels: {    feishu: {      typingIndicator: false,      resolveSenderNames: false,    },  },}

Ámbito de las sesiones de grupo e hilos temáticos

channels.feishu.groupSessionScope (en el nivel superior, por cuenta o por grupo) controla cómo se asignan los mensajes de grupo a las sesiones de agentes:

Para los ámbitos temáticos, los grupos temáticos nativos de Feishu/Lark utilizan el evento thread_id (omt_*) como clave canónica de la sesión del tema. Si un evento nativo que inicia un tema omite thread_id, OpenClaw lo obtiene de Feishu antes de enrutar el turno. Las respuestas normales de grupo que OpenClaw convierte en hilos siguen utilizando el ID del mensaje raíz de la respuesta (om_*) para que el primer turno y los turnos posteriores permanezcan en la misma sesión.

Configura replyInThread: "enabled" (en el nivel superior o por grupo) para que las respuestas del bot creen o continúen un hilo temático de Feishu en lugar de responder en línea. topicSessionMode es el predecesor obsoleto de groupSessionScope; se recomienda usar groupSessionScope.

Herramientas del espacio de trabajo de Feishu

El plugin incluye herramientas de agente para documentos, chats, base de conocimientos, almacenamiento en la nube, permisos y Bitable de Feishu, además de las Skills correspondientes (feishu-doc, feishu-drive, feishu-perm, feishu-wiki). Las familias de herramientas se controlan mediante channels.feishu.tools:

tools.base es un alias de tools.bitable; el valor explícito de bitable tiene prioridad cuando ambos están configurados. Los controles por cuenta se encuentran en accounts.<id>.tools.

Concede drive:drive.metadata:readonly para realizar consultas directas de feishu_drive info fuera del directorio raíz, a menos que la aplicación ya tenga el ámbito completo drive:drive. Sin ninguno de estos ámbitos, info mantiene disponible la consulta heredada del directorio raíz mediante drive:drive:readonly.

Sesiones ACP

Feishu/Lark admite ACP para mensajes directos y mensajes de hilos de grupo. ACP de Feishu/Lark se controla mediante comandos de texto; no hay menús nativos de comandos con barra, por lo que se deben utilizar mensajes /acp ... directamente en la conversación.

Vinculación persistente de ACP

{  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" },    },  ],}

Iniciar ACP desde el chat

En un mensaje directo o hilo de Feishu/Lark:

/acp spawn codex --thread here

--thread here funciona para mensajes directos y mensajes de hilos de Feishu/Lark. Los mensajes posteriores de la conversación vinculada se enrutan directamente a esa sesión ACP.

Enrutamiento multiagente

Utiliza bindings para enrutar mensajes directos o grupos de Feishu/Lark a distintos agentes.

{  agents: {    list: [      { id: "main" },      { id: "agent-a", workspace: "/home/user/agent-a" },      { id: "agent-b", workspace: "/home/user/agent-b" },    ],  },  bindings: [    {      agentId: "agent-a",      match: {        channel: "feishu",        peer: { kind: "direct", id: "ou_xxx" },      },    },    {      agentId: "agent-b",      match: {        channel: "feishu",        peer: { kind: "group", id: "oc_zzz" },      },    },  ],}

Campos de enrutamiento:

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

Consulta Obtener ID de grupos/usuarios para ver consejos sobre cómo encontrarlos.

Aislamiento de agentes por usuario (creación dinámica de agentes)

Activa dynamicAgentCreation para crear automáticamente instancias de agentes aisladas para cada usuario de mensajes directos. Cada usuario obtiene sus propios elementos:

• Directorio de espacio de trabajo independiente
• USER.md / SOUL.md / MEMORY.md separados
• Historial privado de conversaciones
• Skills y estado aislados

Esto es esencial para bots públicos cuando se desea que cada usuario tenga su propia experiencia privada con un asistente de IA.

Configuración rápida

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Crítico: convierte el mensaje directo de cada usuario en su "sesión principal"    // Carga automáticamente USER.md / SOUL.md / MEMORY.md    // Para un aislamiento más estricto, utiliza "per-channel-peer" en su lugar    dmScope: "main",  },}

Cómo funciona

Cuando un usuario nuevo envía su primer mensaje directo:

1. El canal genera un agentId único: feishu-{user_open_id} para la cuenta predeterminada, o un resumen de identidad acotado con el prefijo de la cuenta para una cuenta con nombre
2. Crea un nuevo espacio de trabajo en la ruta workspaceTemplate
3. Registra el agente y crea una vinculación para este usuario
4. El asistente del espacio de trabajo garantiza la presencia de los archivos de arranque (AGENTS.md, SOUL.md, USER.md, etc.) en el primer acceso
5. Enruta todos los mensajes futuros de este usuario a su agente dedicado

Opciones de configuración

Variables de plantilla:

• {agentId} - el ID del agente generado (por ejemplo, feishu-ou_xxxxxx o feishu-support-<identity_digest>)
• {userId} - el open_id de Feishu del remitente (por ejemplo, ou_xxxxxx)

Ámbito de las sesiones

session.dmScope controla cómo se asignan los mensajes directos a las sesiones de agentes. Es una configuración global que afecta a todos los canales.

Compensación: utilizar "main" activa la carga automática de archivos de arranque (USER.md, SOUL.md, MEMORY.md), pero significa que todos los mensajes directos de todos los canales comparten el mismo patrón de clave de sesión. Para bots públicos multiusuario en los que el aislamiento es más importante que la carga automática de archivos de arranque, considera "per-channel-peer" y administra manualmente los archivos de arranque.

Implementación multiusuario típica

{  channels: {    feishu: {      appId: "cli_xxx",      appSecret: "xxx",      dmPolicy: "open",      allowFrom: ["*"],      groupPolicy: "open",      requireMention: true,      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Elige dmScope en función de tus necesidades de aislamiento:    // "main" para la carga automática de archivos de arranque, "per-channel-peer" para un aislamiento más estricto    dmScope: "main",  },  bindings: [], // Vacío: los agentes dinámicos se vinculan automáticamente}

Verificación

Comprueba los registros del Gateway para confirmar que la creación dinámica funciona:

feishu: creando el agente dinámico "feishu-ou_xxxxxx" para el usuario ou_xxxxxx  espacio de trabajo: /home/user/.openclaw/workspace-feishu-ou_xxxxxx  agentDir: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

Enumere todos los espacios de trabajo creados:

ls -la ~/.openclaw/workspace-*

Notas

• Aislamiento de espacios de trabajo: Cada usuario obtiene su propio directorio de espacio de trabajo y su propia instancia de agente. Los usuarios no pueden ver el historial de conversaciones ni los archivos de otros usuarios dentro del flujo normal de mensajería.
• Límite de seguridad: Este es un mecanismo de aislamiento del contexto de mensajería, no un límite de seguridad frente a coinquilinos hostiles. El proceso del agente y el entorno del host son compartidos.
• Las escrituras de configuración deben permanecer habilitadas: La creación dinámica de agentes escribe los agentes y las vinculaciones en la configuración; se omite cuando channels.feishu.configWrites es false (valor predeterminado: habilitado).
• bindings debe estar vacío: Los agentes dinámicos registran automáticamente sus propias vinculaciones
• Ruta de actualización: Las vinculaciones manuales existentes siguen funcionando junto con los agentes dinámicos
• session.dmScope es global: Esto afecta a todos los canales, no solo a Feishu

Referencia de configuración

Configuración completa: Configuración del Gateway

Tipos de mensajes compatibles

Recepción

• ✅ Texto
• ✅ Texto enriquecido (publicación)
• ✅ Imágenes
• ✅ Archivos
• ✅ Audio
• ✅ Vídeo/multimedia
• ✅ Adhesivos

Los mensajes de audio entrantes de Feishu/Lark se normalizan como marcadores de posición multimedia en lugar de JSON file_key sin procesar. Cuando se configura tools.media.audio, OpenClaw descarga el recurso de la nota de voz y ejecuta la transcripción de audio compartida antes del turno del agente, de modo que el agente recibe la transcripción de lo hablado. Si Feishu incluye el texto de la transcripción directamente en la carga útil de audio, se utiliza ese texto sin otra llamada de ASR. Sin un proveedor de transcripción de audio, el agente sigue recibiendo un marcador de posición <media:audio> junto con el archivo adjunto guardado, no la carga útil del recurso de Feishu sin procesar.

Envío

• ✅ Texto
• ✅ Imágenes
• ✅ Archivos
• ✅ Audio
• ✅ Vídeo/multimedia
• ✅ Tarjetas interactivas (incluidas las actualizaciones en streaming)
• ⚠️ Texto enriquecido (formato de estilo publicación; no admite todas las capacidades de creación de contenido de Feishu/Lark)

Las burbujas de audio nativas de Feishu/Lark usan el tipo de mensaje audio de Feishu y requieren contenido multimedia de carga Ogg/Opus (file_type: "opus"). El contenido multimedia .opus y .ogg existente se envía directamente como audio nativo. MP3/WAV/M4A y otros formatos que probablemente sean de audio se transcodifican a Ogg/Opus de 48 kHz con ffmpeg solo cuando la respuesta solicita la entrega por voz (audioAsVoice / herramienta de mensajes asVoice, incluidas las respuestas TTS como notas de voz). Los archivos adjuntos MP3 normales siguen siendo archivos convencionales. Si falta ffmpeg o falla la conversión, OpenClaw recurre a un archivo adjunto y registra el motivo.

Hilos y respuestas

• ✅ Respuestas en línea
• ✅ Respuestas en hilos
• ✅ Las respuestas con contenido multimedia conservan el contexto del hilo al responder a un mensaje de un hilo

El enrutamiento de sesiones de grupos temáticos se describe en Ámbito de las sesiones de grupo e hilos temáticos.

Contenido relacionado

• Descripción general de los canales - todos los canales compatibles
• Emparejamiento - autenticación por mensaje directo y flujo de emparejamiento
• Grupos - comportamiento del chat grupal y restricción mediante menciones
• Enrutamiento de canales - enrutamiento de sesiones para mensajes
• Seguridad - modelo de acceso y refuerzo de la seguridad