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 para documentos/wiki/drive/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

Control de acceso

Mensajes directos

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

Aprobar una solicitud de emparejamiento:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Chats grupales

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

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

• Predeterminado: se requiere @mención, excepto cuando la política de grupo efectiva es "open"; ahí el valor predeterminado es false para que los mensajes que no pueden llevar menciones (por ejemplo, imágenes) aun lleguen al agente.
• Establécelo explícitamente en true o false para anularlo; anulación por grupo: channels.feishu.groups.<chat_id>.requireMention.
• Los mensajes de difusión @all y @_all no se tratan como menciones al bot. Un mensaje que menciona tanto a @all como al bot directamente sigue contando como 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, pero 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 modo allowlist, también puedes admitir un grupo agregando una entrada explícita groups.<chat_id>. Las entradas explícitas no anulan groupPolicy: "disabled". Los valores predeterminados con comodín en 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 permitidos de remitentes para todos los grupos; un allowFrom por grupo tiene prioridad.

Obtener IDs de grupo/usuario

IDs de grupo (chat_id, formato: oc_xxx)

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

IDs de usuario (open_id, formato: ou_xxx)

Inicia el gateway, envía un mensaje directo al bot y luego revisa los registros:

openclaw logs --follow

Busca open_id en la salida del registro. También puedes revisar las solicitudes de emparejamiento pendientes:

openclaw pairing list feishu

Comandos comunes

Solución de problemas

El bot no responde en chats grupales

1. Asegúrate de que el bot esté agregado al grupo
2. Asegúrate de @mencionar al bot (requerido de forma predeterminada)
3. Verifica que groupPolicy no sea "disabled"
4. Revisa los registros: openclaw logs --follow

El bot no recibe mensajes

1. Asegúrate de que el bot esté publicado y aprobado en Feishu Open Platform / Lark Developer
2. Asegúrate de que la suscripción a eventos incluya im.message.receive_v1
3. Asegúrate de que esté seleccionada la conexión persistente (WebSocket)
4. Asegúrate de que todos los ámbitos de permiso requeridos estén concedidos
5. Asegúrate de que el gateway esté en ejecución: openclaw gateway status
6. Revisa los registros: openclaw logs --follow

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

1. Vuelve a ejecutar la configuración: openclaw channels login --channel feishu
2. Elige la configuración manual
3. En Feishu Open Platform, crea una aplicación autoconstruida y copia su App ID y App Secret
4. Pega esas credenciales en el asistente de configuración

Se filtró el App Secret

1. Restablece el App Secret en Feishu Open Platform / Lark Developer
2. Actualiza el valor en tu configuración
3. Reinicia 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 usa cuando las API salientes 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 usa la misma forma que messages.tts y se fusiona en profundidad sobre la configuración TTS global, por lo que las configuraciones de Feishu con varios bots pueden mantener credenciales de proveedor compartidas globalmente mientras anulan solo voz, modelo, persona o modo automático por cuenta.

Límites de mensajes

• textChunkLimit - tamaño de fragmento de texto saliente (predeterminado: 4000 caracteres)
• chunkMode - "length" (predeterminado) divide en el límite; "newline" prefiere límites de salto de línea
• mediaMaxMb - límite de carga/descarga de medios (predeterminado: 30 MB)

Streaming

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

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

Establece streaming: false 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. blockStreaming está desactivado de forma predeterminada; actívalo solo cuando quieras que los bloques completados del asistente se envíen antes de la respuesta final.

Optimización de cuota

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

• typingIndicator (predeterminado true): establece false para omitir las llamadas de reacción de escritura
• resolveSenderNames (predeterminado true): establece false para omitir las búsquedas de perfiles de remitentes

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

Alcance de sesión de grupo e hilos de temas

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

Para los alcances de tema, los grupos de temas nativos de Feishu/Lark usan el thread_id del evento (omt_*) como clave canónica de sesión de tema. Si un evento iniciador de tema nativo omite thread_id, OpenClaw lo hidrata desde Feishu antes de enrutar el turno. Las respuestas normales de grupo que OpenClaw convierte en hilos siguen usando el ID del mensaje raíz de respuesta (om_*) para que el primer turno y los turnos de seguimiento permanezcan en la misma sesión.

Establece replyInThread: "enabled" (nivel superior o por grupo) para hacer que las respuestas del bot creen o continúen un hilo de tema de Feishu en lugar de responder en línea. topicSessionMode es el predecesor obsoleto de groupSessionScope; prefiere groupSessionScope.

Herramientas de 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 Skills correspondientes (feishu-doc, feishu-drive, feishu-perm, feishu-wiki). Las familias de herramientas están controladas por channels.feishu.tools:

tools.base es un alias de tools.bitable; el valor explícito de bitable tiene prioridad cuando ambos están establecidos. Las compuertas por cuenta están en accounts.<id>.tools.

Sesiones ACP

Feishu/Lark admite ACP para mensajes directos y mensajes en hilos grupales. ACP de Feishu/Lark se controla mediante comandos de texto: no hay menús nativos de comandos con barra, así que usa mensajes /acp ... directamente en la conversación.

Vinculación 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" },    },  ],}

Iniciar ACP desde el chat

En un DM o hilo de Feishu/Lark:

/acp spawn codex --thread here

--thread here funciona para DMs y mensajes de hilo de Feishu/Lark. Los mensajes de seguimiento en la conversación vinculada se enrutan directamente a esa sesión ACP.

Enrutamiento multiagente

Usa bindings para enrutar DMs 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" (DM) o "group" (chat de grupo)
• match.peer.id: Open ID del usuario (ou_xxx) o ID de grupo (oc_xxx)

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

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

Habilita dynamicAgentCreation para crear automáticamente instancias de agente aisladas para cada usuario de DM. Cada usuario obtiene su propio:

• Directorio de workspace independiente
• USER.md / SOUL.md / MEMORY.md separados
• Historial de conversación privado
• Skills y estado aislados

Esto es esencial para bots públicos en los que quieres que cada usuario tenga su propia experiencia privada de 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: {    // Critical: makes each user's DM their "main session"    // Automatically loads USER.md / SOUL.md / MEMORY.md    // For stronger isolation, use "per-channel-peer" instead    dmScope: "main",  },}

Cómo funciona

Cuando un usuario nuevo envía su primer DM:

1. El canal genera un agentId único: feishu-{user_open_id} para la cuenta predeterminada, o un resumen de identidad acotado con prefijo de cuenta para una cuenta con nombre
2. Crea un nuevo workspace en la ruta workspaceTemplate
3. Registra el agente y crea una vinculación para este usuario
4. El ayudante del workspace garantiza 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 de 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 sesión

session.dmScope controla cómo se asignan los mensajes directos a sesiones de agente. Esta es una configuración global que afecta a todos los canales.

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

Despliegue multiusuario típico

{  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: {    // Choose dmScope based on your isolation needs:    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation    dmScope: "main",  },  bindings: [], // Empty - dynamic agents auto-bind}

Verificación

Revisa los registros del gateway para confirmar que la creación dinámica funciona:

feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxx  workspace: /home/user/.openclaw/workspace-feishu-ou_xxxxxx  agentDir: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

Lista todos los workspaces creados:

ls -la ~/.openclaw/workspace-*

Notas

• Aislamiento del workspace: Cada usuario obtiene su propio directorio de workspace e instancia de agente. Los usuarios no pueden ver el historial de conversación ni los archivos de otros usuarios dentro del flujo normal de mensajería.
• Límite de seguridad: Este es un mecanismo de aislamiento de contexto de mensajería, no un límite de seguridad frente a coarrendatarios 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 agentes y vinculaciones en la configuración; se omite cuando channels.feishu.configWrites es false (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 de Gateway

Tipos de mensaje admitidos

Recibir

• ✅ Texto
• ✅ Texto enriquecido (post)
• ✅ Imágenes
• ✅ Archivos
• ✅ Audio
• ✅ Vídeo/medios
• ✅ Stickers

Los mensajes de audio entrantes de Feishu/Lark se normalizan como marcadores de posición de medios en lugar de JSON file_key sin procesar. Cuando tools.media.audio está configurado, OpenClaw descarga el recurso de 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 hablada. Si Feishu incluye texto de transcripción directamente en la carga útil de audio, ese texto se usa sin otra llamada de ASR. Sin un proveedor de transcripción de audio, el agente sigue recibiendo un marcador de posición <media:audio> más el adjunto guardado, no la carga útil del recurso de Feishu sin procesar.

Enviar

• ✅ Texto
• ✅ Imágenes
• ✅ Archivos
• ✅ Audio
• ✅ Vídeo/medios
• ✅ Tarjetas interactivas (incluidas actualizaciones en streaming)
• ⚠️ Texto enriquecido (formato de estilo post; no admite todas las capacidades de autoría de Feishu/Lark)

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

Hilos y respuestas

• ✅ Respuestas en línea
• ✅ Respuestas en hilos
• ✅ Las respuestas con medios siguen teniendo en cuenta el hilo al responder a un mensaje de hilo

El enrutamiento de sesiones de grupos por tema se cubre en Alcance de sesión de grupo e hilos de tema.

Relacionado

• Resumen de canales - todos los canales admitidos
• Emparejamiento - autenticación de DM y flujo de emparejamiento
• Grupos - comportamiento de chats grupales y control de menciones
• Enrutamiento de canales - enrutamiento de sesión para mensajes
• Seguridad - modelo de acceso y refuerzo de seguridad