Perché Feishu?
Feishu (飞书), conosciuto a livello internazionale come Lark, è la piattaforma di collaborazione aziendale di ByteDance — ampiamente utilizzata nelle aziende tech cinesi, startup e sempre più nel Sud-est asiatico. Con OpenClaw v2026.2.2, Feishu è diventato il primo client di chat cinese ufficialmente supportato dalla piattaforma.
- •Nessun URL pubblico richiesto — nessun ngrok, nessun dominio, nessun server webhook
- •Funziona dietro firewall — la connessione è in uscita dalla propria macchina
- •Bassa latenza — messaggistica bidirezionale in tempo reale
- •Supporto per contenuti ricchi — testo, immagini, file, audio, video e sticker
Prerequisiti
- •OpenClaw v2026.2.2 o successivo
- •Un account aziendale Feishu/Lark (il piano gratuito funziona)
- •Accesso amministratore per creare app sulla Feishu Open Platform
Passo 1: Creare un'App Feishu
- 1.Andare alla Feishu Open Platform (o alla Lark Developer Console per i tenant internazionali)
- 2.Cliccare Create Custom App
- 3.Impostare il nome dell'app (ad es. "OpenClaw Agent") e la descrizione
- 4.Caricare un'icona (il logo dell'aragosta di OpenClaw funziona bene)
- 5.Copiare l'App ID (formato:
cli_xxx) e l'App Secret dalla pagina Credentials
Passo 2: Configurare i Permessi dell'App
Nelle impostazioni dei permessi dell'app, abilitare questi ambiti:
| Permesso | Scopo |
|---|---|
im:message | Inviare e ricevere messaggi |
im:message.group_at_msg | Ricevere le @menzioni nelle chat di gruppo |
im:resource | Accedere a immagini e file |
contact:user.id:readonly | Identificare gli utenti |
Dopo aver aggiunto i permessi, cliccare Publish per inviare per la revisione. Nella maggior parte dei tenant aziendali, le app auto-costruite vengono approvate automaticamente.
Passo 3: Abilitare la Sottoscrizione di Eventi
- 1.Nelle impostazioni dell'app, andare a Event Subscriptions
- 2.Selezionare WebSocket Mode (connessione lunga) — questo è fondamentale. NON utilizzare la modalità webhook, poiché richiede un URL pubblico.
- 3.Sottoscriversi a questi eventi:
Passo 4: Configurare OpenClaw
Aggiungere le credenziali Feishu alla propria configurazione OpenClaw. Modificare ~/.openclaw/.env:
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret_here
Oppure se si utilizza il file di configurazione di OpenClaw (~/.openclaw/config.yaml):
channels:
feishu:
enabled: true
appId: cli_xxxxxxxxxxxxx
appSecret: your_app_secret_here
Riavviare OpenClaw:
openclaw restart
Si dovrebbe vedere un messaggio di log che conferma che la connessione WebSocket con Feishu è stata stabilita.
Passo 5: Testare la Connessione
Aprire Feishu e trovare la propria app nella lista delle chat (cercare il nome dell'app impostato nel Passo 1). Inviare un messaggio:
> Ciao!
- •Messaggi di testo
- •Immagini (l'agente può analizzarle se si utilizza un modello con capacità visive)
- •File (l'agente può leggere i documenti)
- •Messaggi vocali (trascritti ed elaborati come testo)
Configurazione delle Chat di Gruppo
OpenClaw supporta le chat di gruppo di Feishu con tre modalità di accesso:
| Modalità | Comportamento |
|---|---|
open (predefinita) | Qualsiasi membro del gruppo può attivare il bot quando viene @menzionato |
allowlist | Solo gli utenti approvati possono interagire, anche con @menzione |
disabled | I messaggi di gruppo vengono completamente ignorati |
Configurare in config.yaml:
channels:
feishu:
groupAccess: open # or "allowlist" or "disabled"
allowedUsers: # only used with "allowlist" mode
- user_id_1
- user_id_2
Nelle chat di gruppo, l'agente risponde solo quando viene @menzionato, evitando rumore nei canali trafficati.
Risposte in Streaming
OpenClaw supporta le risposte IA in streaming su Feishu utilizzando carte interattive. Invece di attendere la risposta completa, l'agente invia una carta iniziale e la aggiorna in tempo reale mentre l'IA genera il testo. Questo offre un'esperienza utente molto migliore per le risposte lunghe.
Lo streaming è abilitato per impostazione predefinita. Per disabilitarlo:
channels:
feishu:
streaming: false
Tipi di Messaggi Supportati
| Direzione | Tipi Supportati |
|---|---|
| In entrata (utente -> agente) | Testo, rich text (post), immagini, file, audio, video, sticker |
| In uscita (agente -> utente) | Testo, immagini, file, audio, carte interattive |
Risoluzione dei Problemi
Errore "App not found": Assicurarsi che l'app sia pubblicata e approvata nel proprio tenant Feishu. Le app auto-costruite nei tenant aziendali vengono solitamente approvate automaticamente, ma alcune organizzazioni richiedono l'approvazione dell'amministratore.
Nessuna risposta dall'agente: Controllare i log di OpenClaw (openclaw logs) per errori di connessione WebSocket. Verificare che l'App ID e l'App Secret siano corretti.
I messaggi non arrivano nelle chat di gruppo: Assicurarsi che il bot sia aggiunto al gruppo e che l'utente stia @menzionando il bot correttamente. Controllare l'impostazione groupAccess.
Interruzioni della connessione: La connessione WebSocket si riconnette automaticamente. Se le interruzioni sono frequenti, controllare la stabilità della rete o le impostazioni del firewall.
Utilizzare il Bridge della Comunità (Alternativa)
Se si necessitano funzionalità oltre l'integrazione nativa, il bridge feishu-openclaw mantenuto dalla comunità di AlexAnys offre capacità aggiuntive come la formattazione personalizzata dei messaggi e la gestione avanzata dei gruppi. La configurazione richiede circa 5 minuti e non necessita di un server pubblico.
Per la documentazione completa, consultare la guida ufficiale al canale Feishu.