Bot Feishu

Feishu (Lark) e una piattaforma di team chat usata dalle aziende per messaggistica e collaborazione. Questo plugin connette OpenClaw a un bot Feishu/Lark usando la sottoscrizione eventi WebSocket della piattaforma, cosi i messaggi possono essere ricevuti senza esporre un URL webhook pubblico.

Plugin incluso

Feishu e incluso nelle release attuali di OpenClaw, quindi non e necessaria un’installazione separata del plugin.

Se stai usando una build precedente o un’installazione personalizzata che non include Feishu, installalo manualmente:

openclaw plugins install @openclaw/feishu

Avvio rapido

Ci sono due modi per aggiungere il canale Feishu:

Metodo 1: procedura guidata di onboarding (consigliato)

Se hai appena installato OpenClaw, avvia la procedura guidata:

openclaw onboard

La procedura ti guida attraverso:

1. Creazione di un’app Feishu e raccolta delle credenziali
2. Configurazione delle credenziali dell’app in OpenClaw
3. Avvio del gateway

Nota: Dopo la configurazione, controlla lo stato del gateway:

• openclaw gateway status
• openclaw logs --follow

Metodo 2: setup via CLI

Se hai gia completato l’installazione iniziale, aggiungi il canale via CLI:

openclaw channels add

Scegli Feishu, poi inserisci App ID e App Secret.

Nota: Dopo la configurazione, gestisci il gateway:

• openclaw gateway status
• openclaw gateway restart
• openclaw logs --follow

Step 1: Crea un’app Feishu

1. Apri la Feishu Open Platform

Visita Feishu Open Platform e accedi.

I tenant Lark (globali) dovrebbero usare https://open.larksuite.com/app e impostare domain: "lark" nella configurazione Feishu.

2. Crea un’app

1. Clicca Create enterprise app
2. Compila nome + descrizione dell’app
3. Scegli un’icona per l’app

3. Copia le credenziali

Da Credentials & Basic Info, copia:

• App ID (formato: cli_xxx)
• App Secret

Attenzione: mantieni l’App Secret privato.

4. Configura i permessi

Su Permissions, clicca Batch import e incolla:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card: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. Abilita la funzionalita bot

In App Capability > Bot:

1. Abilita la funzionalita bot
2. Imposta il nome del bot

6. Configura la sottoscrizione eventi

Attenzione: prima di impostare la sottoscrizione eventi, assicurati che:

1. Tu abbia gia eseguito openclaw channels add per Feishu
2. Il gateway sia in esecuzione (openclaw gateway status)

In Event Subscription:

1. Scegli Use long connection to receive events (WebSocket)
2. Aggiungi l’evento: im.message.receive_v1

Attenzione: Se il gateway non e in esecuzione, il setup della connessione persistente potrebbe non riuscire a salvare.

7. Pubblica l’app

1. Crea una versione in Version Management & Release
2. Invia per la revisione e pubblica
3. Attendi l’approvazione dell’amministratore (le app aziendali di solito vengono approvate automaticamente)

Step 2: Configura OpenClaw

Configura con la procedura guidata (consigliato)

openclaw channels add

Scegli Feishu e incolla App ID + App Secret.

Configura tramite file di configurazione

Modifica ~/.openclaw/openclaw.json:

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "My AI assistant",
        },
      },
    },
  },
}

Se usi connectionMode: "webhook", imposta sia verificationToken che encryptKey. Il server webhook Feishu si associa a 127.0.0.1 per impostazione predefinita; imposta webhookHost solo se hai intenzionalmente bisogno di un indirizzo di bind diverso.

Verification Token e Encrypt Key (modalita webhook)

Quando usi la modalita webhook, imposta sia channels.feishu.verificationToken che channels.feishu.encryptKey nella tua configurazione. Per ottenere i valori:

1. Nella Feishu Open Platform, apri la tua app
2. Vai in Development → Events & Callbacks (开发配置 → 事件与回调)
3. Apri la scheda Encryption (加密策略)
4. Copia Verification Token e Encrypt Key

Lo screenshot qui sotto mostra dove trovare il Verification Token. L’Encrypt Key e nella stessa sezione Encryption.

Configura tramite variabili d’ambiente

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

Dominio Lark (globale)

Se il tuo tenant e su Lark (internazionale), imposta il dominio a lark (o una stringa di dominio completa). Puoi impostarlo in channels.feishu.domain o per account (channels.feishu.accounts.<id>.domain).

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

Flag di ottimizzazione quota

Puoi ridurre l’utilizzo delle API Feishu con due flag opzionali:

• typingIndicator (predefinito true): quando false, salta le chiamate di reazione typing.
• resolveSenderNames (predefinito true): quando false, salta le chiamate di lookup del profilo mittente.

Impostali a livello top-level o per account:

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

Step 3: Avvia e testa

1. Avvia il gateway

openclaw gateway

2. Invia un messaggio di test

In Feishu, trova il tuo bot e invia un messaggio.

3. Approva il pairing

Per impostazione predefinita, il bot risponde con un codice di pairing. Approvalo:

openclaw pairing approve feishu <CODE>

Dopo l’approvazione, puoi chattare normalmente.

Panoramica

• Canale bot Feishu: bot Feishu gestito dal gateway
• Routing deterministico: le risposte tornano sempre a Feishu
• Isolamento sessione: i DM condividono una sessione principale; i gruppi sono isolati
• Connessione WebSocket: connessione persistente tramite Feishu SDK, nessun URL pubblico necessario

Controllo degli accessi

Messaggi diretti

• Predefinito: dmPolicy: "pairing" (gli utenti sconosciuti ricevono un codice di pairing)

• Approva il pairing:

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

• Modalita allowlist: imposta channels.feishu.allowFrom con gli Open ID consentiti

Chat di gruppo

1. Policy di gruppo (channels.feishu.groupPolicy):

• "open" = consenti tutti nei gruppi (predefinito)
• "allowlist" = consenti solo groupAllowFrom
• "disabled" = disabilita i messaggi di gruppo

2. Requisito menzione (channels.feishu.groups.<chat_id>.requireMention):

• true = richiedi @menzione (predefinito)
• false = rispondi senza menzioni

Esempi di configurazione gruppi

Consenti tutti i gruppi, richiedi @menzione (predefinito)

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

Consenti tutti i gruppi, nessuna @menzione richiesta

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

Consenti solo gruppi specifici

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Gli ID gruppo Feishu (chat_id) hanno questo aspetto: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Limita quali mittenti possono scrivere in un gruppo (allowlist mittenti)

Oltre a consentire il gruppo stesso, tutti i messaggi in quel gruppo sono filtrati dall’open_id del mittente: solo gli utenti elencati in groups.<chat_id>.allowFrom vedranno i loro messaggi elaborati; i messaggi dagli altri membri vengono ignorati (questo e un filtraggio a livello mittente completo, non solo per i comandi di controllo come /reset o /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Gli ID utente Feishu (open_id) hanno questo aspetto: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Ottenere gli ID gruppo/utente

ID gruppo (chat_id)

Gli ID gruppo hanno questo aspetto: oc_xxx.

Metodo 1 (consigliato)

1. Avvia il gateway e @menziona il bot nel gruppo
2. Esegui openclaw logs --follow e cerca chat_id

Metodo 2

Usa il debugger API Feishu per elencare le chat di gruppo.

ID utente (open_id)

Gli ID utente hanno questo aspetto: ou_xxx.

Metodo 1 (consigliato)

1. Avvia il gateway e scrivi un DM al bot
2. Esegui openclaw logs --follow e cerca open_id

Metodo 2

Controlla le richieste di pairing per gli Open ID degli utenti:

openclaw pairing list feishu

Comandi comuni

Nota: Feishu non supporta ancora i menu comandi nativi, quindi i comandi devono essere inviati come testo.

Comandi di gestione gateway

Risoluzione problemi

Il bot non risponde nelle chat di gruppo

1. Assicurati che il bot sia aggiunto al gruppo
2. Assicurati di @menzionare il bot (comportamento predefinito)
3. Controlla che groupPolicy non sia impostato a "disabled"
4. Controlla i log: openclaw logs --follow

Il bot non riceve messaggi

1. Assicurati che l’app sia pubblicata e approvata
2. Assicurati che la sottoscrizione eventi includa im.message.receive_v1
3. Assicurati che la connessione persistente sia abilitata
4. Assicurati che i permessi dell’app siano completi
5. Assicurati che il gateway sia in esecuzione: openclaw gateway status
6. Controlla i log: openclaw logs --follow

Fuga di App Secret

1. Reimposta l’App Secret nella Feishu Open Platform
2. Aggiorna l’App Secret nella tua configurazione
3. Riavvia il gateway

Fallimenti nell’invio messaggi

1. Assicurati che l’app abbia il permesso im:message:send_as_bot
2. Assicurati che l’app sia pubblicata
3. Controlla i log per errori dettagliati

Configurazione avanzata

Account multipli

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

defaultAccount controlla quale account Feishu viene usato quando le API in uscita non specificano un accountId esplicitamente.

Limiti messaggi

• textChunkLimit: dimensione segmento testo in uscita (predefinito: 2000 caratteri)
• mediaMaxMb: limite upload/download media (predefinito: 30MB)

Streaming

Feishu supporta risposte in streaming tramite card interattive. Quando abilitato, il bot aggiorna una card mentre genera il testo.

{
  channels: {
    feishu: {
      streaming: true, // abilita output streaming via card (predefinito true)
      blockStreaming: true, // abilita streaming a blocchi (predefinito true)
    },
  },
}

Imposta streaming: false per attendere la risposta completa prima dell’invio.

Routing multi-agent

Usa bindings per instradare DM o gruppi Feishu verso agent diversi.

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

Campi di routing:

• match.channel: "feishu"
• match.peer.kind: "direct" o "group"
• match.peer.id: Open ID utente (ou_xxx) o ID gruppo (oc_xxx)

Vedi Ottenere gli ID gruppo/utente per suggerimenti di lookup.

Riferimento configurazione

Configurazione completa: Configurazione gateway

Opzioni principali:

Riferimento dmPolicy

Tipi di messaggio supportati

Ricezione

• Testo
• Rich text (post)
• Immagini
• File
• Audio
• Video
• Sticker

Invio

• Testo
• Immagini
• File
• Audio
• Rich text (supporto parziale)