Feishu

Feishu/Lark é uma plataforma de colaboração completa em que equipes conversam, compartilham documentos, gerenciam calendários e trabalham juntas.

Status: pronto para produção para DMs de bot + chats em grupo. WebSocket é o modo padrão; o modo webhook é opcional.

Início rápido

openclaw channels login --channel feishu

openclaw gateway restart

Controle de acesso

Mensagens diretas

Configure dmPolicy para controlar quem pode enviar DM ao bot:

• "pairing" - usuários desconhecidos recebem um código de pareamento; aprove via CLI
• "allowlist" - somente usuários listados em allowFrom podem conversar
• "open" - permite DMs públicas somente quando allowFrom inclui "*"; com entradas restritivas, somente usuários correspondentes podem conversar

Aprovar uma solicitação de pareamento:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Chats em grupo

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

Padrão: allowlist

Exigência de menção (channels.feishu.requireMention):

• true - exigir @menção (padrão)
• false - responder sem @menção
• Substituição por grupo: channels.feishu.groups.<chat_id>.requireMention
• @all e @_all somente para transmissão não são tratados como menções ao bot. Uma mensagem que menciona @all e também o bot diretamente ainda conta como menção ao bot.

Exemplos de configuração de grupo

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

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

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

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

Permitir somente grupos específicos

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Group IDs look like: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

No modo allowlist, você também pode admitir um grupo adicionando uma entrada explícita groups.<chat_id>. Entradas explícitas não substituem groupPolicy: "disabled". Padrões curinga em groups.* configuram grupos correspondentes, mas não admitem grupos por si só.

{  channels: {    feishu: {      groupPolicy: "allowlist",      groups: {        oc_xxx: {          requireMention: false,        },      },    },  },}

Restringir remetentes dentro de um grupo

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // User open_ids look like: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

Obter IDs de grupo/usuário

IDs de grupo (chat_id, formato: oc_xxx)

Abra o grupo no Feishu/Lark, clique no ícone de menu no canto superior direito e acesse Configurações. O ID do grupo (chat_id) é listado na página de configurações.

IDs de usuário (open_id, formato: ou_xxx)

Inicie o gateway, envie uma DM para o bot e então verifique os logs:

openclaw logs --follow

Procure por open_id na saída do log. Você também pode verificar solicitações de pareamento pendentes:

openclaw pairing list feishu

Comandos comuns

Solução de problemas

O bot não responde em chats em grupo

1. Verifique se o bot foi adicionado ao grupo
2. Verifique se você @menciona o bot (exigido por padrão)
3. Verifique se groupPolicy não é "disabled"
4. Verifique os logs: openclaw logs --follow

O bot não recebe mensagens

1. Verifique se o bot está publicado e aprovado no Feishu Open Platform / Lark Developer
2. Verifique se a assinatura de eventos inclui im.message.receive_v1
3. Verifique se conexão persistente (WebSocket) está selecionada
4. Verifique se todos os escopos de permissão necessários foram concedidos
5. Verifique se o gateway está em execução: openclaw gateway status
6. Verifique os logs: openclaw logs --follow

A configuração por QR não reage no app móvel do Feishu

1. Execute a configuração novamente: openclaw channels login --channel feishu
2. Escolha configuração manual
3. No Feishu Open Platform, crie um app autoconstruído e copie seu App ID e App Secret
4. Cole essas credenciais no assistente de configuração

App Secret vazou

1. Redefina o App Secret no Feishu Open Platform / Lark Developer
2. Atualize o valor na sua configuração
3. Reinicie o gateway: openclaw gateway restart

Configuração avançada

Várias contas

{  channels: {    feishu: {      defaultAccount: "main",      accounts: {        main: {          appId: "cli_xxx",          appSecret: "xxx",          name: "Primary bot",          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },        backup: {          appId: "cli_yyy",          appSecret: "yyy",          name: "Backup bot",          enabled: false,        },      },    },  },}

defaultAccount controla qual conta é usada quando APIs de saída não especificam um accountId. accounts.<id>.tts usa o mesmo formato de messages.tts e faz mesclagem profunda sobre a configuração global de TTS, para que configurações Feishu com vários bots possam manter credenciais compartilhadas de provedor globalmente enquanto substituem apenas voz, modelo, persona ou modo automático por conta.

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: 30 MB)

Streaming

Feishu/Lark oferece suporte a respostas em streaming por meio de cartões interativos. Quando ativado, o bot atualiza o cartão em tempo real enquanto gera texto.

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

Defina streaming: false para enviar a resposta completa em uma mensagem. blockStreaming fica desativado por padrão; ative-o somente quando quiser que blocos concluídos do assistente sejam enviados antes da resposta final.

Otimização de cota

Reduza o número de chamadas à API do Feishu/Lark com dois sinalizadores opcionais:

• typingIndicator (padrão true): defina como false para ignorar chamadas de reação de digitação
• resolveSenderNames (padrão true): defina como false para ignorar buscas de perfil do remetente

{  channels: {    feishu: {      typingIndicator: false,      resolveSenderNames: false,    },  },}

Sessões ACP

Feishu/Lark oferece suporte a ACP para DMs e mensagens de thread de grupo. O ACP do Feishu/Lark é orientado por comandos de texto - não há menus nativos de comandos com barra, então use mensagens /acp ... diretamente na conversa.

Vinculação ACP persistente

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

Gerar ACP a partir do chat

Em uma DM ou thread do Feishu/Lark:

/acp spawn codex --thread here

--thread here funciona para DMs e mensagens de thread do Feishu/Lark. Mensagens de acompanhamento na conversa vinculada são roteadas diretamente para essa sessão ACP.

Roteamento multiagente

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

{  agents: {    list: [      { id: "main" },      { id: "agent-a", workspace: "/home/user/agent-a" },      { id: "agent-b", workspace: "/home/user/agent-b" },    ],  },  bindings: [    {      agentId: "agent-a",      match: {        channel: "feishu",        peer: { kind: "direct", id: "ou_xxx" },      },    },    {      agentId: "agent-b",      match: {        channel: "feishu",        peer: { kind: "group", id: "oc_zzz" },      },    },  ],}

Campos de roteamento:

• match.channel: "feishu"
• match.peer.kind: "direct" (DM) ou "group" (chat em grupo)
• match.peer.id: Open ID do usuário (ou_xxx) ou ID do grupo (oc_xxx)

Consulte Obter IDs de grupo/usuário para dicas de consulta.

Isolamento de agente por usuário (Criação dinâmica de agentes)

Ative dynamicAgentCreation para criar automaticamente instâncias de agente isoladas para cada usuário de DM. Cada usuário recebe seu próprio:

• Diretório de workspace independente
• USER.md / SOUL.md / MEMORY.md separados
• Histórico de conversa privado
• Skills e estado isolados

Isso é essencial para bots públicos em que você quer que cada usuário tenha sua própria experiência privada de assistente de IA.

Configuração rápida

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Critical: makes each user's DM their "main session"    // Automatically loads USER.md / SOUL.md / MEMORY.md    // For stronger isolation, use "per-channel-peer" instead    dmScope: "main",  },}

Como funciona

Quando um novo usuário envia sua primeira DM:

1. O canal gera um agentId exclusivo: feishu-{user_open_id} para a conta padrão, ou um resumo de identidade limitado com prefixo da conta para uma conta nomeada
2. Cria um novo workspace no caminho workspaceTemplate
3. Registra o agente e cria uma vinculação para este usuário
4. O auxiliar de workspace garante arquivos de inicialização (AGENTS.md, SOUL.md, USER.md etc.) no primeiro acesso
5. Roteia todas as mensagens futuras deste usuário para seu agente dedicado

Opções de configuração

Variáveis de modelo:

• {agentId} - o ID de agente gerado (por exemplo, feishu-ou_xxxxxx ou feishu-support-<identity_digest>)
• {userId} - o open_id do Feishu do remetente (por exemplo, ou_xxxxxx)

Escopo da sessão

session.dmScope controla como mensagens diretas são mapeadas para sessões de agente. Esta é uma configuração global que afeta todos os canais.

Tradeoff: Usar "main" habilita o carregamento automático de arquivos de bootstrap (USER.md, SOUL.md, MEMORY.md), mas significa que todas as DMs em todos os canais compartilham o mesmo padrão de chave de sessão. Para bots públicos multiusuário nos quais o isolamento importa mais do que o carregamento automático de bootstrap, considere "per-channel-peer" e gerencie os arquivos de bootstrap manualmente.

{  session: {    // For single-user personal bots: enables auto bootstrap loading    dmScope: "main",     // For public multi-user bots: stronger isolation    // dmScope: "per-channel-peer",  },}

Implantação multiusuário típica

{  channels: {    feishu: {      appId: "cli_xxx",      appSecret: "xxx",      dmPolicy: "open",      allowFrom: ["*"],      groupPolicy: "open",      requireMention: true,      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Choose dmScope based on your isolation needs:    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation    dmScope: "main",  },  bindings: [], // Empty - dynamic agents auto-bind}

Verificação

Verifique os logs do Gateway para confirmar que a criação dinâmica está funcionando:

feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxxworkspace: /Users/you/.openclaw/workspace-feishu-ou_xxxxxxfeishu: dynamic agent created, new route: agent:feishu-ou_xxxxxx:main

Liste todos os workspaces criados:

ls -la ~/.openclaw/workspace-*

Observações

• Isolamento de workspace: Cada usuário recebe seu próprio diretório de workspace e instância de agente. Usuários não conseguem ver o histórico de conversas nem os arquivos uns dos outros dentro do fluxo normal de mensagens.
• Limite de segurança: Este é um mecanismo de isolamento de contexto de mensagens, não um limite de segurança contra cotenants hostis. O processo do agente e o ambiente do host são compartilhados.
• bindings deve estar vazio: Agentes dinâmicos registram automaticamente suas próprias vinculações
• Caminho de upgrade: Vinculações manuais existentes continuam funcionando junto com agentes dinâmicos
• session.dmScope é global: Isso afeta todos os canais, não apenas o Feishu

Referência de configuração

Configuração completa: Configuração do Gateway

Tipos de mensagem compatíveis

Receber

• ✅ Texto
• ✅ Rich text (post)
• ✅ Imagens
• ✅ Arquivos
• ✅ Áudio
• ✅ Vídeo/mídia
• ✅ Stickers

Mensagens de áudio de entrada do Feishu/Lark são normalizadas como placeholders de mídia em vez de JSON file_key bruto. Quando tools.media.audio está configurado, o OpenClaw baixa o recurso de nota de voz e executa a transcrição de áudio compartilhada antes do turno do agente, para que o agente receba a transcrição falada. Se o Feishu incluir texto de transcrição diretamente no payload de áudio, esse texto será usado sem outra chamada de ASR. Sem um provedor de transcrição de áudio, o agente ainda recebe um placeholder <media:audio> mais o anexo salvo, não o payload bruto do recurso do Feishu.

Enviar

• ✅ Texto
• ✅ Imagens
• ✅ Arquivos
• ✅ Áudio
• ✅ Vídeo/mídia
• ✅ Cartões interativos (incluindo atualizações em streaming)
• ⚠️ Rich text (formatação no estilo de postagem; não oferece suporte a todos os recursos de autoria do Feishu/Lark)

Os balões de áudio nativos do Feishu/Lark usam o tipo de mensagem audio do Feishu e exigem mídia de upload Ogg/Opus (file_type: "opus"). Mídias .opus e .ogg existentes são enviadas diretamente como áudio nativo. MP3/WAV/M4A e outros formatos de áudio prováveis são transcodificados para Ogg/Opus a 48 kHz com ffmpeg somente quando a resposta solicita entrega por voz (audioAsVoice / ferramenta de mensagem asVoice, incluindo respostas de nota de voz TTS). Anexos MP3 comuns permanecem como arquivos normais. Se ffmpeg estiver ausente ou a conversão falhar, o OpenClaw recorre a um anexo de arquivo e registra o motivo.

Threads e respostas

• ✅ Respostas inline
• ✅ Respostas em thread
• ✅ Respostas com mídia permanecem cientes da thread ao responder a uma mensagem em thread

Para groupSessionScope: "group_topic" e "group_topic_sender", grupos de tópicos nativos do Feishu/Lark usam o thread_id (omt_*) do evento como a chave canônica da sessão de tópico. Se um evento iniciador de tópico nativo omitir thread_id, o OpenClaw o hidrata a partir do Feishu antes de rotear o turno. Respostas normais de grupo que o OpenClaw transforma em threads continuam usando o ID da mensagem raiz de resposta (om_*) para que o primeiro turno e o turno de acompanhamento permaneçam na mesma sessão.

Relacionados

• Visão geral dos canais - todos os canais compatíveis
• Pareamento - autenticação por DM e fluxo de pareamento
• Grupos - comportamento de chat em grupo e controle por menção
• Roteamento de canais - roteamento de sessão para mensagens
• Segurança - modelo de acesso e endurecimento