Feishu

OpenClaw terhubung ke Feishu/Lark (platform kolaborasi lengkap) melalui plugin resmi @openclaw/feishu: DM bot, obrolan grup, balasan kartu streaming, serta alat dokumen/wiki/drive/Bitable Feishu.

Status: siap produksi untuk DM bot + obrolan grup. WebSocket adalah transport peristiwa default (tidak memerlukan URL publik); mode webhook bersifat opsional.

Mulai cepat

openclaw channels login --channel feishu

openclaw gateway restart

Ketahanan pesan masuk

OpenClaw memasukkan envelope im.message.receive_v1 dan drive.notice.comment_add_v1 yang telah diautentikasi ke antrean secara tahan lama sebelum pengiriman ke agen. Peristiwa yang tertunda atau dapat dicoba ulang tetap bertahan setelah Gateway dimulai ulang, tetap diserialkan per obrolan atau dokumen, dan menggunakan ID peristiwa Feishu untuk mencegah entri antrean duplikat selama catatan penyelesaian aktif atau yang dipertahankan masih ada.

Jika peristiwa WebSocket tidak dapat dipersistenkan setelah sejumlah percobaan ulang yang dibatasi, OpenClaw menutup soket tersebut dan memaksa koneksi baru yang diautentikasi, alih-alih melanjutkan setelah giliran yang belum di-commit. Jenis peristiwa Feishu lainnya, termasuk reaksi dan undangan rapat VC, menggunakan jalur peristiwa normal dan tidak mendapatkan jaminan antrean tahan lama ini.

Kontrol akses

Pesan langsung

Konfigurasikan channels.feishu.dmPolicy (default: pairing) untuk mengontrol siapa yang dapat mengirim DM kepada bot:

Setujui permintaan pemasangan:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Obrolan grup

Kebijakan grup (channels.feishu.groupPolicy, default: allowlist):

Persyaratan penyebutan (channels.feishu.requireMention):

• Default: @mention diperlukan, kecuali jika kebijakan grup efektif adalah "open"; dalam kondisi tersebut, nilai default-nya adalah false agar pesan yang tidak dapat menyertakan penyebutan (misalnya gambar) tetap sampai ke agen.
• Tetapkan true atau false secara eksplisit untuk menggantinya; penggantian per grup: channels.feishu.groups.<chat_id>.requireMention.
• @all dan @_all yang hanya untuk siaran tidak dianggap sebagai penyebutan bot. Pesan yang menyebut @all sekaligus bot secara langsung tetap dihitung sebagai penyebutan bot.

Contoh konfigurasi grup

Izinkan semua grup tanpa memerlukan @mention

{  channels: {    feishu: {      groupPolicy: "open", // requireMention secara default bernilai false pada "open"    },  },}

Izinkan semua grup, tetapi tetap wajibkan @mention

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

Hanya izinkan grup tertentu

{  channels: {    feishu: {      groupPolicy: "allowlist",      // ID grup terlihat seperti: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

Dalam mode allowlist, Anda juga dapat mengizinkan grup dengan menambahkan entri groups.<chat_id> eksplisit. Entri eksplisit tidak menggantikan groupPolicy: "disabled". Default wildcard di bawah groups.* mengonfigurasi grup yang cocok, tetapi tidak mengizinkan grup dengan sendirinya.

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

Batasi pengirim dalam grup

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // open_id pengguna terlihat seperti: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

channels.feishu.groupSenderAllowFrom menetapkan daftar izin pengirim yang sama untuk semua grup; allowFrom per grup memiliki prioritas.

Pesan yang dibuat oleh bot

Secara default, Feishu mengabaikan pesan yang dibuat oleh bot lain. Untuk mengizinkan percakapan grup antarbot, berikan cakupan im:message.group_at_msg.include_bot:readonly dan im:message:readonly kepada aplikasi, lalu tetapkan allowBots:

{  channels: {    feishu: {      allowBots: true,    },  },}

Feishu hanya mengirimkan peristiwa grup yang dibuat oleh bot ketika bot lain menyebut bot ini. Kebijakan grup, daftar izin pengirim, dan persyaratan penyebutan yang ada tetap berlaku. OpenClaw membuang pesan yang dibuatnya sendiri, menyebut bot rekan pada setiap balasan teks atau kartu, dan menerapkan perlindungan bersama channels.defaults.botLoopProtection.

Mendapatkan ID grup/pengguna

ID grup (chat_id, format: oc_xxx)

Buka grup di Feishu/Lark, klik ikon menu di sudut kanan atas, lalu buka Settings. ID grup (chat_id) tercantum di halaman pengaturan.

ID pengguna (open_id, format: ou_xxx)

Mulai Gateway, kirim DM kepada bot, lalu periksa log:

openclaw logs --follow

Cari open_id dalam keluaran log. Anda juga dapat memeriksa permintaan pemasangan yang tertunda:

openclaw pairing list feishu

Perintah umum

Pemecahan masalah

Bot tidak merespons dalam obrolan grup

1. Pastikan bot telah ditambahkan ke grup
2. Pastikan Anda @mention bot (diwajibkan secara default)
3. Verifikasikan bahwa groupPolicy bukan "disabled"
4. Periksa log: openclaw logs --follow

Bot tidak menerima pesan

1. Pastikan bot telah dipublikasikan dan disetujui di Feishu Open Platform / Lark Developer
2. Pastikan langganan peristiwa menyertakan im.message.receive_v1
3. Untuk bergabung otomatis dengan undangan rapat, langgani juga vc.bot.meeting_invited_v1
4. Pastikan persistent connection (WebSocket) dipilih
5. Pastikan semua cakupan izin yang diperlukan telah diberikan
6. Pastikan Gateway sedang berjalan: openclaw gateway status
7. Periksa log: openclaw logs --follow

Berlangganan vc.bot.meeting_invited_v1 hanya mengirimkan peristiwa. Bergabung otomatis dinonaktifkan secara default. Untuk mengaktifkannya secara global:

{  channels: {    feishu: {      vcAutoJoin: true,    },  },}

Untuk mengaktifkannya hanya bagi satu akun, hilangkan sakelar tingkat teratas dan tetapkan penggantian akun:

{  channels: {    feishu: {      accounts: {        meetings: { vcAutoJoin: true },      },    },  },}

Pengundang tetap melewati kebijakan DM Feishu normal, daftar izin/pemasangan, sesi, dan perutean balasan sebelum agen menerima giliran untuk bergabung. Bergabung juga memerlukan alat untuk bergabung ke VC Feishu yang tersedia dan dikonfigurasi bagi identitas aplikasi dengan cakupan vc:meeting.bot.join:write. Sebagai contoh, skill agen VC lark-cli resmi menyediakan vc +meeting-join.

Penyiapan QR tidak merespons di aplikasi seluler Feishu

1. Jalankan kembali penyiapan: openclaw channels login --channel feishu
2. Pilih penyiapan manual
3. Di Feishu Open Platform, buat aplikasi mandiri lalu salin App ID dan App Secret-nya
4. Tempelkan kredensial tersebut ke wizard penyiapan

App Secret bocor

1. Atur ulang App Secret di Feishu Open Platform / Lark Developer
2. Perbarui nilainya dalam konfigurasi Anda
3. Mulai ulang Gateway: openclaw gateway restart

Konfigurasi lanjutan

Beberapa akun

{  channels: {    feishu: {      defaultAccount: "main",      accounts: {        main: {          appId: "cli_xxx",          appSecret: "xxx",          name: "Bot utama",          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },        backup: {          appId: "cli_yyy",          appSecret: "yyy",          name: "Bot cadangan",          enabled: false,        },      },    },  },}

defaultAccount mengontrol akun yang digunakan ketika API keluar tidak menentukan accountId. Entri akun mewarisi pengaturan tingkat teratas; sebagian besar kunci tingkat teratas dapat diganti per akun. accounts.<id>.tts menggunakan bentuk yang sama seperti messages.tts dan melakukan deep merge terhadap konfigurasi TTS global, sehingga penyiapan Feishu dengan beberapa bot dapat mempertahankan kredensial penyedia bersama secara global sambil hanya mengganti suara, model, persona, atau mode otomatis per akun.

Batas pesan

• textChunkLimit - ukuran potongan teks keluar (default: 4000 karakter)
• streaming.chunkMode - "length" (default) membagi pada batas; "newline" mengutamakan batas baris baru
• mediaMaxMb - batas unggah/unduh media (default: 30 MB)

Streaming

Feishu/Lark mendukung balasan streaming melalui kartu interaktif (API streaming Card Kit). Ketika diaktifkan, bot memperbarui kartu secara waktu nyata saat menghasilkan teks.

{  channels: {    feishu: {      streaming: {        mode: "partial", // keluaran kartu streaming (default: "partial")        block: { enabled: true }, // mengaktifkan streaming blok yang telah selesai      },    },  },}

Atur streaming.mode: "off" untuk mengirim balasan lengkap dalam satu pesan; renderMode: "raw" (teks biasa alih-alih kartu) juga menonaktifkan kartu streaming. streaming.block.enabled dinonaktifkan secara default; aktifkan hanya jika Anda ingin blok asisten yang telah selesai dikirim sebelum balasan akhir. Boolean lama streaming serta kunci datar blockStreaming / blockStreamingCoalesce / chunkMode dimigrasikan ke bentuk bertingkat ini melalui openclaw doctor --fix.

Pengoptimalan kuota

Kurangi jumlah panggilan API Feishu/Lark dengan dua flag opsional:

• typingIndicator (default true): atur false untuk melewati panggilan reaksi mengetik
• resolveSenderNames (default true): atur false untuk melewati pencarian profil pengirim

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

Cakupan sesi grup dan utas topik

channels.feishu.groupSessionScope (tingkat teratas, per akun, atau per grup) mengontrol cara pesan grup dipetakan ke sesi agen:

Untuk cakupan topik, grup topik asli Feishu/Lark menggunakan peristiwa thread_id (omt_*) sebagai kunci sesi topik kanonis. Jika peristiwa pembuka topik asli tidak menyertakan thread_id, OpenClaw mengambilnya dari Feishu sebelum merutekan giliran. Balasan grup biasa yang diubah OpenClaw menjadi utas tetap menggunakan ID pesan akar balasan (om_*) agar giliran pertama dan giliran lanjutan tetap berada dalam sesi yang sama.

Atur replyInThread: "enabled" (tingkat teratas atau per grup) agar balasan bot membuat atau melanjutkan utas topik Feishu alih-alih membalas sebaris. topicSessionMode adalah pendahulu groupSessionScope yang sudah tidak digunakan; utamakan groupSessionScope.

Alat ruang kerja Feishu

Plugin ini menyediakan alat agen untuk dokumen, percakapan, basis pengetahuan, penyimpanan cloud, izin, dan Bitable Feishu, serta skill yang sesuai (feishu-doc, feishu-drive, feishu-perm, feishu-wiki). Kelompok alat dikendalikan oleh channels.feishu.tools:

tools.base adalah alias untuk tools.bitable; nilai eksplisit bitable diprioritaskan jika keduanya ditetapkan. Pengendali per akun berada di bawah accounts.<id>.tools.

Berikan drive:drive.metadata:readonly untuk pencarian langsung feishu_drive info di luar direktori akar, kecuali aplikasi sudah memiliki cakupan penuh drive:drive. Tanpa salah satu cakupan tersebut, info tetap menyediakan pencarian direktori akar lama melalui drive:drive:readonly.

Sesi ACP

Feishu/Lark mendukung ACP untuk DM dan pesan utas grup. ACP Feishu/Lark dikendalikan oleh perintah teks—tidak ada menu perintah garis miring asli, jadi gunakan pesan /acp ... secara langsung dalam percakapan.

Pengikatan ACP persisten

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

Membuat ACP dari percakapan

Dalam DM atau utas Feishu/Lark:

/acp spawn codex --thread here

--thread here berfungsi untuk DM dan pesan utas Feishu/Lark. Pesan lanjutan dalam percakapan yang terikat dirutekan langsung ke sesi ACP tersebut.

Perutean multiagen

Gunakan bindings untuk merutekan DM atau grup Feishu/Lark ke agen yang berbeda.

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

Bidang perutean:

• match.channel: "feishu"
• match.peer.kind: "direct" (DM) atau "group" (percakapan grup)
• match.peer.id: Open ID pengguna (ou_xxx) atau ID grup (oc_xxx)

Lihat Mendapatkan ID grup/pengguna untuk kiat pencarian.

Isolasi agen per pengguna (Pembuatan Agen Dinamis)

Aktifkan dynamicAgentCreation untuk secara otomatis membuat instans agen terisolasi bagi setiap pengguna DM. Setiap pengguna mendapatkan:

• Direktori ruang kerja independen
• USER.md / SOUL.md / MEMORY.md terpisah
• Riwayat percakapan privat
• Skill dan status terisolasi

Ini sangat penting untuk bot publik jika Anda ingin setiap pengguna memiliki pengalaman asisten AI privat mereka sendiri.

Penyiapan cepat

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Penting: menjadikan DM setiap pengguna sebagai "sesi utama" mereka    // Memuat USER.md / SOUL.md / MEMORY.md secara otomatis    // Untuk isolasi yang lebih kuat, gunakan "per-channel-peer"    dmScope: "main",  },}

Cara kerjanya

Saat pengguna baru mengirim DM pertama mereka:

1. Saluran menghasilkan agentId unik: feishu-{user_open_id} untuk akun default, atau ringkasan identitas terbatas yang diawali akun untuk akun bernama
2. Membuat ruang kerja baru pada jalur workspaceTemplate
3. Mendaftarkan agen dan membuat pengikatan untuk pengguna ini
4. Pembantu ruang kerja memastikan berkas bootstrap (AGENTS.md, SOUL.md, USER.md, dan sebagainya) tersedia pada akses pertama
5. Merutekan semua pesan mendatang dari pengguna ini ke agen khusus mereka

Opsi konfigurasi

Variabel templat:

• {agentId} - ID agen yang dihasilkan (misalnya, feishu-ou_xxxxxx atau feishu-support-<identity_digest>)
• {userId} - open_id Feishu milik pengirim (misalnya, ou_xxxxxx)

Cakupan sesi

session.dmScope mengontrol cara pesan langsung dipetakan ke sesi agen. Ini adalah pengaturan global yang memengaruhi semua saluran.

Kompromi: Menggunakan "main" mengaktifkan pemuatan otomatis berkas bootstrap (USER.md, SOUL.md, MEMORY.md), tetapi berarti semua DM di semua saluran menggunakan pola kunci sesi yang sama. Untuk bot publik multi-pengguna yang lebih mengutamakan isolasi daripada pemuatan otomatis bootstrap, pertimbangkan "per-channel-peer" dan kelola berkas bootstrap secara manual.

Penerapan multi-pengguna umum

{  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: {    // Pilih dmScope berdasarkan kebutuhan isolasi Anda:    // "main" untuk pemuatan otomatis bootstrap, "per-channel-peer" untuk isolasi yang lebih kuat    dmScope: "main",  },  bindings: [], // Kosong - agen dinamis terikat otomatis}

Verifikasi

Periksa log Gateway untuk memastikan pembuatan dinamis berfungsi:

feishu: membuat agen dinamis "feishu-ou_xxxxxx" untuk pengguna ou_xxxxxx  ruang kerja: /home/user/.openclaw/workspace-feishu-ou_xxxxxx  direktori agen: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

Cantumkan semua ruang kerja yang dibuat:

ls -la ~/.openclaw/workspace-*

Catatan

• Isolasi ruang kerja: Setiap pengguna mendapatkan direktori ruang kerja dan instans agen masing-masing. Pengguna tidak dapat melihat riwayat percakapan atau berkas pengguna lain dalam alur perpesanan normal.
• Batas keamanan: Ini adalah mekanisme isolasi konteks perpesanan, bukan batas keamanan antarpenyewa yang bermusuhan. Proses agen dan lingkungan host digunakan bersama.
• Penulisan konfigurasi harus tetap diaktifkan: Pembuatan agen dinamis menulis agen dan pengikatan ke dalam konfigurasi; proses ini dilewati jika channels.feishu.configWrites bernilai false (default: diaktifkan).
• bindings harus kosong: Agen dinamis mendaftarkan pengikatannya sendiri secara otomatis
• Jalur peningkatan: Pengikatan manual yang sudah ada tetap berfungsi bersama agen dinamis
• session.dmScope bersifat global: Ini memengaruhi semua kanal, bukan hanya Feishu

Referensi konfigurasi

Konfigurasi lengkap: Konfigurasi Gateway

Jenis pesan yang didukung

Terima

• ✅ Teks
• ✅ Teks kaya (postingan)
• ✅ Gambar
• ✅ Berkas
• ✅ Audio
• ✅ Video/media
• ✅ Stiker

Pesan audio Feishu/Lark yang masuk dinormalisasi sebagai placeholder media, bukan sebagai JSON file_key mentah. Ketika tools.media.audio dikonfigurasi, OpenClaw mengunduh sumber catatan suara dan menjalankan transkripsi audio bersama sebelum giliran agen, sehingga agen menerima transkrip ucapan. Jika Feishu menyertakan teks transkrip secara langsung dalam payload audio, teks tersebut digunakan tanpa panggilan ASR lain. Tanpa penyedia transkripsi audio, agen tetap menerima placeholder <media:audio> beserta lampiran yang disimpan, bukan payload sumber daya Feishu mentah.

Kirim

• ✅ Teks
• ✅ Gambar
• ✅ Berkas
• ✅ Audio
• ✅ Video/media
• ✅ Kartu interaktif (termasuk pembaruan streaming)
• ⚠️ Teks kaya (pemformatan bergaya postingan; tidak mendukung kemampuan penulisan Feishu/Lark secara lengkap)

Bubble audio native Feishu/Lark menggunakan jenis pesan Feishu audio dan memerlukan media unggahan Ogg/Opus (file_type: "opus"). Media .opus dan .ogg yang ada dikirim langsung sebagai audio native. MP3/WAV/M4A dan format lain yang kemungkinan merupakan audio ditranskode menjadi Ogg/Opus 48kHz dengan ffmpeg hanya ketika balasan meminta pengiriman suara (audioAsVoice / alat pesan asVoice, termasuk balasan catatan suara TTS). Lampiran MP3 biasa tetap menjadi file biasa. Jika ffmpeg tidak tersedia atau konversi gagal, OpenClaw beralih ke lampiran file dan mencatat alasannya dalam log.

Utas dan balasan

• ✅ Balasan sebaris
• ✅ Balasan utas
• ✅ Balasan media tetap mempertimbangkan utas saat membalas pesan utas

Perutean sesi grup topik dibahas dalam Cakupan sesi grup dan utas topik.

Terkait

• Ikhtisar Saluran - semua saluran yang didukung
• Pemasangan - autentikasi DM dan alur pemasangan
• Grup - perilaku obrolan grup dan pembatasan berdasarkan sebutan
• Perutean Saluran - perutean sesi untuk pesan
• Keamanan - model akses dan penguatan