Feishu

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

Estado: listo para producción con mensajes directos al 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

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 grupo 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 @all y @_all, destinadas únicamente a difusiones, no se consideran menciones al bot. Un mensaje que menciona tanto a @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, 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 el modo allowlist, también puede admitir un grupo añadiendo 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 los admiten por sí solos.

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

Restringir los 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.

Obtener los ID de grupos y usuarios

ID de grupo (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 usuario (open_id, formato: ou_xxx)

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

openclaw logs --follow

Busque open_id en la salida del registro. También puede 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 se haya añadido al grupo
2. Asegúrese de incluir una @mención al bot (obligatoria 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 a eventos incluya im.message.receive_v1
3. Asegúrese de que esté seleccionada la opción persistent connection (WebSocket)
4. Asegúrese de que se hayan concedido todos los ámbitos de permisos necesarios
5. Asegúrese de que el Gateway esté en ejecución: openclaw gateway status
6. Consulte los registros: openclaw logs --follow

La configuración mediante QR no reacciona en la aplicación móvil de 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 su 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 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 pueden anularse para cada cuenta. accounts.<id>.tts utiliza la misma estructura que messages.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 únicamente la voz, el modelo, la personalidad o el modo automático para cada cuenta.

Límites de mensajes

• textChunkLimit - tamaño de los fragmentos de texto saliente (valor predeterminado: 4000 caracteres)
• chunkMode - "length" (valor predeterminado) divide al alcanzar el límite; "newline" prioriza los saltos de línea
• 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 se activa, el bot actualiza la tarjeta en tiempo real a medida que genera el texto.

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

Establezca streaming: false para enviar la respuesta completa en un único mensaje; renderMode: "raw" (texto sin formato en lugar de tarjetas) también desactiva las tarjetas en streaming. blockStreaming está desactivado de forma predeterminada; actívelo solo cuando desee que los bloques completados del asistente se envíen antes de la respuesta final.

Optimización de cuotas

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

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

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

Ámbito de las sesiones grupales e hilos de temas

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

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

Establezca replyInThread: "enabled" (en el nivel superior o por grupo) para 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; se recomienda utilizar 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 definidos. Los controles por cuenta se encuentran en accounts.<id>.tools.

Concede drive:drive.metadata:readonly para las 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 los dos á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 en hilos de grupo. ACP en 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 mensaje directo o hilo de Feishu/Lark:

/acp spawn codex --thread here

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

Enrutamiento multiagente

Usa bindings para dirigir los 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 grupal)
• match.peer.id: Open ID del usuario (ou_xxx) o ID del grupo (oc_xxx)

Consulta Obtener los ID de grupos y usuarios para ver consejos de búsqueda.

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

Activa dynamicAgentCreation para crear automáticamente instancias de agente aisladas para cada usuario de mensajes directos. Cada usuario obtiene:

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

Esto es esencial para bots públicos en los que se desea 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: {    // 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, usa "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 prefijo de 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 los archivos de arranque (AGENTS.md, SOUL.md, USER.md, etc.) en el primer acceso
5. Dirige todos los mensajes futuros de este usuario a su agente dedicado

Opciones de configuración

Variables de plantilla:

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

Ámbito de la sesión

session.dmScope controla cómo se asignan los mensajes directos a las sesiones del agente. Este es un ajuste global que afecta a todos los canales.

Contrapartida: Usar "main" permite la carga automática de archivos de arranque (USER.md, SOUL.md, MEMORY.md), pero implica 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 sea más importante que la carga automática de archivos de arranque, considera "per-channel-peer" y gestiona los archivos de arranque manualmente.

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 según 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

Revisa 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  directorio del agente: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

Enumera todos los espacios de trabajo creados:

ls -la ~/.openclaw/workspace-*

Notas

• Aislamiento del espacio de trabajo: Cada usuario obtiene su propio directorio de espacio de trabajo e 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 coarrendatarios hostiles. El proceso del agente y el entorno del host son compartidos.
• Las escrituras de configuración deben permanecer activadas: La creación dinámica de agentes escribe agentes y vinculaciones en la configuración; se omite cuando channels.feishu.configWrites es false (valor predeterminado: activado).
• 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/contenido multimedia
• ✅ Pegatinas

Los mensajes de audio entrantes de Feishu/Lark se normalizan como marcadores de posición de contenido 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 este recibe la transcripción del contenido hablado. Si Feishu incluye el texto de la transcripción directamente en la carga útil del audio, se utiliza ese texto sin realizar 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 sin procesar del recurso de Feishu.

Envío

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

Las burbujas de audio nativas de Feishu/Lark utilizan el tipo de mensaje audio de Feishu y requieren contenido multimedia Ogg/Opus para la carga (file_type: "opus"). El contenido multimedia .opus y .ogg existente se envía directamente como audio nativo. Los formatos MP3/WAV/M4A y otros formatos probablemente de audio se transcodifican a Ogg/Opus de 48kHz con ffmpeg solo cuando la respuesta solicita la entrega por voz (audioAsVoice / asVoice de la herramienta de mensajes, incluidas las respuestas de notas de voz de TTS). Los archivos MP3 adjuntos 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 permanecen vinculadas al 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 de temas.

Temas relacionados

• Descripción general de los canales - todos los canales compatibles
• Vinculación - autenticación de mensajes directos y flujo de vinculación
• Grupos - comportamiento del chat grupal y control mediante menciones
• Enrutamiento de canales - enrutamiento de sesiones para mensajes
• Seguridad - modelo de acceso y refuerzo de la seguridad