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)

Visão geral

Plataformas de mensagens

Configuração

​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

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