Bot Feishu

Feishu (Lark) é uma plataforma de chat corporativo usada por empresas para mensagens e colaboração. Este plugin conecta o OpenClaw a um bot Feishu/Lark usando a assinatura de eventos via WebSocket da plataforma, permitindo receber mensagens sem expor uma URL de webhook pública.

Plugin incluído

O Feishu já vem incluído nas versões atuais do OpenClaw, então não é necessário instalar um plugin separado.

Se estiver usando uma build mais antiga ou uma instalação customizada que não inclua o Feishu, instale-o manualmente:

openclaw plugins install @openclaw/feishu

Início rápido

Existem duas formas de adicionar o canal Feishu:

Método 1: assistente de configuração (recomendado)

Se você acabou de instalar o OpenClaw, execute o assistente:

openclaw onboard

O assistente guia você por:

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

Após a configuração, verifique o status do gateway:

• openclaw gateway status
• openclaw logs --follow

Método 2: configuração via CLI

Se já completou a instalação inicial, adicione o canal via CLI:

openclaw channels add

Escolha Feishu e insira o App ID e o App Secret.

Após a configuração, gerencie o gateway:

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

Passo 1: Crie um app Feishu

1. Abra a Feishu Open Platform

Acesse a Feishu Open Platform e faça login.

Tenants Lark (global) devem usar https://open.larksuite.com/app e definir domain: "lark" na configuração do Feishu.

2. Crie um app

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

3. Copie as credenciais

Em Credentials & Basic Info, copie:

• App ID (formato: cli_xxx)
• App Secret

Importante: mantenha o App Secret em sigilo.

4. Configure as permissões

Em Permissions, clique em Batch import e cole:

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

Em App Capability > Bot:

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

6. Configure a assinatura de eventos

Aviso: antes de configurar a assinatura de eventos, certifique-se de:

1. Já ter executado openclaw channels add para o Feishu
2. O gateway estar rodando (openclaw gateway status)

Em Event Subscription:

1. Escolha Use long connection to receive events (WebSocket)
2. Adicione o evento: im.message.receive_v1

Se o gateway não estiver rodando, a configuração de conexão longa pode falhar ao salvar.

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 geralmente são aprovados automaticamente)

Passo 2: Configure o OpenClaw

Configure com o assistente (recomendado)

openclaw channels add

Escolha Feishu e cole o App ID + App Secret.

Configure via arquivo de configuração

Edite ~/.openclaw/openclaw.json:

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

Se usar connectionMode: "webhook", defina tanto verificationToken quanto encryptKey. O servidor webhook do Feishu escuta em 127.0.0.1 por padrão; defina webhookHost apenas se intencionalmente precisar de um endereço de bind diferente.

Verification Token e Encrypt Key (modo webhook)

No modo webhook, defina channels.feishu.verificationToken e channels.feishu.encryptKey na configuração. Para obter os valores:

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

A captura de tela abaixo mostra onde encontrar o Verification Token. O Encrypt Key está listado na mesma seção Encryption.

Configure via variáveis de ambiente

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

Domínio Lark (global)

Se seu tenant é Lark (internacional), defina o domínio como lark (ou uma string de domínio completa). Pode ser definido em channels.feishu.domain ou por conta (channels.feishu.accounts.<id>.domain).

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

Flags de otimização de cota

Você pode reduzir o uso da API Feishu com duas flags opcionais:

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

Defina no nível superior ou por conta:

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

Passo 3: Inicie e teste

1. Inicie o gateway

openclaw gateway

2. Envie uma mensagem de teste

No Feishu, encontre o bot e envie uma mensagem.

3. Aprove o pareamento

Por padrão, o bot responde com um código de pareamento. Aprove-o:

openclaw pairing approve feishu <CODE>

Após a aprovação, você pode conversar normalmente.

Visão geral

• Canal bot Feishu: bot Feishu gerenciado pelo gateway
• Roteamento determinístico: respostas sempre retornam para o Feishu
• Isolamento de sessão: DMs compartilham uma sessão principal; grupos são isolados
• Conexão WebSocket: conexão longa via SDK 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 lista de permitidos: defina channels.feishu.allowFrom com os Open IDs permitidos

Chats de grupo

1. Política de grupo (channels.feishu.groupPolicy):

• "open" = permite todos nos grupos (padrão)
• "allowlist" = permite apenas groupAllowFrom
• "disabled" = desativa mensagens de grupo

2. Requisito de menção (channels.feishu.groups.<chat_id>.requireMention):

• true = exige @menção (padrão)
• false = responde sem menções

Exemplos de configuração de grupo

Permitir todos os grupos, exigir @menção (padrão)

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

Permitir todos os grupos, sem exigir @menção

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

Permitir apenas grupos específicos

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Restringir quais remetentes podem enviar mensagens em um grupo (lista de permitidos de remetentes)

Além de permitir o grupo em si, todas as mensagens nesse grupo são filtradas pelo open_id do remetente: apenas usuários listados em groups.<chat_id>.allowFrom têm suas mensagens processadas; mensagens de outros membros são ignoradas (isso é filtragem completa a nível de remetente, não apenas para comandos de controle como /reset ou /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu user IDs (open_id) look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Obter IDs de grupo/usuário

IDs de grupo (chat_id)

IDs de grupo têm formato oc_xxx.

Método 1 (recomendado)

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

Método 2

Use o debugger da API Feishu para listar os chats de grupo.

IDs de usuário (open_id)

IDs de usuário têm formato ou_xxx.

Método 1 (recomendado)

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

Método 2

Verifique as solicitações de pareamento para os Open IDs dos usuários:

openclaw pairing list feishu

Comandos comuns

Nota: O Feishu ainda não suporta menus de comando nativos, então os comandos devem ser enviados como texto.

Comandos de gerenciamento do gateway

Solução de problemas

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 (comportamento padrão)
3. Verifique se groupPolicy não está definido como "disabled"
4. Verifique os logs: openclaw logs --follow

Bot não recebe mensagens

1. Certifique-se de que o app está publicado e aprovado
2. Certifique-se de que a assinatura de eventos inclui im.message.receive_v1
3. Certifique-se de que a conexão longa está ativada
4. Certifique-se de que as permissões do app estão completas
5. Certifique-se de que o gateway está rodando: openclaw gateway status
6. Verifique os logs: openclaw logs --follow

Vazamento do App Secret

1. Resete o App Secret na Feishu Open Platform
2. Atualize o App Secret na 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 está publicado
3. Verifique os logs para erros detalhados

Configuração avançada

Múltiplas contas

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

defaultAccount controla qual conta Feishu é usada quando APIs de saída não especificam um accountId explicitamente.

Limites de mensagem

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

Streaming

O Feishu suporta respostas em streaming via cards interativos. Quando ativado, o bot atualiza um card conforme gera o texto.

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

Defina streaming: false para aguardar a resposta completa antes de enviar.

Roteamento multiagente

Use bindings para rotear DMs ou grupos do Feishu para diferentes agentes.

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

Campos de roteamento:

• 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)

Veja Obter IDs de grupo/usuário para dicas de lookup.

Referência de configuração

Configuração completa: Configuração do gateway

Opções principais:

Referência de dmPolicy

Tipos de mensagem suportados

Recebimento

• Texto
• Rich text (post)
• Imagens
• Arquivos
• Áudio
• Vídeo
• Stickers

Envio

• Texto
• Imagens
• Arquivos
• Áudio
• Rich text (suporte parcial)