​

Bot Feishu

​

Plugin incluso

openclaw plugins install @openclaw/feishu

​

Avvio rapido

​

Metodo 1: onboarding (consigliato)

openclaw onboard

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

• openclaw gateway status
• openclaw logs --follow

​

Metodo 2: configurazione tramite CLI

openclaw channels add

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

​

Passaggio 1: creare un’app Feishu

​

1. Apri Feishu Open Platform

​

2. Crea un’app

1. Fai clic su Create enterprise app
2. Compila il nome e la descrizione dell’app
3. Scegli un’icona per l’app

​

3. Copia le credenziali

• App ID (formato: cli_xxx)
• App Secret

​

4. Configura i permessi

{
  "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 funzionalità bot

1. Abilita la funzionalità bot
2. Imposta il nome del bot

​

6. Configura la sottoscrizione degli eventi

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

1. Scegli Use long connection to receive events (WebSocket)
2. Aggiungi l’evento: im.message.receive_v1
3. (Facoltativo) Per i flussi di lavoro dei commenti Drive, aggiungi anche: drive.notice.comment_add_v1

​

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 enterprise di solito vengono approvate automaticamente)

​

Passaggio 2: configurare OpenClaw

​

Configurazione con la procedura guidata (consigliata)

openclaw channels add

​

Configurazione tramite file di configurazione

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

​

Verification Token e Encrypt Key (modalità webhook)

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

​

Configurazione tramite variabili d’ambiente

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

​

Dominio Lark (globale)

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

​

Flag di ottimizzazione della quota

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

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

​

Passaggio 3: avviare e testare

​

1. Avvia il gateway

openclaw gateway

​

2. Invia un messaggio di test

​

3. Approva l’associazione

openclaw pairing approve feishu <CODE>

​

Panoramica

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

​

Controllo degli accessi

​

Messaggi diretti

• Predefinito: dmPolicy: "pairing" (gli utenti sconosciuti ricevono un codice di pairing)
• Approva l’associazione:
  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>
  
• Modalità allowlist: imposta channels.feishu.allowFrom con gli Open ID consentiti

​

Chat di gruppo

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

• true esplicito = richiede @mention
• false esplicito = risponde senza menzioni
• quando non impostato e groupPolicy: "open" = predefinito false
• quando non impostato e groupPolicy non è "open" = predefinito true

​

Esempi di configurazione dei gruppi

​

Consenti tutti i gruppi, senza @mention obbligatoria (predefinito per i gruppi aperti)

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

​

Consenti tutti i gruppi, ma richiedi comunque @mention

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

​

Consenti solo gruppi specifici

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Gli ID dei gruppi Feishu (chat_id) hanno un aspetto simile a: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

​

Limitare quali mittenti possono inviare messaggi in un gruppo (allowlist mittenti)

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

​

Ottenere gli ID di gruppo/utente

​

ID gruppo (chat_id)

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

​

ID utente (open_id)

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

openclaw pairing list feishu

​

Comandi comuni

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

​

Comandi di gestione del gateway

​

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 con @ (comportamento predefinito)
3. Verifica che groupPolicy non sia impostato su "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 degli eventi includa im.message.receive_v1
3. Assicurati che la long connection 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

​

Perdita dell’App Secret

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

​

Errori di invio dei 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",
          name: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

​

Limiti dei messaggi

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

​

Streaming

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

​

Sessioni ACP

• DM
• conversazioni di gruppo con argomento

​

Associazioni ACP persistenti

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

​

Avvio ACP associato al thread dalla chat

/acp spawn codex --thread here

• --thread here funziona per DM e argomenti Feishu.
• I messaggi successivi nel DM/argomento associato vengono instradati direttamente a quella sessione ACP.
• La v1 non si rivolge alle chat di gruppo generiche senza argomento.

​

Instradamento multi-agent

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

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

​

Riferimento della configurazione

​

Riferimento dmPolicy

​

Tipi di messaggi supportati

​

Ricezione

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

​

Invio

• ✅ Testo
• ✅ Immagini
• ✅ File
• ✅ Audio
• ✅ Video/media
• ✅ Schede interattive
• ⚠️ Testo avanzato (formattazione stile post e schede, non funzionalità di authoring Feishu arbitrarie)

​

Thread e risposte

• ✅ Risposte inline
• ✅ Risposte ai thread degli argomenti dove Feishu espone reply_in_thread
• ✅ Le risposte con media restano consapevoli del thread quando rispondono a un messaggio di thread/argomento

​

Commenti Drive

• Sottoscrivi drive.notice.comment_add_v1 nelle impostazioni di sottoscrizione eventi della tua app Feishu (insieme all’esistente im.message.receive_v1)
• Lo strumento Drive è abilitato per impostazione predefinita; disabilitalo con channels.feishu.tools.drive: false

• il testo del commento e il mittente
• i metadati del documento (titolo, tipo, URL)
• il contesto del thread del commento per le risposte nel thread

​

Superficie delle azioni runtime

• send
• read
• edit
• thread-reply
• pin
• list-pins
• unpin
• member-info
• channel-info
• channel-list
• react e reactions quando le reazioni sono abilitate nella configurazione
• azioni sui commenti feishu_drive: list_comments, list_comment_replies, add_comment, reply_comment

​

Correlati

• Panoramica dei canali — tutti i canali supportati
• Pairing — autenticazione DM e flusso di pairing
• Gruppi — comportamento delle chat di gruppo e controllo delle menzioni
• Instradamento dei canali — instradamento delle sessioni per i messaggi
• Sicurezza — modello di accesso e hardening