Integracao do OpenClaw com Feishu/Lark: Guia Completo de Configuracao

Feishu vs Lark: Duas Plataformas, Uma Integracao

Feishu e Lark sao as plataformas de mensagens corporativas da ByteDance — Feishu para a China continental e Lark para o mercado internacional. As duas compartilham a mesma arquitetura, entao o processo de integracao e praticamente identico, independente de qual versao a sua organizacao usa.

O OpenClaw oferece duas formas de conexao com o Feishu/Lark:

Este guia foca no plugin integrado, que resolve cerca de 90% dos casos de uso. Se voce precisa de integracao completa com o workspace (ler documentos, gerenciar calendarios, criar tarefas), veja a secao Plugin Oficial do Feishu mais adiante.

Pre-requisitos para Configuracao do OpenClaw com Feishu

Antes de comecar, confira se voce tem:

• OpenClaw instalado e rodando (versao >= 2026.2). Se ainda nao configurou, siga o guia de instalacao.
• Uma conta de desenvolvedor Feishu em open.feishu.cn (ou open.larksuite.com para o Lark).
• Gateway acessivel — confirme com:

openclaw gateway status

Nao precisa de IP publico nem dominio. O plugin integrado usa o modo WebSocket por padrao, que estabelece uma conexao de saida com os servidores do Feishu. Funciona atras de NATs, firewalls e na maioria das redes corporativas sem nenhum redirecionamento de porta.

Passo 1: Criar um Bot App no Feishu/Lark

Acessar o Console de Desenvolvedor

Acesse o portal de desenvolvedores da sua plataforma:

• Feishu (China): open.feishu.cn → Console de Desenvolvedor
• Lark (Internacional): open.larksuite.com → Developer Console

Criar a Aplicacao

1. Clique em Create Custom App (ou "Enterprise Self-Built Application", dependendo do idioma da interface)
2. Preencha o nome do app — algo descritivo como "OpenClaw Assistant"
3. Opcionalmente, adicione um icone e uma descricao (isso e o que os usuarios veem no diretorio de bots)

Copiar Suas Credenciais

1. Acesse Credentials & Basic Info no menu lateral
2. Copie o App ID (tem o formato cli_a5xxxxxxxxxxxxx)
3. Copie o App Secret

Mantenha seu App Secret seguro. Nunca faca commit dele no controle de versao, nao cole em chats e nao inclua em capturas de tela. Se vazar, gere um novo imediatamente pelo console de desenvolvedor.

Passo 2: Configurar Permissoes do Bot Feishu

Seu app precisa de permissoes (scopes) especificas para enviar e receber mensagens. Existem duas formas de configurar isso.

Opcao A: Importacao em Lote (Recomendado)

Essa e a abordagem mais rapida — voce cola um bloco JSON e todas as permissoes sao habilitadas de uma vez.

1. Nas configuracoes do seu app, va em Development Settings → Permission Management
2. Clique em Batch Enable (ou "Batch Import Scopes")
3. Cole o seguinte JSON:

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message:send_as_bot",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:message.group_msg", "im:message:readonly", "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly",
      "application:application:self_manage", "application:bot.menu:write",
      "cardkit:card:write",
      "docs:document.content:read", "sheets:spreadsheet",
      "wiki:wiki:readonly", "event:ip_list"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

4. Clique em Confirm para aplicar

Opcao B: Selecao Manual

Se a importacao em lote nao estiver disponivel na sua versao do console, habilite estas permissoes individualmente em Permission Management:

• im:message — Enviar e receber mensagens
• im:message:send_as_bot — Enviar mensagens como bot
• im:message.p2p_msg:readonly — Ler mensagens diretas
• im:message.group_at_msg:readonly — Ler mensagens com @mencao em grupos
• im:message.group_msg — Ler todas as mensagens de grupos
• im:resource — Acessar recursos de mensagem (imagens, arquivos)
• im:chat — Acessar metadados de chats
• im:chat.members:bot_access — Verificar se o bot e membro de chats
• contact:user.employee_id:readonly — Ler IDs de usuarios
• docs:document.content:read — Ler conteudo de documentos (opcional, para resumos de docs)
• sheets:spreadsheet — Acessar planilhas (opcional)
• wiki:wiki:readonly — Ler paginas do wiki (opcional)

As permissoes de documentos, planilhas e wiki sao opcionais. So habilite se voce quer que o bot consiga ler e resumir documentos que os usuarios compartilham no chat.

Passo 3: Habilitar Bot e Inscricoes de Eventos no Feishu

Habilitar a Capacidade de Bot

1. No menu lateral, va em App Capabilities → Bot
2. Ative a capacidade de bot
3. Opcionalmente, defina uma descricao e texto de ajuda para o bot

Configurar Inscricoes de Eventos

Este e o passo critico que diz ao Feishu para encaminhar mensagens para a sua instancia do OpenClaw.

1. Va em Events & Callbacks → Event Subscriptions
2. Em Connection Mode, selecione Long Connection (WebSocket)
3. Adicione os seguintes eventos:

O evento im.message.receive_v1 e o unico estritamente obrigatorio — sem ele, o bot nao recebe nenhuma mensagem. Os eventos de reacao sao uteis se voce quer acionar acoes com base em respostas com emoji (por exemplo, joinha para confirmar uma acao).

Sem as inscricoes de eventos, a caixa de input do chat nao aparece quando os usuarios abrem uma conversa com o bot no Feishu/Lark. Se os usuarios veem o perfil do bot mas nao conseguem digitar nada, quase certamente e esse o problema.

Esta e a causa numero 1 do erro "app has not established a long connection". Se voce vir esse erro nos logs, verifique se adicionou pelo menos o evento im.message.receive_v1 e selecionou o modo Long Connection.

Passo 4: Publicar o App no Feishu

O app so fica visivel para os usuarios depois de publicado.

1. Va em Version Management no menu lateral
2. Clique em Create Version
3. Preencha um numero de versao (por exemplo, 1.0.0) e notas de lancamento
4. Clique em Submit for Review

Para apps internos corporativos, a aprovacao costuma ser automatica se voce for administrador do tenant (ou um admin com escopo completo). Se voce for um desenvolvedor regular, o app pode passar pelo processo de revisao da sua organizacao — consulte seu administrador.

Depois de publicar:

1. Abra o Feishu (ou Lark) no desktop ou celular
2. Va ao diretorio de apps ou use a barra de busca
3. Procure pelo nome do seu app
4. Voce deve ver o bot listado — mas nao mande mensagem ainda. Configure o OpenClaw primeiro.

Passo 5: Configurar o Canal Feishu no OpenClaw

Configuracao Rapida via CLI

A forma mais rapida de conectar:

openclaw channels add    # Selecione "Feishu", depois cole seu App ID e Secret
openclaw gateway restart

O CLI guia voce pelas configuracoes essenciais de forma interativa.

Configuracao Manual

Para mais controle, edite o ~/.openclaw/openclaw.json diretamente:

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",            // Use "lark" para o Lark internacional
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "open",
      requireMention: true,
      streaming: true,
      typingIndicator: true,
      accounts: {
        main: {
          appId: "cli_a5xxxxxxxxxxxxx",
          appSecret: "your-app-secret",
          botName: "AI Assistant"
        }
      }
    }
  }
}

Referencia de Configuracao

Feishu vs Lark (campo domain): A unica diferenca e o campo domain. Defina como "feishu" se a sua organizacao usa Feishu (China), ou "lark" se usa Lark (internacional). Todo o resto — credenciais, permissoes, eventos — funciona da mesma forma.

Passo 6: Iniciar o Gateway do OpenClaw e Parear com Feishu

Iniciar o Gateway

openclaw gateway           # Iniciar o gateway (em primeiro plano)

Em outro terminal, acompanhe os logs:

openclaw logs --follow     # Transmitir logs em tempo real

Voce deve ver uma saida como:

[feishu] WebSocket connected to wss://open.feishu.cn/...
[feishu] Bot "AI Assistant" is online

Parear Sua Conta

A politica padrao de DM e pairing, ou seja, novos usuarios precisam ser aprovados antes de conversar com o bot. Isso evita acessos nao autorizados.

1. Abra o Feishu (ou Lark) e encontre seu bot
2. Mande qualquer mensagem — "ola" funciona
3. Verifique seu terminal. Voce vera uma solicitacao de pareamento com um codigo:

[feishu] New pairing request from user_xxxxx (Code: ABC123)

4. Aprove o pareamento:

openclaw pairing approve feishu ABC123

5. Volte ao Feishu/Lark e mande outra mensagem
6. A IA deve responder

Verificar a Conexao

openclaw gateway status

Saida esperada:

Feishu: connected (websocket)
  Account: main
  Bot: AI Assistant
  Paired users: 1
  Active groups: 0

Se o status mostrar disconnected, confira a secao de Solucao de Problemas abaixo.

Configuracao de Chat em Grupo no Feishu

Por padrao, groupPolicy: "open" permite que o bot entre em qualquer grupo ao qual for adicionado. Para um controle mais rigoroso, use uma allowlist:

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      requireMention: true,
      groups: {
        "oc_xxxxxxxxx": {           // ID do chat no Feishu
          agentId: "main",
          requireMention: false      // Override: responder a todas as mensagens neste grupo
        },
        "oc_yyyyyyyyy": {
          agentId: "support",        // Rotear para um agente diferente
          requireMention: true
        }
      }
    }
  }
}

Para descobrir o ID de um grupo, adicione o bot ao grupo e confira os logs — o ID e exibido quando o bot entra.

Dica: Defina requireMention: true globalmente e faca override por grupo. Isso evita que o bot seja barulhento em canais grandes, mas permite conversa livre em grupos dedicados ao bot.

Modo Webhook do Feishu no OpenClaw

WebSocket e o modo de conexao recomendado, mas algumas redes corporativas bloqueiam conexoes WebSocket persistentes de saida. Nesse caso, mude para o modo webhook:

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "do-console-feishu",
      encryptKey: "do-console-feishu",
      webhookPath: "/feishu/events",
      webhookPort: 3000
    }
  }
}

Para obter o token de verificacao e a chave de criptografia:

1. Nas configuracoes do seu app Feishu, va em Events & Callbacks → Encryption Strategy
2. Copie o Verification Token e o Encrypt Key

Depois, configure a URL de requisicao no console do Feishu:

1. Em Events & Callbacks → Event Subscriptions, mude para Push to URL
2. Defina a URL como https://seu-dominio.com/feishu/events
3. Clique em Verify — o Feishu envia uma requisicao de desafio e o OpenClaw responde automaticamente

O modo webhook exige uma URL acessivel publicamente. Voce vai precisar de um dominio, certificado TLS e regras de firewall adequadas. Para a maioria dos cenarios, WebSocket e muito mais simples.

Roteamento Multi-Agente para Feishu no OpenClaw

Se voce roda multiplos agentes de IA, pode rotear diferentes conversas para diferentes agentes:

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "support", match: { channel: "feishu", peer: { kind: "direct", id: "ou_xxxxx" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxxxxxxxx" } } }
  ]
}

Por padrao, mensagens diretas sao roteadas para o agente principal (main). Voce pode definir regras especificas para usuarios ou grupos — por exemplo, direcionar DMs de um usuario especifico para o agente support, ou mensagens de um grupo para o agente team-helper.

Isso e util para organizacoes que querem um assistente de uso geral, um agente de suporte ao cliente e um agente de ferramentas para devs — todos rodando pelo mesmo bot Feishu, mas com modelos e prompts diferentes por tras.

Plugin Oficial do Feishu para OpenClaw

O plugin oficial do Feishu e mantido pelo time do Feishu/Lark na ByteDance. Diferente do plugin integrado (que opera como bot), o plugin oficial usa OAuth para agir em nome de um usuario. Isso da acesso ao workspace completo: documentos, calendarios, tarefas, planilhas e wikis.

Requisitos

• OpenClaw >= 2026.2.26 (Linux/macOS) ou >= 2026.3.2 (Windows)
• Node.js >= 22
• npm disponivel no PATH

Instalacao

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-plugin.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu-plugin.tgz -g
rm /tmp/feishu-plugin.tgz
feishu-plugin-onboard install

O comando feishu-plugin-onboard install inicia um assistente de configuracao interativo. Ele vai:

1. Pedir seu App ID e App Secret do Feishu
2. Abrir uma janela do navegador para autorizacao OAuth
3. Gerar um arquivo de configuracao em ~/.openclaw/plugins/feishu/config.json
4. Registrar o plugin na sua instancia do OpenClaw

Pos-Instalacao

Apos a instalacao, verifique se o plugin foi carregado:

openclaw plugins list

Voce deve ver feishu-official na saida. Teste pedindo ao bot para executar uma acao no workspace:

@Bot Resuma o documento mais recente no espaco de wiki "Engenharia"

Diagnosticos

Se o plugin nao estiver funcionando:

feishu-plugin-onboard doctor           # Verificar problemas comuns
feishu-plugin-onboard doctor --fix     # Corrigir automaticamente problemas detectados
feishu-plugin-onboard info --all       # Ver informacoes completas do plugin

Atencao quanto a seguranca: O plugin oficial acessa os dados do seu workspace atraves do seu token OAuth pessoal. Isso significa que o bot pode ler qualquer documento, evento de calendario ou tarefa que voce tem acesso. Nao use o plugin oficial em bots ou maquinas compartilhadas — use apenas em instancias pessoais e seguras.

Usando os Dois Plugins Simultaneamente

Voce pode rodar o plugin integrado e o plugin oficial ao mesmo tempo. O plugin integrado cuida das mensagens, enquanto o plugin oficial cuida das acoes no workspace. O OpenClaw roteia as requisicoes para o plugin adequado automaticamente.

Para desabilitar o plugin oficial sem desinstalar:

feishu-plugin-onboard disable

Solucao de Problemas da Integracao Feishu

"Sem caixa de input" — usuarios nao conseguem digitar mensagens para o bot

Causa: Inscricoes de eventos estao faltando ou o app nao foi publicado.

Solucao:

1. Confirme que im.message.receive_v1 esta adicionado em Events & Callbacks
2. Confirme que o modo de conexao esta definido como Long Connection
3. Confirme que o app esta publicado (Version Management → verifique se ha uma versao ativa)
4. Reinicie o gateway: openclaw gateway restart

Erro "App has not established a long connection"

Causa: A inscricao de eventos do Feishu espera uma conexao WebSocket, mas o OpenClaw ainda nao conectou.

Solucao:

1. Confirme que connectionMode esta como "websocket" na sua configuracao
2. Reinicie o gateway: openclaw gateway restart
3. Confira os logs: openclaw logs --follow — procure por mensagens de conexao WebSocket
4. Se estiver atras de um proxy restritivo, verifique se conexoes WebSocket de saida estao bloqueadas

Bot esta online mas nao responde mensagens

Causa: Geralmente e um problema de pareamento ou politica de DM mal configurada.

Solucao:

1. Verifique se o usuario esta pareado: openclaw pairing list feishu
2. Se estiver usando modo pairing, aprove o usuario: openclaw pairing approve feishu <CODE>
3. Se quiser que qualquer pessoa converse sem pareamento, defina dmPolicy: "open"
4. Confira os logs para erros: openclaw logs --follow

Bot nao responde em chats de grupo

Causa: O bot exige @mencao mas nao foi mencionado, ou a politica de grupo bloqueia o grupo.

Solucao:

1. Certifique-se de que groupPolicy esta como "open" ou que o grupo esta na allowlist
2. Se requireMention estiver como true, os usuarios precisam @mencionar o bot
3. Verifique se o bot realmente e membro do grupo
4. Confira se a permissao im:message.group_msg esta habilitada

Erro "Message send failed" ou "send_as_bot"

Causa: Permissao im:message:send_as_bot ausente, ou o app nao foi republicado apos adicionar permissoes.

Solucao:

1. Confirme que a permissao esta habilitada no console de desenvolvedor
2. Crie uma nova versao e publique — alteracoes de permissoes exigem um novo release
3. Reinicie o gateway

Conflito entre plugin integrado e plugin oficial

Causa: Ambos os plugins tentando processar o mesmo evento.

Solucao:

1. Normalmente isso nao e um problema — o OpenClaw deduplica eventos. Se voce estiver vendo respostas duplicadas, desabilite um:

feishu-plugin-onboard disable    # Desabilitar plugin oficial
# OU
openclaw channels disable feishu  # Desabilitar plugin integrado

2. Avalie qual plugin voce realmente precisa — a maioria dos usuarios so precisa do plugin integrado

Windows: Erro ENOENT ao instalar o plugin oficial

Causa: O npm nao consegue encontrar o arquivo .tgz baixado, geralmente um problema de caminho no Windows.

Solucao:

1. Use um caminho absoluto completo:

npm install C:\Users\SeuNome\Downloads\feishu-plugin.tgz -g

2. Certifique-se de que esta rodando o terminal como Administrador
3. Verifique se o Node.js e >= 22: node --version

Referencia de Comandos OpenClaw para Feishu

FAQ

Preciso de IP publico ou dominio?

Nao. O modo WebSocket (padrao) conecta de saida, da sua maquina para os servidores do Feishu. Nenhum trafego de entrada, nenhum redirecionamento de porta, nenhum registro DNS. A unica excecao e o modo webhook, que exige uma URL acessivel publicamente.

Qual a diferenca entre Feishu e Lark?

Feishu e para a China continental. Lark e a versao internacional. Rodam em infraestruturas separadas, mas tem os mesmos recursos e APIs. A unica diferenca na configuracao e o campo domain — defina como "feishu" ou "lark". Seu App ID e Secret funcionam na plataforma em que foram criados.

Devo usar o plugin integrado ou o plugin oficial?

Para mensagens — enviar e receber mensagens, ler conteudo compartilhado no chat — o plugin integrado e tudo que voce precisa. Para acoes no workspace — ler documentos, gerenciar calendarios, criar tarefas, consultar planilhas — use o plugin oficial. Voce pode rodar os dois simultaneamente.

Posso rodar o Feishu junto com outros canais?

Sim. O OpenClaw suporta multiplos canais simultaneamente. Voce pode ter Feishu, Telegram, Discord, WhatsApp e outros rodando ao mesmo tempo, cada um conectado ao mesmo agente ou a agentes diferentes. Adicione com openclaw channels add.

As respostas estao lentas — como acelerar?

1. Habilite streaming (streaming: true) — isso mostra respostas parciais conforme sao geradas, entao os usuarios veem o texto aparecendo imediatamente
2. Confira seu modelo — modelos maiores sao mais lentos. Experimente um modelo mais rapido para consultas rotineiras
3. Verifique a latencia de rede — se sua instancia do OpenClaw esta longe dos servidores do Feishu, as respostas vao parecer mais lentas
4. Revise seu prompt — prompts de sistema longos aumentam o tempo de processamento

Meu App Secret foi comprometido — o que faco?

1. Va ao console de desenvolvedor do Feishu imediatamente
2. Acesse Credentials & Basic Info
3. Clique em Reset ao lado do App Secret
4. Copie o novo secret
5. Atualize ~/.openclaw/openclaw.json com o novo valor
6. Reinicie o gateway: openclaw gateway restart
7. O secret antigo e invalidado instantaneamente — nao precisa revogar sessoes individuais

Proximos Passos Apos Configurar o Feishu

Agora que sua integracao Feishu/Lark esta funcionando, explore o que mais o OpenClaw pode fazer:

• Veja todos os 50+ canais suportados — conecte plataformas adicionais
• Diretorio de Skills — descubra o que seu assistente de IA pode fazer
• Guia de solucao de problemas — resolva problemas comuns em todos os canais
• Guia completo para iniciantes — aprenda OpenClaw do zero
• Integracao com Telegram — adicione o Telegram como outro canal
• Integracao com Discord — configure o Discord com Gateway Intents