Configuração do Feishu / Lark

O Hermes Agent se integra ao Feishu e ao Lark como um bot completo. Depois de conectado, você conversa com o agente em mensagens diretas ou em grupos, recebe resultados de tarefas cron em um chat casa e envia texto, imagens, áudio e anexos de arquivo pelo fluxo normal do gateway.

A integração suporta os dois modos de conexão:

• websocket — recomendado; o Hermes abre a conexão de saída e você não precisa de um endpoint público de webhook
• webhook — útil quando você quer que o Feishu/Lark empurre os eventos para o seu gateway por HTTP

Como o Hermes se comporta

Contexto	Comportamento
Mensagens diretas	O Hermes responde a toda mensagem.
Grupos	O Hermes só responde quando o bot é mencionado com @ no chat.
Grupos compartilhados	Por padrão, o histórico de sessão é isolado por usuário dentro de um chat compartilhado.

Esse comportamento em chats compartilhados é controlado pelo config.yaml:

group_sessions_per_user: true

Defina como false só se você realmente quiser uma conversa compartilhada por chat.

Passo 1: crie um app no Feishu / Lark

Recomendado: criar por QR Code (um comando)

hermes gateway setup

Selecione Feishu / Lark e escaneie o QR Code com o app de celular do Feishu ou do Lark. O Hermes cria automaticamente uma aplicação de bot com as permissões corretas e salva as credenciais.

Alternativa: configuração manual

Se a criação por QR Code não estiver disponível, o assistente volta para a entrada manual:

1. Abra o console de desenvolvedor do Feishu ou do Lark:
   • Feishu: https://open.feishu.cn/
   • Lark: https://open.larksuite.com/
2. Crie um app novo.
3. Em Credentials & Basic Info, copie o App ID e o App Secret.
4. Habilite a capacidade Bot para o app.
5. Rode hermes gateway setup, selecione Feishu / Lark e informe as credenciais quando forem pedidas.

aviso

Mantenha o App Secret em segredo. Qualquer pessoa com ele pode se passar pelo seu app.

Configure as permissões

No console de desenvolvedor do Feishu, vá em Permission Management e adicione os escopos abaixo. Você pode importá-los em lote na página de permissões.

Permissões obrigatórias:

Escopo	Para que serve
im:message	Receber e ler mensagens
im:message:send_as_bot	Enviar mensagens como o bot
im:resource	Acessar imagens, arquivos e áudio enviados pelos usuários
im:chat	Acessar metadados de chat/grupo
im:chat:readonly	Ler a lista de chats e os membros

Permissões recomendadas (para funcionalidade completa):

Escopo	Para que serve
im:message.reactions:readonly	Receber eventos de reação com emoji
admin:app.info:readonly	Detectar automaticamente a identidade do bot para o controle por menção
contact:user.id:readonly	Resolver IDs de usuário para casar com a lista de permissão

Configure os eventos

Em Events and Callbacks:

1. Defina o modo de conexão como Long Connection (WebSocket) (recomendado) ou configure uma URL de webhook
2. Na seção Event Configuration, assine:
   • im.message.receive_v1 — obrigatório para receber mensagens

Publique o app

Depois de configurar permissões e eventos, vá em Version Management e publique uma nova versão do app. As permissões só entram em vigor quando uma versão é publicada e aprovada (em apps corporativos, isso pode exigir aprovação do administrador).

Passo 2: escolha um modo de conexão

Recomendado: modo WebSocket

Use o modo WebSocket quando o Hermes roda no seu notebook, na sua estação de trabalho ou em um servidor privado. Nenhuma URL pública é necessária. O SDK oficial do Lark abre e mantém uma conexão WebSocket de saída persistente, com reconexão automática.

FEISHU_CONNECTION_MODE=websocket

Requisitos: o pacote Python websockets precisa estar instalado. O SDK cuida internamente do ciclo de vida da conexão, dos heartbeats e da reconexão automática.

Como funciona: o adaptador roda o cliente WebSocket do SDK do Lark em uma thread de executor em segundo plano. Os eventos de entrada (mensagens, reações, ações de card) são despachados para o laço principal do asyncio. Ao cair a conexão, o SDK tenta reconectar automaticamente.

Opcional: modo webhook

Use o modo webhook só quando você já roda o Hermes por trás de um endpoint HTTP alcançável.

FEISHU_CONNECTION_MODE=webhook

No modo webhook, o Hermes sobe um servidor HTTP (via aiohttp) e serve um endpoint do Feishu em:

/feishu/webhook

Requisitos: o pacote Python aiohttp precisa estar instalado.

Você pode personalizar o endereço de escuta e o caminho do servidor de webhook:

FEISHU_WEBHOOK_HOST=127.0.0.1   # padrão: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # padrão: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # padrão: /feishu/webhook

Quando o Feishu envia um desafio de verificação de URL (type: url_verification), o webhook responde automaticamente, então você consegue concluir a configuração da assinatura no console de desenvolvedor do Feishu. A resposta ao desafio é condicionada ao FEISHU_VERIFICATION_TOKEN quando ele está definido — pedidos de desafio com token ausente ou divergente são rejeitados, para que um remoto não autenticado não consiga provar controle do endpoint apenas repetindo dados de desafio controlados por ele.

Passo 3: configure o Hermes

Opção A: configuração interativa

hermes gateway setup

Selecione Feishu / Lark e responda às perguntas.

Opção B: configuração manual

Acrescente o seguinte ao ~/.hermes/.env:

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# Opcional, mas fortemente recomendado
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

O FEISHU_DOMAIN aceita:

• feishu para o Feishu da China
• lark para o Lark internacional

Passo 4: suba o gateway

hermes gateway

Depois mande mensagem para o bot pelo Feishu/Lark para confirmar que a conexão está viva.

Chat casa

Use /set-home em um chat do Feishu/Lark para marcá-lo como canal casa dos resultados de tarefas cron e das notificações entre plataformas.

Você também pode pré-configurar isso:

FEISHU_HOME_CHANNEL=oc_xxx

Segurança

Lista de permissão de usuários

Para uso em produção, defina uma lista de permissão de Open IDs do Feishu:

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

Se você deixar a lista de permissão vazia, qualquer pessoa que alcance o bot pode conseguir usá-lo. Em grupos, a lista de permissão é conferida contra o open_id do remetente antes de a mensagem ser processada.

Chave de criptografia do webhook

Ao rodar no modo webhook, defina uma chave de criptografia para habilitar a verificação de assinatura dos payloads de webhook de entrada:

FEISHU_ENCRYPT_KEY=sua-chave-de-criptografia

Essa chave fica na seção Event Subscriptions da configuração do seu app do Feishu. Quando definida, o adaptador verifica cada pedido de webhook usando o algoritmo de assinatura:

SHA256(timestamp + nonce + encrypt_key + body)

O hash calculado é comparado com o cabeçalho x-lark-signature usando comparação de tempo constante. Pedidos com assinatura inválida ou ausente são rejeitados com HTTP 401.

dica

No modo WebSocket, a verificação de assinatura é feita pelo próprio SDK, então o FEISHU_ENCRYPT_KEY é opcional. No modo webhook, é fortemente recomendado em produção.

Token de verificação

Uma camada extra de autenticação, que confere o campo token dentro dos payloads de webhook:

FEISHU_VERIFICATION_TOKEN=seu-token-de-verificacao

Esse token também fica na seção Event Subscriptions do seu app do Feishu. Quando definido, todo payload de webhook de entrada precisa conter um token correspondente no seu objeto header. Tokens divergentes são rejeitados com HTTP 401.

O FEISHU_ENCRYPT_KEY e o FEISHU_VERIFICATION_TOKEN podem ser usados juntos, como defesa em profundidade.

Política de mensagens em grupo

A variável de ambiente FEISHU_GROUP_POLICY controla se e como o Hermes responde em grupos:

FEISHU_GROUP_POLICY=allowlist   # padrão

Valor	Comportamento
open	O Hermes responde a menções de qualquer usuário em qualquer grupo.
allowlist	O Hermes só responde a menções de usuários listados em FEISHU_ALLOWED_USERS.
disabled	O Hermes ignora todas as mensagens de grupo.

Em todos os modos, o bot precisa ser mencionado explicitamente com @ (ou @all) no grupo antes de a mensagem ser processada. Mensagens diretas sempre passam direto por esse controle.

Defina FEISHU_REQUIRE_MENTION=false para o Hermes ler todo o tráfego do grupo sem exigir menção:

FEISHU_REQUIRE_MENTION=false

Para controle por chat, defina require_mention em uma entrada de group_rules — veja Controle de acesso por grupo abaixo.

Identidade do bot

O Hermes detecta automaticamente o open_id e o nome de exibição do bot na inicialização. Você só precisa definir isso na mão quando a detecção automática não consegue alcançar a API do Feishu, ou quando o seu app usa IDs de usuário no escopo do tenant:

FEISHU_BOT_OPEN_ID=ou_xxx     # só quando a detecção automática falha
FEISHU_BOT_USER_ID=xxx        # obrigatório se o seu app usa sender_id_type=user_id
FEISHU_BOT_NAME=MyBot         # só quando a detecção automática falha

Mensagens entre bots

Por padrão, o Hermes ignora mensagens enviadas por outros bots. Habilite mensagens entre bots quando você quiser que o Hermes participe de orquestração A2A ou receba notificações de outros bots no mesmo grupo.

FEISHU_ALLOW_BOTS=mentions   # padrão: none

Valor	Comportamento
none	Ignora todas as mensagens de outros bots (padrão).
mentions	Aceita apenas quando o bot parceiro menciona o Hermes com @.
all	Aceita toda mensagem de bot parceiro.

Também configurável como feishu.allow_bots no config.yaml (a variável de ambiente vence quando os dois estão definidos).

Bots parceiros não precisam ser adicionados ao FEISHU_ALLOWED_USERS — aquela lista de permissão vale só para remetentes humanos.

Conceda o escopo application:bot.basic_info:read para exibir os nomes dos bots parceiros; sem ele, os bots parceiros continuam roteando corretamente, mas aparecem pelo seu open_id.

Ações de card interativo

Quando os usuários clicam em botões ou interagem com cards interativos enviados pelo bot, o adaptador roteia isso como eventos sintéticos de comando /card:

• Cliques em botão viram: /card button {"key": "value", ...}
• O payload value da ação, vindo da definição do card, é incluído como JSON.
• Ações de card são deduplicadas com uma janela de 15 minutos, para evitar processamento duplicado.

Os pedidos de atualização iniciados pelo gateway usam um card nativo do Feishu com Yes / No, em vez de recorrer a respostas em texto puro. Quando o hermes update --gateway precisa de confirmação, o adaptador registra a resposta escolhida no arquivo .update_response do Hermes e substitui o card ali mesmo por um estado resolvido.

Eventos de ação de card são despachados com MessageType.COMMAND, então percorrem o pipeline normal de processamento de comandos.

É assim também que funciona a aprovação de comandos — quando o agente precisa rodar um comando perigoso, ele envia um card interativo com os botões Allow Once / Session / Always / Deny. O usuário clica em um botão, e o callback da ação do card entrega a decisão de aprovação de volta ao agente.

Configuração obrigatória no app do Feishu

Cards interativos exigem três passos de configuração no Console de Desenvolvedor do Feishu. Se qualquer um deles faltar, o erro 200340 aparece quando os usuários clicam nos botões do card.

1. Assine o evento de ação de card: Em Event Subscriptions, adicione card.action.trigger aos eventos assinados.

2. Habilite a capacidade de Card Interativo: Em App Features > Bot, confirme que a chave Interactive Card está habilitada. Isso avisa ao Feishu que o seu app pode receber callbacks de ação de card.

3. Configure a Card Request URL (só no modo webhook): Em App Features > Bot > Message Card Request URL, defina a URL como o mesmo endpoint do seu webhook de eventos (por exemplo, https://seu-servidor:8765/feishu/webhook). No modo WebSocket, o SDK cuida disso automaticamente.

aviso

Sem os três passos, o Feishu vai enviar cards interativos com sucesso (o envio só exige a permissão im:message:send), mas clicar em qualquer botão devolve o erro 200340. O card parece funcionar — o erro só aparece quando um usuário interage com ele.

Resposta inteligente a comentários em documentos

Além do chat, o adaptador também pode responder a menções com @ deixadas em documentos do Feishu/Lark. Quando um usuário comenta em um documento (seleção local de texto ou comentário do documento inteiro) e menciona o bot com @, o Hermes lê o documento mais a thread de comentários ao redor e publica uma resposta da LLM ali mesmo na thread.

Movido pelo evento drive.notice.comment_add_v1, o handler:

• Busca em paralelo o conteúdo do documento e a linha do tempo dos comentários (20 mensagens em threads de documento inteiro, 12 em threads de seleção local).
• Roda o agente com os conjuntos de ferramentas feishu_doc + feishu_drive restritos àquela única sessão de comentário.
• Fatia as respostas em pedaços de 4000 caracteres e as publica de volta como respostas encadeadas.
• Guarda em cache as sessões por documento por 1 hora, com limite de 50 mensagens, para que comentários subsequentes no mesmo documento mantenham o contexto.

Controle de acesso em 3 camadas

Respostas a comentários em documentos são somente por concessão explícita — não existe modo implícito de liberar para todos. As permissões são resolvidas nesta ordem (a primeira que casar vence, por campo):

1. Documento exato — regra restrita a um token de documento específico.
2. Curinga — regra que casa com um padrão de documentos.
3. Nível superior — regra padrão para o espaço de trabalho.

Duas políticas estão disponíveis por regra:

• allowlist — uma lista estática de usuários / tenants.
• pairing — lista estática ∪ repositório aprovado em tempo de execução. Útil em implantações graduais, em que os moderadores podem conceder acesso ao vivo.

As regras ficam em ~/.hermes/feishu_comment_rules.json (as concessões de pareamento em ~/.hermes/feishu_comment_pairing.json), com recarga a quente em cache por mtime — as edições passam a valer no próximo evento de comentário, sem reiniciar o gateway.

CLI:

# Inspecione as regras atuais e o estado do pareamento
python -m gateway.platforms.feishu_comment_rules status

# Simule uma checagem de acesso para um documento + usuário específicos
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>

# Administre as concessões de pareamento em tempo de execução
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add <user_open_id>
python -m gateway.platforms.feishu_comment_rules pairing remove <user_open_id>

Configuração obrigatória no app do Feishu

Além das permissões de chat/card já concedidas, adicione o evento de comentário do drive:

• Assine drive.notice.comment_add_v1 em Event Subscriptions.
• Conceda os escopos docs:doc:readonly e drive:drive:readonly para o handler poder ler o conteúdo do documento.

Eventos de convite para reunião

Você pode convidar o bot Hermes do Feishu/Lark para uma reunião por vídeo do mesmo jeito que convida um participante humano. Quando o bot recebe o evento de convite para a reunião, o Hermes pode iniciar automaticamente um turno do agente que tenta entrar na reunião.

Movido pelo evento vc.bot.meeting_invited_v1, o fluxo é:

• Um usuário convida o bot para uma reunião por vídeo do Feishu/Lark.
• O Feishu/Lark manda ao Hermes o evento de convite para a reunião.
• O Hermes extrai quem convidou, o tema da reunião e o número da reunião.
• Se quem convidou está autorizado pela lista de permissão normal do gateway ou pela política de pareamento, o agente recebe o número da reunião e tenta entrar automaticamente.
• Se o convite está malformado, ou se o agente não consegue entrar, o Hermes descarta o evento ou responde a quem convidou com uma explicação curta.

Convites malformados que não incluem tanto quem convidou quanto um meeting_no são ignorados.

Configuração obrigatória no app do Feishu

Além das permissões de chat/card já concedidas, adicione o evento de convite para reunião por vídeo:

• Assine vc.bot.meeting_invited_v1 em Event Subscriptions.
• Habilite o escopo de permissão de Videoconferência que o console de desenvolvedor do Feishu/Lark pedir para esse evento.
• Mantenha im:message e im:message:send_as_bot habilitados para o Hermes poder responder a quem convidou.
• Garanta que a lista de permissão de usuários do gateway ou a política de pareamento autorize quem convidou. Convites para reunião não passam por cima das checagens normais de acesso do gateway.

Suporte a mídia

Entrada (recebimento)

O adaptador recebe e guarda em cache os seguintes tipos de mídia enviados pelos usuários:

Tipo	Extensões	Como é processado
Imagens	.jpg, .jpeg, .png, .gif, .webp, .bmp	Baixadas pela API do Feishu e guardadas em cache local
Áudio	.ogg, .mp3, .wav, .m4a, .aac, .flac, .opus, .webm	Baixado e guardado em cache; arquivos de texto pequenos são extraídos automaticamente
Vídeo	.mp4, .mov, .avi, .mkv, .webm, .m4v, .3gp	Baixado e guardado em cache como documento
Arquivos	.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx e outros	Baixados e guardados em cache como documentos

Mídia de mensagens de texto rico (post), incluindo imagens embutidas e anexos de arquivo, também é extraída e guardada em cache.

Para documentos pequenos baseados em texto (.txt, .md), o conteúdo do arquivo é injetado automaticamente no texto da mensagem, para o agente ler diretamente sem precisar de ferramentas.

Saída (envio)

Método	O que envia
send	Mensagens de texto ou de post rico (detectado automaticamente pelo conteúdo markdown)
send_image / send_image_file	Sobe a imagem para o Feishu e a envia como bolha nativa de imagem (com legenda opcional)
send_document	Sobe o arquivo para a API do Feishu e o envia como anexo
send_voice	Sobe o arquivo de áudio como anexo de arquivo do Feishu
send_video	Sobe o vídeo e o envia como mensagem de mídia nativa
send_animation	GIFs são rebaixados a anexos de arquivo (o Feishu não tem bolha nativa de GIF)

O roteamento do upload de arquivo é automático, conforme a extensão:

• .ogg, .opus → enviados como áudio opus
• .mp4, .mov, .avi, .m4v → enviados como mídia mp4
• .pdf, .doc(x), .xls(x), .ppt(x) → enviados com o seu tipo de documento
• Todo o resto → enviado como arquivo de stream genérico

Renderização de markdown e recuo para post

Quando o texto de saída contém formatação markdown (títulos, negrito, listas, blocos de código, links etc.), o adaptador o envia automaticamente como uma mensagem de post do Feishu, com uma tag md embutida, em vez de texto puro. Isso habilita a renderização rica no cliente do Feishu.

Se a API do Feishu rejeitar o payload de post (por exemplo, por construções markdown não suportadas), o adaptador recua automaticamente para o envio em texto puro, sem o markdown. Esse recuo em dois estágios garante que as mensagens sejam sempre entregues.

Mensagens de texto puro (sem markdown detectado) são enviadas como o tipo simples de mensagem text.

Reações de status de processamento

Enquanto o agente trabalha, o bot mostra uma reação Typing na sua mensagem. Ela é removida quando a resposta chega, ou substituída por CrossMark se o processamento falhou.

Defina FEISHU_REACTIONS=false para desligar isso.

Proteção contra rajadas e agrupamento

O adaptador tem debounce para rajadas rápidas de mensagens, para não sobrecarregar o agente:

Agrupamento de texto

Quando um usuário envia várias mensagens de texto em sequência rápida, elas são unidas em um único evento antes do despacho:

Ajuste	Variável de ambiente	Padrão
Período de silêncio	HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS	0,6s
Máximo de mensagens por lote	HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES	8
Máximo de caracteres por lote	HERMES_FEISHU_TEXT_BATCH_MAX_CHARS	4000

Agrupamento de mídia

Vários anexos de mídia enviados em sequência rápida (por exemplo, arrastando várias imagens) são unidos em um único evento:

Ajuste	Variável de ambiente	Padrão
Período de silêncio	HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS	0,8s

Serialização por chat

Mensagens dentro do mesmo chat são processadas em série (uma por vez), para manter a coerência da conversa. Cada chat tem o seu próprio lock, então mensagens de chats diferentes são processadas em paralelo.

Limite de taxa (modo webhook)

No modo webhook, o adaptador aplica limite de taxa por IP para se proteger de abuso:

• Janela: janela deslizante de 60 segundos
• Limite: 120 pedidos por janela, por trio (app_id, caminho, IP)
• Teto de rastreamento: até 4096 chaves únicas rastreadas (evita crescimento ilimitado de memória)

Pedidos que passam do limite recebem HTTP 429 (Too Many Requests).

Rastreamento de anomalias no webhook

O adaptador acompanha respostas de erro consecutivas por endereço IP. Depois de 25 erros consecutivos do mesmo IP dentro de uma janela de 6 horas, um aviso é registrado no log. Isso ajuda a detectar clientes mal configurados ou tentativas de sondagem.

Proteções adicionais do webhook:

• Limite de tamanho do corpo: 1 MB no máximo
• Timeout de leitura do corpo: 30 segundos
• Exigência de Content-Type: só application/json é aceito

Ajuste fino do WebSocket

Ao usar o modo websocket, você pode personalizar o comportamento de reconexão e de ping:

platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120   # Segundos entre tentativas de reconexão (padrão: 120)
      ws_ping_interval: 30         # Segundos entre pings do WebSocket (opcional; padrão do SDK se não definido)

Ajuste	Chave de configuração	Padrão	Descrição
Intervalo de reconexão	ws_reconnect_interval	120s	Quanto esperar entre tentativas de reconexão
Intervalo de ping	ws_ping_interval	(padrão do SDK)	Frequência dos pings de keepalive do WebSocket

Controle de acesso por grupo

Além do FEISHU_GROUP_POLICY global, você pode definir regras finas por grupo usando group_rules no config.yaml:

platforms:
  feishu:
    extra:
      default_group_policy: "open"     # Padrão para grupos que não estão em group_rules
      admins:                          # Usuários que podem administrar as configurações do bot
        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_group_chat_id_2":
          policy: "admin_only"
        "oc_group_chat_id_3":
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"
        "oc_free_chat":
          policy: "open"
          require_mention: false       # sobrepõe FEISHU_REQUIRE_MENTION para este chat

Política	Descrição
open	Qualquer pessoa do grupo pode usar o bot
allowlist	Só usuários na allowlist do grupo podem usar o bot
blacklist	Todos, menos os usuários na blacklist do grupo, podem usar o bot
admin_only	Só usuários na lista global de admins podem usar o bot neste grupo
disabled	O bot ignora todas as mensagens deste grupo

Defina require_mention: false em uma entrada de group_rules para pular a exigência de menção com @ naquele chat específico. Quando omitido, o chat herda o valor global de FEISHU_REQUIRE_MENTION.

Grupos que não estão listados em group_rules recorrem ao default_group_policy (que por padrão vale o valor de FEISHU_GROUP_POLICY).

Deduplicação

Mensagens de entrada são deduplicadas por ID de mensagem, com TTL de 24 horas. O estado de deduplicação é persistido entre reinícios em ~/.hermes/feishu_seen_message_ids.json.

Ajuste	Variável de ambiente	Padrão
Tamanho do cache	HERMES_FEISHU_DEDUP_CACHE_SIZE	2048 entradas

Todas as variáveis de ambiente

Variável	Obrigatória	Padrão	Descrição
FEISHU_APP_ID	✅	—	App ID do Feishu/Lark
FEISHU_APP_SECRET	✅	—	App Secret do Feishu/Lark
FEISHU_DOMAIN	—	feishu	feishu (China) ou lark (internacional)
FEISHU_CONNECTION_MODE	—	websocket	websocket ou webhook
FEISHU_ALLOWED_USERS	—	(vazio)	Lista de open_id separada por vírgula, para a lista de permissão de usuários
FEISHU_ALLOW_BOTS	—	none	Aceitar mensagens de outros bots: none, mentions ou all
FEISHU_REQUIRE_MENTION	—	true	Se as mensagens de grupo precisam mencionar o bot com @
FEISHU_HOME_CHANNEL	—	—	ID do chat para a saída de cron/notificações
FEISHU_ENCRYPT_KEY	—	(vazio)	Chave de criptografia para a verificação de assinatura do webhook
FEISHU_VERIFICATION_TOKEN	—	(vazio)	Token de verificação para autenticar o payload do webhook
FEISHU_GROUP_POLICY	—	allowlist	Política de mensagens em grupo: open, allowlist, disabled
FEISHU_BOT_OPEN_ID	—	(vazio)	open_id do bot (para detecção de menção)
FEISHU_BOT_USER_ID	—	(vazio)	user_id do bot (para detecção de menção)
FEISHU_BOT_NAME	—	(vazio)	Nome de exibição do bot (para detecção de menção)
FEISHU_WEBHOOK_HOST	—	127.0.0.1	Endereço de escuta do servidor de webhook
FEISHU_WEBHOOK_PORT	—	8765	Porta do servidor de webhook
FEISHU_WEBHOOK_PATH	—	/feishu/webhook	Caminho do endpoint do webhook
HERMES_FEISHU_DEDUP_CACHE_SIZE	—	2048	Máximo de IDs de mensagem deduplicados a rastrear
HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS	—	0.6	Período de silêncio do debounce de rajada de texto
HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES	—	8	Máximo de mensagens unidas por lote de texto
HERMES_FEISHU_TEXT_BATCH_MAX_CHARS	—	4000	Máximo de caracteres unidos por lote de texto
HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS	—	0.8	Período de silêncio do debounce de rajada de mídia

Os ajustes de WebSocket e de ACL por grupo são configurados pelo config.yaml, em platforms.feishu.extra (veja Ajuste fino do WebSocket e Controle de acesso por grupo acima).

Solução de problemas

Problema	Solução
lark-oapi not installed	Instale o SDK: pip install lark-oapi
websockets not installed; websocket mode unavailable	Instale o websockets: pip install websockets
aiohttp not installed; webhook mode unavailable	Instale o aiohttp: pip install aiohttp
FEISHU_APP_ID or FEISHU_APP_SECRET not set	Defina as duas variáveis de ambiente ou configure via hermes gateway setup
Another local Hermes gateway is already using this Feishu app_id	Só uma instância do Hermes pode usar o mesmo app_id por vez. Pare o outro gateway primeiro.
O bot não responde em grupos	Confirme que o bot foi mencionado com @, verifique o FEISHU_GROUP_POLICY e confira se o remetente está em FEISHU_ALLOWED_USERS quando a política é allowlist
Webhook rejected: invalid verification token	Confirme que o FEISHU_VERIFICATION_TOKEN bate com o token na configuração de Event Subscriptions do seu app do Feishu
Webhook rejected: invalid signature	Confirme que o FEISHU_ENCRYPT_KEY bate com a chave de criptografia na configuração do seu app do Feishu
Mensagens de post aparecem como texto puro	A API do Feishu rejeitou o payload de post; esse é o comportamento normal de recuo. Veja os logs para detalhes.
O bot não recebe imagens/arquivos	Conceda os escopos de permissão im:message e im:resource ao seu app do Feishu
Identidade do bot não detectada automaticamente	Normalmente é um problema de rede passageiro ao alcançar o endpoint de informações do bot do Feishu. Como contorno, defina FEISHU_BOT_OPEN_ID e FEISHU_BOT_NAME na mão.
Mensagens de bot parceiro continuam ignoradas depois de habilitar FEISHU_ALLOW_BOTS	O Hermes ainda não consegue se identificar — defina FEISHU_BOT_OPEN_ID (e FEISHU_BOT_USER_ID, se o seu app usa sender_id_type=user_id).
Bots parceiros aparecem como ou_xxxxxx em vez do nome	Conceda o escopo application:bot.basic_info:read.
Erro 200340 ao clicar nos botões de aprovação	Habilite a capacidade Interactive Card e configure a Card Request URL no Console de Desenvolvedor do Feishu. Veja Configuração obrigatória no app do Feishu acima.
Webhook rate limit exceeded	Mais de 120 pedidos por minuto do mesmo IP. Normalmente é má configuração ou um laço.

Conjunto de ferramentas

O Feishu / Lark usa o preset de plataforma hermes-feishu, que inclui as mesmas ferramentas centrais do Telegram e das outras plataformas de mensagem baseadas em gateway.

---