Por Que Feishu?
O Feishu (飞书), conhecido internacionalmente como Lark, é a plataforma de colaboração empresarial da ByteDance — amplamente usada em empresas de tecnologia chinesas, startups e cada vez mais no Sudeste Asiático. Com o OpenClaw v2026.2.2, o Feishu se tornou o primeiro cliente de chat chinês oficialmente suportado pela plataforma.
- •Nenhuma URL pública necessária — sem ngrok, sem domínio, sem servidor de webhook
- •Funciona atrás de firewalls — a conexão é de saída a partir da sua máquina
- •Baixa latência — mensagens bidirecionais em tempo real
- •Suporte a conteúdo rico — texto, imagens, arquivos, áudio, vídeo e stickers
Pré-requisitos
- •OpenClaw v2026.2.2 ou posterior
- •Uma conta empresarial Feishu/Lark (o plano gratuito funciona)
- •Acesso de administrador para criar apps na Plataforma Aberta do Feishu
Passo 1: Criar um App no Feishu
- 1.Acesse a Plataforma Aberta do Feishu (ou o Console de Desenvolvedores Lark para tenants internacionais)
- 2.Clique em Criar App Personalizado
- 3.Defina o nome do app (ex: "OpenClaw Agent") e a descrição
- 4.Faça upload de um ícone (o logo da lagosta do OpenClaw funciona bem)
- 5.Copie o App ID (formato:
cli_xxx) e o App Secret da página de Credenciais
Passo 2: Configurar Permissões do App
Nas configurações de permissão do seu app, habilite estes escopos:
| Permissão | Propósito |
|---|---|
im:message | Enviar e receber mensagens |
im:message.group_at_msg | Receber @menções em chats de grupo |
im:resource | Acessar imagens e arquivos |
contact:user.id:readonly | Identificar usuários |
Após adicionar as permissões, clique em Publicar para submeter para revisão. Na maioria dos tenants empresariais, apps criados internamente são aprovados automaticamente.
Passo 3: Habilitar Assinatura de Eventos
- 1.Nas configurações do app, vá para Assinatura de Eventos
- 2.Selecione Modo WebSocket (conexão longa) — isso é crítico. NÃO use o modo webhook, pois ele requer uma URL pública.
- 3.Assine estes eventos:
Passo 4: Configurar o OpenClaw
Adicione as credenciais do Feishu à sua configuração do OpenClaw. Edite ~/.openclaw/.env:
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here
Ou se estiver usando o arquivo de configuração do OpenClaw (~/.openclaw/config.yaml):
channels:
feishu:
enabled: true
appId: cli_xxxxxxxxxxxxx
appSecret: your_app_secret_here
Reinicie o OpenClaw:
openclaw restart
Você deve ver uma mensagem de log confirmando que a conexão WebSocket do Feishu foi estabelecida.
Passo 5: Testar a Conexão
Abra o Feishu e encontre seu app na lista de chats (procure pelo nome do app que você definiu no Passo 1). Envie uma mensagem:
> Olá!
- •Mensagens de texto
- •Imagens (o agente pode analisá-las se estiver usando um modelo com capacidade de visão)
- •Arquivos (o agente pode ler documentos)
- •Mensagens de voz (transcritas e processadas como texto)
Configuração de Chat em Grupo
O OpenClaw suporta chats de grupo no Feishu com três modos de acesso:
| Modo | Comportamento |
|---|---|
open (padrão) | Qualquer membro do grupo pode acionar o bot quando @mencionado |
allowlist | Apenas usuários aprovados podem interagir, mesmo com @menção |
disabled | Mensagens de grupo são completamente ignoradas |
Configure no config.yaml:
channels:
feishu:
groupAccess: open # ou "allowlist" ou "disabled"
allowedUsers: # usado apenas com modo "allowlist"
- user_id_1
- user_id_2
Em chats de grupo, o agente só responde quando @mencionado, prevenindo ruído em canais movimentados.
Respostas em Streaming
O OpenClaw suporta streaming de respostas de IA no Feishu usando cards interativos. Em vez de esperar pela resposta completa, o agente envia um card inicial e o atualiza em tempo real conforme a IA gera texto. Isso proporciona uma experiência de usuário muito melhor para respostas longas.
O streaming é habilitado por padrão. Para desabilitá-lo:
channels:
feishu:
streaming: false
Tipos de Mensagem Suportados
| Direção | Tipos Suportados |
|---|---|
| Entrada (usuário para agente) | Texto, rich text (post), imagens, arquivos, áudio, vídeo, stickers |
| Saída (agente para usuário) | Texto, imagens, arquivos, áudio, cards interativos |
Resolução de Problemas
Erro "App não encontrado": Certifique-se de que o app está publicado e aprovado no seu tenant Feishu. Apps criados internamente em tenants empresariais geralmente são aprovados automaticamente, mas algumas organizações exigem aprovação de administrador.
Sem resposta do agente: Verifique os logs do OpenClaw (openclaw logs) para erros de conexão WebSocket. Verifique se o App ID e o App Secret estão corretos.
Mensagens não chegam em chats de grupo: Certifique-se de que o bot foi adicionado ao grupo, e que o usuário está @mencionando o bot corretamente. Verifique a configuração groupAccess.
Conexão cai: A conexão WebSocket reconecta automaticamente. Se as quedas forem frequentes, verifique a estabilidade da sua rede ou configurações de firewall.
Usando a Bridge da Comunidade (Alternativa)
Se você precisa de recursos além da integração nativa, a bridge feishu-openclaw mantida pela comunidade, de AlexAnys, oferece capacidades adicionais como formatação personalizada de mensagens e gerenciamento avançado de grupos. Leva cerca de 5 minutos para configurar e não requer servidor público.
Para documentação completa, veja o guia oficial do canal Feishu.