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 WebSocket da plataforma, para que as mensagens possam ser recebidas sem expor uma URL pública de webhook.

Plugin necessário

Instale o plugin Feishu:

openclaw plugins install @openclaw/feishu

Checkout local (ao executar a partir de um repositório git):

openclaw plugins install ./extensions/feishu

Início rápido

Há duas maneiras de adicionar o canal Feishu:

Método 1: assistente de onboarding (recomendado)

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

openclaw onboard

O assistente guia você por:

Criar um app Feishu e coletar credenciais
Configurar as credenciais do app no OpenClaw
Iniciar o gateway

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

openclaw gateway status
openclaw logs --follow

Método 2: configuração da CLI

Se você já concluiu a instalação inicial, adicione o canal via CLI:

openclaw channels add

Escolha Feishu e, em seguida, informe o App ID e o App Secret. ✅ Após a configuração, gerencie o gateway:

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

Etapa 1: Criar um app Feishu

1. Abrir o Feishu Open Platform

Acesse o 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. Criar um app

Clique em Create enterprise app
Preencha o nome e a descrição do app
Escolha um ícone para o app

3. Copiar credenciais

Em Credentials & Basic Info, copie:

App ID (formato: cli_xxx)
Segredo do aplicativo

❗ Importante: mantenha o App Secret em sigilo. Get credentials

4. Configurar 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",
      "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. Ativar a capacidade de bot

Em App Capability > Bot:

Ative a capacidade de bot
Defina o nome do bot

6. Configurar assinatura de eventos

⚠️ Importante: antes de configurar a assinatura de eventos, certifique-se de que:

Você já executou openclaw channels add para o Feishu
O gateway está em execução (openclaw gateway status)

Em Event Subscription:

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

⚠️ Se o gateway não estiver em execução, a configuração de conexão longa pode falhar ao salvar. Configure event subscription

7. Publicar o app

Crie uma versão em Version Management & Release
Envie para revisão e publique
Aguarde a aprovação do administrador (apps corporativos geralmente são aprovados automaticamente)

Etapa 2: Configurar o OpenClaw

Configurar com o assistente (recomendado)

openclaw channels add

Escolha Feishu e cole seu App ID e App Secret.

Configurar 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",
        },
      },
    },
  },
}

Configurar via variáveis de ambiente

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

Domínio Lark (global)

Se o seu tenant estiver no Lark (internacional), defina o domínio como lark (ou uma string de domínio completa). Você pode definir isso em channels.feishu.domain ou por conta (channels.feishu.accounts.<id>.domain).

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

Etapa 3: Iniciar + testar

1. Iniciar o gateway

openclaw gateway

2. Enviar uma mensagem de teste

No Feishu, encontre seu bot e envie uma mensagem.

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

Chats em grupo

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

"open" = permitir todos nos grupos (padrão)
"allowlist" = permitir apenas groupAllowFrom
"disabled" = desativar mensagens em grupo

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

true = exigir @menção (padrão)
false = responder sem menções

Exemplos de configuração de grupos

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 usuários específicos em grupos

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["ou_xxx", "ou_yyy"],
    },
  },
}

Obter IDs de grupo/usuário

IDs de grupo (chat_id)

Os IDs de grupo têm o formato oc_xxx. Método 1 (recomendado)

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

Método 2 Use o depurador da API do Feishu para listar chats em grupo.

IDs de usuário (open_id)

Os IDs de usuário têm o formato ou_xxx. Método 1 (recomendado)

Inicie o gateway e envie uma DM ao bot
Execute openclaw logs --follow e procure por open_id

Método 2 Verifique solicitações de pareamento para Open IDs de usuários:

openclaw pairing list feishu

Comandos comuns

Comando	Descrição
`/status`	Mostrar status do bot
`/reset`	Redefinir a sessão
`/model`	Mostrar/trocar modelo

Nota: o Feishu ainda não oferece suporte a menus de comandos nativos, portanto os comandos devem ser enviados como texto.

Comandos de gerenciamento do gateway

Comando	Descrição
`openclaw gateway status`	Mostrar status do gateway
`openclaw gateway install`	Instalar/iniciar o serviço do gateway
`openclaw gateway stop`	Parar o serviço do gateway
`openclaw gateway restart`	Reiniciar o serviço do gateway
`openclaw logs --follow`	Acompanhar logs do gateway

Solução de problemas

O bot não responde em chats de grupo

Certifique-se de que o bot foi adicionado ao grupo
Certifique-se de @mencionar o bot (comportamento padrão)
Verifique se groupPolicy não está definido como "disabled"
Verifique os logs: openclaw logs --follow

O bot não recebe mensagens

Certifique-se de que o app está publicado e aprovado
Certifique-se de que a assinatura de eventos inclui im.message.receive_v1
Certifique-se de que a conexão longa está habilitada
Certifique-se de que as permissões do app estão completas
Certifique-se de que o gateway está em execução: openclaw gateway status
Verifique os logs: openclaw logs --follow

Vazamento do App Secret

Redefina o App Secret no Feishu Open Platform
Atualize o App Secret na sua configuração
Reinicie o gateway

Falhas no envio de mensagens

Certifique-se de que o app possui a permissão im:message:send_as_bot
Certifique-se de que o app está publicado
Verifique os logs para erros detalhados

Configuração avançada

Múltiplas contas

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

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

Streaming

O Feishu oferece suporte a respostas em streaming via cartões interativos. Quando habilitado, o bot atualiza um cartão 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" or "group"
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.

Referência de configuração

Configuração completa: Configuração do Gateway Opções principais:

Configuração	Descrição	Padrão
`channels.feishu.enabled`	Ativar/desativar canal	`true`
`channels.feishu.domain`	Domínio da API (`feishu` ou `lark`)	`feishu`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	Substituição de domínio da API por conta	`feishu`
`channels.feishu.dmPolicy`	Política de DM	`pairing`
`channels.feishu.allowFrom`	Lista de permissões de DM (lista de open_id)	-
`channels.feishu.groupPolicy`	Política de grupo	`open`
`channels.feishu.groupAllowFrom`	Lista de permissões de grupo	-
`channels.feishu.groups.<chat_id>.requireMention`	Exigir @mention	`true`
`channels.feishu.groups.<chat_id>.enabled`	Ativar grupo	`true`
`channels.feishu.textChunkLimit`	Tamanho do bloco de mensagem	`2000`
`channels.feishu.mediaMaxMb`	Limite de tamanho de mídia	`30`
`channels.feishu.streaming`	Ativar saída de cartão em streaming	`true`
`channels.feishu.blockStreaming`	Ativar streaming em blocos	`true`

Referência dmPolicy

Valor	Comportamento
`"pairing"`	Padrão. Usuários desconhecidos recebem um código de pareamento; devem ser aprovados
`"allowlist"`	Apenas usuários em `allowFrom` podem conversar
`"open"`	Permitir todos os usuários (requer `"*"` em allowFrom)
`"disabled"`	Desativar DMs

Tipos de mensagem suportados

Receber

✅ Texto
✅ Texto rico (post)
✅ Imagens
✅ Arquivos
✅ Áudio
✅ Vídeo
✅ Stickers

Enviar

✅ Texto
✅ Imagens
✅ Arquivos
✅ Áudio
⚠️ Texto rico (suporte parcial)

​Bot Feishu

​Plugin necessário

​Início rápido

​Método 1: assistente de onboarding (recomendado)

​Método 2: configuração da CLI

​Etapa 1: Criar um app Feishu

​1. Abrir o Feishu Open Platform

​2. Criar um app

​3. Copiar credenciais

​4. Configurar permissões

​5. Ativar a capacidade de bot

​6. Configurar assinatura de eventos

​7. Publicar o app

​Etapa 2: Configurar o OpenClaw

​Configurar com o assistente (recomendado)

​Configurar via arquivo de configuração

​Configurar via variáveis de ambiente

​Domínio Lark (global)

​Etapa 3: Iniciar + testar

​1. Iniciar o gateway

​2. Enviar uma mensagem de teste

​3. Aprovar pareamento

​Visão geral

​Controle de acesso

​Mensagens diretas

​Chats em grupo

​Exemplos de configuração de grupos

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

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

​Permitir apenas usuários específicos em grupos

​Obter IDs de grupo/usuário

​IDs de grupo (chat_id)

​IDs de usuário (open_id)

​Comandos comuns

​Comandos de gerenciamento do gateway

​Solução de problemas

​O bot não responde em chats de grupo

​O bot não recebe mensagens

​Vazamento do App Secret

​Falhas no envio de mensagens

​Configuração avançada

​Múltiplas contas

​Limites de mensagem

​Streaming

​Roteamento multiagente

​Referência de configuração

​Referência dmPolicy

​Tipos de mensagem suportados

​Receber

​Enviar