​

Bot de Feishu

​

Plugin incluido

openclaw plugins install @openclaw/feishu

​

Inicio rápido

​

Método 1: onboarding (recomendado)

openclaw onboard

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

• openclaw gateway status
• openclaw logs --follow

​

Método 2: configuración con la CLI

openclaw channels add

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

​

Paso 1: Crear una app de Feishu

​

1. Abre Feishu Open Platform

​

2. Crea una app

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

​

3. Copia las credenciales

• App ID (formato: cli_xxx)
• App Secret

​

4. Configura los permisos

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

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

​

6. Configura la suscripción a eventos

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

1. Elige Use long connection to receive events (WebSocket)
2. Agrega el evento: im.message.receive_v1
3. (Opcional) Para los flujos de trabajo de comentarios de Drive, agrega también: drive.notice.comment_add_v1

​

7. Publica la app

1. Crea una versión en Version Management & Release
2. Envíala para revisión y publícala
3. Espera la aprobación del administrador (las apps empresariales suelen aprobarse automáticamente)

​

Paso 2: Configurar OpenClaw

​

Configurar con el asistente (recomendado)

openclaw channels add

​

Configurar mediante archivo de configuración

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

​

Verification Token y Encrypt Key (modo webhook)

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

​

Configurar mediante variables de entorno

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

​

Dominio de Lark (global)

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

​

Indicadores de optimización de cuota

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

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

​

Paso 3: Iniciar + probar

​

1. Inicia el gateway

openclaw gateway

​

2. Envía un mensaje de prueba

​

3. Aprueba el pairing

openclaw pairing approve feishu <CODE>

​

Resumen

• Canal de bot de Feishu: bot de Feishu gestionado 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 mediante el SDK de Feishu, sin necesidad de una URL pública

​

Control de acceso

​

Mensajes directos

• Predeterminado: dmPolicy: "pairing" (los usuarios desconocidos reciben un código de pairing)
• Aprobar pairing:
  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>
  
• Modo allowlist: establece channels.feishu.allowFrom con los Open ID permitidos

​

Chats grupales

• "open" = permitir a todos en grupos
• "allowlist" = permitir solo groupAllowFrom
• "disabled" = deshabilitar mensajes de grupo

• true explícito = requiere @mention
• false explícito = responde sin menciones
• cuando no está establecido y groupPolicy: "open" = predeterminado false
• cuando no está establecido y groupPolicy no es "open" = predeterminado true

​

Ejemplos de configuración de grupos

​

Permitir todos los grupos, sin requerir @mention (predeterminado para grupos abiertos)

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

​

Permitir todos los grupos, pero seguir requiriendo @mention

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

​

Permitir solo grupos específicos

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Los ID de grupo de Feishu (chat_id) tienen un formato como: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

​

Restringir qué remitentes pueden enviar mensajes en un grupo (allowlist de remitentes)

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

​

Obtener ID de grupo/usuario

​

ID de grupo (chat_id)

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

​

ID de usuario (open_id)

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

openclaw pairing list feishu

​

Comandos comunes

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

​

Comandos de administración del gateway

​

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 hacer @mention al bot (comportamiento predeterminado)
3. Comprueba que groupPolicy no esté configurado como "disabled"
4. Revisa los logs: 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 a eventos incluya im.message.receive_v1
3. Asegúrate de que long connection esté habilitada
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 logs: openclaw logs --follow

​

Fuga de 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 al enviar 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 logs para ver los errores detallados

​

Configuración avanzada

​

Varias cuentas

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

​

Límites de mensajes

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

​

Streaming

{
  channels: {
    feishu: {
      streaming: true, // habilitar salida de tarjetas en streaming (predeterminado true)
      blockStreaming: true, // habilitar streaming a nivel de bloque (predeterminado true)
    },
  },
}

​

Sesiones ACP

• mensajes directos
• conversaciones de tema en grupo

​

Enlaces ACP persistentes

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

​

Creación de ACP vinculada al hilo desde el chat

/acp spawn codex --thread here

• --thread here funciona para mensajes directos y temas de Feishu.
• Los mensajes posteriores en el mensaje directo/tema vinculado se enrutan directamente a esa sesión ACP.
• La v1 no se dirige a chats grupales genéricos sin tema.

​

Enrutamiento multiagente

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

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

​

Referencia de configuración

​

Referencia de dmPolicy

​

Tipos de mensajes compatibles

​

Recepción

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

​

Envío

• ✅ Texto
• ✅ Imágenes
• ✅ Archivos
• ✅ Audio
• ✅ Video/medios
• ✅ Tarjetas interactivas
• ⚠️ Texto enriquecido (formato estilo post y tarjetas, no funciones arbitrarias de autoría de Feishu)

​

Hilos y respuestas

• ✅ Respuestas en línea
• ✅ Respuestas en hilos de tema cuando Feishu expone reply_in_thread
• ✅ Las respuestas con medios mantienen compatibilidad con hilos al responder a un mensaje de hilo/tema

​

Comentarios de Drive

• Suscribirse a drive.notice.comment_add_v1 en la configuración de suscripción a eventos de tu app de Feishu (junto con im.message.receive_v1, que ya existe)
• La herramienta Drive está habilitada de forma predeterminada; desactívala con channels.feishu.tools.drive: false

• el texto del comentario y el remitente
• metadatos del documento (título, tipo, URL)
• el contexto del hilo del comentario para responder en el hilo

​

Superficie de acciones en tiempo de ejecución

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• react y reactions cuando las reacciones están habilitadas en la configuración
• acciones de comentarios feishu_drive: list_comments, list_comment_replies, add_comment, reply_comment

​

Relacionado

• Channels Overview — todos los canales compatibles
• Pairing — autenticación de mensajes directos y flujo de pairing
• Groups — comportamiento de chats grupales y control por menciones
• Channel Routing — enrutamiento de sesiones para mensajes
• Security — modelo de acceso y endurecimiento