Feishu

Feishu/Lark è una piattaforma di collaborazione all-in-one in cui i team chattano, condividono documenti, gestiscono calendari e lavorano insieme.

Stato: pronta per la produzione per DM del bot + chat di gruppo. WebSocket è la modalità predefinita; la modalità Webhook è opzionale.

# Avvio rapido

openclaw channels login --channel feishu

openclaw gateway restart

# Controllo degli accessi

# Messaggi diretti

Configura dmPolicy per controllare chi può inviare DM al bot:

• "pairing" - gli utenti sconosciuti ricevono un codice di associazione; approva tramite CLI
• "allowlist" - solo gli utenti elencati in allowFrom possono chattare (impostazione predefinita: solo il proprietario del bot)
• "open" - consenti DM pubblici solo quando allowFrom include "*"; con voci restrittive, solo gli utenti corrispondenti possono chattare
• "disabled" - disabilita tutti i DM

Approva una richiesta di associazione:

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

# Chat di gruppo

Criterio di gruppo (channels.feishu.groupPolicy):

Predefinito: allowlist

Requisito di menzione (channels.feishu.requireMention):

• true - richiede @menzione (predefinito)
• false - risponde senza @menzione
• Override per gruppo: channels.feishu.groups.<chat_id>.requireMention
• @all e @_all solo broadcast non sono trattati come menzioni del bot. Un messaggio che menziona sia @all sia direttamente il bot viene comunque conteggiato come menzione del bot.

# Esempi di configurazione dei gruppi

# Consenti tutti i gruppi, nessuna @menzione richiesta

{
  channels: {
    feishu: {
      groupPolicy: "open",
    },
  },
}

# Consenti tutti i gruppi, richiedendo comunque @menzione

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

# Consenti solo gruppi specifici

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Group IDs look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

In modalità allowlist, puoi anche ammettere un gruppo aggiungendo una voce esplicita groups.<chat_id>. Le voci esplicite non sovrascrivono groupPolicy: "disabled". Le impostazioni predefinite con carattere jolly in groups.* configurano i gruppi corrispondenti, ma da sole non ammettono gruppi.

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groups: {
        oc_xxx: {
          requireMention: false,
        },
      },
    },
  },
}

# Limita i mittenti all'interno di un gruppo

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // User open_ids look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

# Ottieni gli ID di gruppi/utenti

# ID gruppo (chat_id, formato: oc_xxx)

Apri il gruppo in Feishu/Lark, fai clic sull'icona del menu nell'angolo in alto a destra e vai a Impostazioni. L'ID del gruppo (chat_id) è elencato nella pagina delle impostazioni.

# ID utente (open_id, formato: ou_xxx)

Avvia il Gateway, invia un DM al bot, quindi controlla i log:

openclaw logs --follow

Cerca open_id nell'output del log. Puoi anche controllare le richieste di associazione in sospeso:

openclaw pairing list feishu

# Comandi comuni

# Risoluzione dei problemi

# Il bot non risponde nelle chat di gruppo

1. Assicurati che il bot sia stato aggiunto al gruppo
2. Assicurati di @menzionare il bot (richiesto per impostazione predefinita)
3. Verifica che groupPolicy non sia "disabled"
4. Controlla i log: openclaw logs --follow

# Il bot non riceve messaggi

1. Assicurati che il bot sia pubblicato e approvato in Feishu Open Platform / Lark Developer
2. Assicurati che la sottoscrizione agli eventi includa im.message.receive_v1
3. Assicurati che sia selezionata la connessione persistente (WebSocket)
4. Assicurati che tutti gli ambiti di autorizzazione richiesti siano concessi
5. Assicurati che il Gateway sia in esecuzione: openclaw gateway status
6. Controlla i log: openclaw logs --follow

# App Secret trapelato

1. Reimposta l'App Secret in Feishu Open Platform / Lark Developer
2. Aggiorna il valore nella tua configurazione
3. Riavvia il Gateway: openclaw gateway restart

# Configurazione avanzata

# Account multipli

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

defaultAccount controlla quale account viene usato quando le API in uscita non specificano un accountId. accounts.<id>.tts usa la stessa forma di messages.tts ed esegue un deep merge sulla configurazione TTS globale, quindi le configurazioni Feishu multi-bot possono mantenere le credenziali dei provider condivise a livello globale, sovrascrivendo solo voce, modello, persona o modalità automatica per account.

# Limiti dei messaggi

• textChunkLimit - dimensione dei blocchi di testo in uscita (predefinito: 2000 caratteri)
• mediaMaxMb - limite di caricamento/download dei media (predefinito: 30 MB)

# Streaming

Feishu/Lark supporta le risposte in streaming tramite schede interattive. Quando è abilitato, il bot aggiorna la scheda in tempo reale mentre genera il testo.

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

Imposta streaming: false per inviare la risposta completa in un unico messaggio. blockStreaming è disattivato per impostazione predefinita; abilitalo solo quando vuoi inviare i blocchi completati dell'assistente prima della risposta finale.

# Ottimizzazione delle quote

Riduci il numero di chiamate API Feishu/Lark con due flag opzionali:

• typingIndicator (predefinito true): imposta false per saltare le chiamate di reazione di digitazione
• resolveSenderNames (predefinito true): imposta false per saltare le ricerche dei profili dei mittenti

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
    },
  },
}

# Sessioni ACP

Feishu/Lark supporta ACP per DM e messaggi di thread di gruppo. ACP di Feishu/Lark è basato su comandi testuali: non ci sono menu nativi per comandi slash, quindi usa i messaggi /acp ... direttamente nella conversazione.

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

# Avvia ACP dalla chat

In un DM o thread Feishu/Lark:

/acp spawn codex --thread here

--thread here funziona per DM e messaggi di thread Feishu/Lark. I messaggi successivi nella conversazione associata vengono instradati direttamente a quella sessione ACP.

# Routing multi-agente

Usa bindings per instradare DM o gruppi Feishu/Lark ad agenti diversi.

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

Campi di routing:

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

Vedi Ottieni gli ID di gruppi/utenti per suggerimenti sulla ricerca.

# Riferimento di configurazione

Configurazione completa: Configurazione del Gateway

# Tipi di messaggio supportati

# Ricezione

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

I messaggi audio Feishu/Lark in ingresso vengono normalizzati come segnaposto media invece che come JSON file_key grezzo. Quando tools.media.audio è configurato, OpenClaw scarica la risorsa della nota vocale ed esegue la trascrizione audio condivisa prima del turno dell'agente, così l'agente riceve la trascrizione del parlato. Se Feishu include testo di trascrizione direttamente nel payload audio, quel testo viene usato senza un'altra chiamata ASR. Senza un provider di trascrizione audio, l'agente riceve comunque un segnaposto <media:audio> più l'allegato salvato, non il payload grezzo della risorsa Feishu.

# Invio

• ✅ Testo
• ✅ Immagini
• ✅ File
• ✅ Audio
• ✅ Video/media
• ✅ Schede interattive (inclusi aggiornamenti in streaming)
• ⚠️ Rich text (formattazione in stile post; non supporta tutte le funzionalità di authoring Feishu/Lark)

I fumetti audio nativi Feishu/Lark usano il tipo di messaggio Feishu audio e richiedono media caricati in Ogg/Opus (file_type: "opus"). I media .opus e .ogg esistenti vengono inviati direttamente come audio nativo. MP3/WAV/M4A e altri formati audio probabili vengono transcodificati in Ogg/Opus a 48 kHz con ffmpeg solo quando la risposta richiede la consegna vocale (audioAsVoice / strumento messaggi asVoice, incluse le risposte con nota vocale TTS). Gli allegati MP3 ordinari restano file normali. Se ffmpeg manca o la conversione non riesce, OpenClaw ripiega su un allegato file e registra il motivo nei log.

# Thread e risposte

• ✅ Risposte in linea
• ✅ Risposte nei thread
• ✅ Le risposte con media restano consapevoli del thread quando rispondono a un messaggio in un thread

Per groupSessionScope: "group_topic" e "group_topic_sender", i gruppi topic nativi Feishu/Lark usano l'evento thread_id (omt_*) come chiave canonica della sessione topic. Se un evento starter di topic nativo omette thread_id, OpenClaw lo idrata da Feishu prima di effettuare il routing del turno. Le normali risposte di gruppo che OpenClaw trasforma in thread continuano a usare l'ID del messaggio radice della risposta (om_*), così il primo turno e il turno successivo restano nella stessa sessione.

# Correlati

• Panoramica dei canali - tutti i canali supportati
• Abbinamento - autenticazione DM e flusso di abbinamento
• Gruppi - comportamento delle chat di gruppo e gating delle menzioni
• Routing dei canali - routing delle sessioni per i messaggi
• Sicurezza - modello di accesso e hardening