​

Bot do Feishu

​

Plugin empacotado

openclaw plugins install @openclaw/feishu

​

Início rápido

​

Método 1: onboarding (recomendado)

openclaw onboard

1. Criar um app no Feishu e coletar credenciais
2. Configurar as credenciais do app no OpenClaw
3. Iniciar o gateway

• openclaw gateway status
• openclaw logs --follow

​

Método 2: configuração pela CLI

openclaw channels add

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

​

Etapa 1: criar um app do Feishu

​

1. Abra a Feishu Open Platform

​

2. Crie um app

1. Clique em Create enterprise app
2. Preencha o nome e a descrição do app
3. Escolha um ícone para o app

​

3. Copie as credenciais

• App ID (formato: cli_xxx)
• App Secret

​

4. Configure as permissões

{
  "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. Habilite a capacidade de bot

1. Habilite a capacidade de bot
2. Defina o nome do bot

​

6. Configure a assinatura de eventos

1. Você já executou openclaw channels add para o Feishu
2. O gateway está em execução (openclaw gateway status)

1. Escolha Use long connection to receive events (WebSocket)
2. Adicione o evento: im.message.receive_v1
3. (Opcional) Para fluxos de trabalho de comentários do Drive, adicione também: drive.notice.comment_add_v1

​

7. Publique o app

1. Crie uma versão em Version Management & Release
2. Envie para revisão e publique
3. Aguarde a aprovação do administrador (apps corporativos normalmente são aprovados automaticamente)

​

Etapa 2: configurar o OpenClaw

​

Configurar com o assistente (recomendado)

openclaw channels add

​

Configurar pelo arquivo de configuração

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Meu assistente de IA",
        },
      },
    },
  },
}

​

Verification Token e Encrypt Key (modo webhook)

1. Na Feishu Open Platform, abra seu app
2. Vá para Development → Events & Callbacks (开发配置 → 事件与回调)
3. Abra a aba Encryption (加密策略)
4. Copie Verification Token e Encrypt Key

​

Configurar por variáveis de ambiente

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

​

Domínio do Lark (global)

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

​

Flags de otimização de cota

• typingIndicator (padrão true): quando false, ignora chamadas de reação de digitação.
• resolveSenderNames (padrão true): quando false, ignora chamadas de busca de perfil do remetente.

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

​

Etapa 3: iniciar e testar

​

1. Inicie o gateway

openclaw gateway

​

2. Envie uma mensagem de teste

​

3. Aprove o pareamento

openclaw pairing approve feishu <CODE>

​

Visão geral

• Canal de bot do Feishu: bot do Feishu gerenciado pelo gateway
• Roteamento determinístico: as respostas sempre retornam ao Feishu
• Isolamento de sessão: DMs compartilham uma sessão principal; grupos são isolados
• Conexão WebSocket: conexão longa via SDK do Feishu, sem necessidade de URL pública

​

Controle de acesso

​

Mensagens diretas

• Padrão: dmPolicy: "pairing" (usuários desconhecidos recebem um código de pareamento)
• Aprovar pareamento:
  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>
  
• Modo allowlist: defina channels.feishu.allowFrom com os Open IDs permitidos

​

Chats em grupo

• "open" = permite todos nos grupos
• "allowlist" = permite apenas groupAllowFrom
• "disabled" = desabilita mensagens em grupo

• true explícito = exigir @mention
• false explícito = responder sem menções
• quando não definido e groupPolicy: "open" = o padrão é false
• quando não definido e groupPolicy não é "open" = o padrão é true

​

Exemplos de configuração de grupo

​

Permitir todos os grupos, sem exigir @mention (padrão para grupos abertos)

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

​

Permitir todos os grupos, mas ainda exigir @mention

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

​

Permitir apenas grupos específicos

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Os IDs de grupo (chat_id) do Feishu se parecem com: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

​

Restringir quais remetentes podem enviar mensagem em um grupo (allowlist de remetentes)

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Os IDs de usuário (open_id) do Feishu se parecem com: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

​

Obter IDs de grupo/usuário

​

IDs de grupo (chat_id)

1. Inicie o gateway e mencione o bot com @ no grupo
2. Execute openclaw logs --follow e procure chat_id

​

IDs de usuário (open_id)

1. Inicie o gateway e envie uma DM para o bot
2. Execute openclaw logs --follow e procure open_id

openclaw pairing list feishu

​

Comandos comuns

Observação: o Feishu ainda não oferece suporte a menus de comandos nativos, então os comandos devem ser enviados como texto.

​

Comandos de gerenciamento do gateway

​

Solução de problemas

​

O bot não responde em chats de grupo

1. Certifique-se de que o bot foi adicionado ao grupo
2. Certifique-se de mencionar o bot com @ (comportamento padrão)
3. Verifique se groupPolicy não está definido como "disabled"
4. Verifique os logs: openclaw logs --follow

​

O bot não recebe mensagens

1. Certifique-se de que o app foi publicado e aprovado
2. Certifique-se de que a assinatura de eventos inclui im.message.receive_v1
3. Certifique-se de que long connection está habilitada
4. Certifique-se de que as permissões do app estão completas
5. Certifique-se de que o gateway está em execução: openclaw gateway status
6. Verifique os logs: openclaw logs --follow

​

Vazamento do App Secret

1. Redefina o App Secret na Feishu Open Platform
2. Atualize o App Secret na sua configuração
3. Reinicie o gateway

​

Falhas no envio de mensagens

1. Certifique-se de que o app tem a permissão im:message:send_as_bot
2. Certifique-se de que o app foi publicado
3. Verifique os logs para ver erros detalhados

​

Configuração avançada

​

Múltiplas contas

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Bot principal",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Bot de backup",
          enabled: false,
        },
      },
    },
  },
}

​

Limites de mensagem

• textChunkLimit: tamanho do bloco de texto de saída (padrão: 2000 caracteres)
• mediaMaxMb: limite de upload/download de mídia (padrão: 30MB)

​

Streaming

{
  channels: {
    feishu: {
      streaming: true, // habilita saída em streaming por cartão (padrão true)
      blockStreaming: true, // habilita streaming em nível de bloco (padrão true)
    },
  },
}

​

Sessões ACP

• DMs
• conversas de tópico em grupo

​

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

​

Geração de ACP vinculada à thread a partir do chat

/acp spawn codex --thread here

• --thread here funciona para DMs e tópicos do Feishu.
• Mensagens subsequentes na DM/tópico vinculado são roteadas diretamente para essa sessão ACP.
• A v1 não tem como alvo chats em grupo genéricos sem tópico.

​

Roteamento 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" ou "group"
• match.peer.id: Open ID do usuário (ou_xxx) ou ID do grupo (oc_xxx)

​

Referência de configuração

​

Referência de dmPolicy

​

Tipos de mensagem compatíveis

​

Receber

• ✅ Texto
• ✅ Texto rico (post)
• ✅ Imagens
• ✅ Arquivos
• ✅ Áudio
• ✅ Vídeo/mídia
• ✅ Figurinhas

​

Enviar

• ✅ Texto
• ✅ Imagens
• ✅ Arquivos
• ✅ Áudio
• ✅ Vídeo/mídia
• ✅ Cartões interativos
• ⚠️ Texto rico (formatação estilo post e cartões, não recursos arbitrários de autoria do Feishu)

​

Threads e respostas

• ✅ Respostas inline
• ✅ Respostas em topic-thread quando o Feishu expõe reply_in_thread
• ✅ Respostas com mídia permanecem cientes da thread ao responder a uma mensagem de thread/tópico

​

Comentários do Drive

• Assine drive.notice.comment_add_v1 nas configurações de assinatura de eventos do seu app Feishu (junto com o já existente im.message.receive_v1)
• A ferramenta Drive é habilitada por padrão; desabilite com channels.feishu.tools.drive: false

• o texto do comentário e o remetente
• metadados do documento (título, tipo, URL)
• o contexto da thread de comentários para respostas na thread

​

Superfície de ações em runtime

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• react e reactions quando reações estão habilitadas na configuração
• ações de comentário feishu_drive: list_comments, list_comment_replies, add_comment, reply_comment

​

Relacionado

• Channels Overview — todos os canais compatíveis
• Pairing — autenticação de DM e fluxo de pareamento
• Groups — comportamento de chat em grupo e controle por menção
• Channel Routing — roteamento de sessão para mensagens
• Security — modelo de acesso e hardening