Feishu

​

Início rápido

openclaw channels login --channel feishu

openclaw gateway restart

​

Controle de acesso

​

Mensagens diretas

• "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

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

​

Chats em grupo

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

{
  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)

​

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

openclaw logs --follow

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

​

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

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

​

Otimização de cota

• 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

​

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

/acp spawn codex --thread here

​

Roteamento multiagente

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

• 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)

​

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

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

​

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

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

• {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: {
    // 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

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

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

​

Tipos de mensagem compatíveis

​

Receber

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

​

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)

​

Threads e respostas

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

​

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