Feishu

OpenClaw, resmi @openclaw/feishu plugin aracılığıyla Feishu/Lark'a (hepsi bir arada iş birliği platformu) bağlanır: bot DM'leri, grup sohbetleri, akışlı kart yanıtları ve Feishu belge/wiki/drive/Bitable araçları.

Durum: bot DM'leri ve grup sohbetleri için üretime hazırdır. WebSocket varsayılan olay aktarım yöntemidir (genel URL gerekmez); webhook modu isteğe bağlıdır.

Hızlı başlangıç

openclaw channels login --channel feishu

openclaw gateway restart

Gelen olayların dayanıklılığı

OpenClaw, kimliği doğrulanmış im.message.receive_v1 ve drive.notice.comment_add_v1 zarflarını agent'a göndermeden önce dayanıklı biçimde kuyruğa alır. Bekleyen veya yeniden denenebilir olaylar Gateway yeniden başlatıldığında korunur, sohbet veya belge başına sıralı kalır ve etkin ya da saklanan tamamlanma kaydı var olduğu sürece yinelenen kuyruk girdilerini engellemek için Feishu'nun olay kimliğini kullanır.

Bir WebSocket olayı sınırlı sayıdaki yeniden denemenin ardından kalıcılaştırılamazsa OpenClaw, kaydedilmemiş bir turu atlayarak devam etmek yerine ilgili soketi kapatır ve kimliği yeniden doğrulanmış yeni bir bağlantıyı zorunlu kılar. Tepkiler ve VC toplantı davetleri dâhil diğer Feishu olay türleri normal olay yollarını kullanır ve bu dayanıklı kuyruk garantisinden yararlanmaz.

Erişim denetimi

Doğrudan mesajlar

Bota kimlerin DM gönderebileceğini denetlemek için channels.feishu.dmPolicy ayarını (varsayılan: pairing) yapılandırın:

Bir eşleştirme isteğini onaylayın:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Grup sohbetleri

Grup politikası (channels.feishu.groupPolicy, varsayılan: allowlist):

Bahsetme gereksinimi (channels.feishu.requireMention):

• Varsayılan: etkin grup politikası "open" olmadığı sürece @bahsetme gerekir; bu politikada, bahsetme içermeyen mesajların (örneğin görsellerin) yine de agent'a ulaşabilmesi için varsayılan değer false olur.
• Geçersiz kılmak için true veya false değerini açıkça ayarlayın; grup başına geçersiz kılma: channels.feishu.groups.<chat_id>.requireMention.
• Yalnızca yayın amaçlı @all ve @_all, bottan bahsetme olarak değerlendirilmez. Hem @all hem de doğrudan bottan bahseden bir mesaj yine bottan bahsetme sayılır.

Grup yapılandırması örnekleri

Tüm gruplara izin verin, @bahsetme gerekmesin

{  channels: {    feishu: {      groupPolicy: "open", // "open" altında requireMention varsayılan olarak false olur    },  },}

Tüm gruplara izin verin, ancak yine de @bahsetme gerektirin

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

Yalnızca belirli gruplara izin verin

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Grup kimlikleri şu biçimdedir: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

allowlist modunda açık bir groups.<chat_id> girdisi ekleyerek de bir gruba izin verebilirsiniz. Açık girdiler groupPolicy: "disabled" değerini geçersiz kılmaz. groups.* altındaki joker karakter varsayılanları eşleşen grupları yapılandırır ancak kendi başlarına gruplara izin vermez.

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

Bir grup içindeki gönderenleri sınırlayın

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // Kullanıcı open_id değerleri şu biçimdedir: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

channels.feishu.groupSenderAllowFrom, tüm gruplar için aynı gönderen izin listesini ayarlar; grup başına allowFrom önceliklidir.

Bot tarafından yazılan mesajlar

Feishu, diğer botlar tarafından yazılan mesajları varsayılan olarak yok sayar. Botlar arası grup konuşmalarına izin vermek için uygulamaya im:message.group_at_msg.include_bot:readonly ve im:message:readonly kapsamlarını verin, ardından allowBots ayarını belirleyin:

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

Feishu, bot tarafından yazılan grup olaylarını yalnızca başka bir bot bu bottan bahsettiğinde iletir. Mevcut grup politikası, gönderen izin listeleri ve bahsetme gereksinimleri uygulanmaya devam eder. OpenClaw kendi yazdığı mesajları bırakır, her metin veya kart yanıtında eş botu belirtir ve paylaşılan channels.defaults.botLoopProtection korumasını uygular.

Grup/kullanıcı kimliklerini alma

Grup kimlikleri (chat_id, biçim: oc_xxx)

Grubu Feishu/Lark'ta açın, sağ üst köşedeki menü simgesine tıklayın ve Settings bölümüne gidin. Grup kimliği (chat_id) ayarlar sayfasında listelenir.

Kullanıcı kimlikleri (open_id, biçim: ou_xxx)

Gateway'i başlatın, bota bir DM gönderin ve ardından günlükleri kontrol edin:

openclaw logs --follow

Günlük çıktısında open_id değerini arayın. Bekleyen eşleştirme isteklerini de kontrol edebilirsiniz:

openclaw pairing list feishu

Yaygın komutlar

Sorun giderme

Bot grup sohbetlerinde yanıt vermiyor

1. Botun gruba eklendiğinden emin olun
2. Bottan @bahsettiğinizden emin olun (varsayılan olarak gereklidir)
3. groupPolicy değerinin "disabled" olmadığını doğrulayın
4. Günlükleri kontrol edin: openclaw logs --follow

Bot mesajları almıyor

1. Botun Feishu Open Platform / Lark Developer'da yayımlandığından ve onaylandığından emin olun
2. Olay aboneliğinin im.message.receive_v1 içerdiğinden emin olun
3. Toplantı davetlerine otomatik katılım için vc.bot.meeting_invited_v1 olayına da abone olun
4. persistent connection (WebSocket) seçeneğinin seçildiğinden emin olun
5. Gerekli tüm izin kapsamlarının verildiğinden emin olun
6. Gateway'in çalıştığından emin olun: openclaw gateway status
7. Günlükleri kontrol edin: openclaw logs --follow

Yalnızca vc.bot.meeting_invited_v1 olayına abone olmak olayı iletir. Otomatik katılımlar varsayılan olarak kapalıdır. Bunları genel olarak etkinleştirmek için:

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

Yalnızca tek bir hesap için etkinleştirmek üzere üst düzey anahtarı kullanmayın ve hesap geçersiz kılmasını ayarlayın:

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

Agent bir katılım turu almadan önce davet edenler yine normal Feishu DM politikasından, izin listesinden/eşleştirmeden, oturumdan ve yanıt yönlendirmesinden geçer. Katılım ayrıca uygulama kimliği için vc:meeting.bot.join:write kapsamıyla yapılandırılmış kullanılabilir bir Feishu VC katılım aracı gerektirir. Örneğin, resmi lark-cli VC agent skill vc +meeting-join sağlar.

QR kurulumu Feishu mobil uygulamasında tepki vermiyor

1. Kurulumu yeniden çalıştırın: openclaw channels login --channel feishu
2. Manuel kurulumu seçin
3. Feishu Open Platform'da kendi oluşturduğunuz bir uygulama oluşturun ve App ID ile App Secret değerlerini kopyalayın
4. Bu kimlik bilgilerini kurulum sihirbazına yapıştırın

App Secret sızdırıldı

1. Feishu Open Platform / Lark Developer'da App Secret değerini sıfırlayın
2. Yapılandırmanızdaki değeri güncelleyin
3. Gateway'i yeniden başlatın: openclaw gateway restart

Gelişmiş yapılandırma

Birden fazla hesap

{  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, giden API'ler bir accountId belirtmediğinde hangi hesabın kullanılacağını denetler. Hesap girdileri üst düzey ayarları devralır; çoğu üst düzey anahtar hesap başına geçersiz kılınabilir. accounts.<id>.tts, tts ile aynı biçimi kullanır ve genel TTS yapılandırması üzerine derin birleştirme uygular; böylece çok botlu Feishu kurulumları, yalnızca ses, model, persona veya otomatik modu hesap başına geçersiz kılarken paylaşılan sağlayıcı kimlik bilgilerini genel düzeyde tutabilir.

Mesaj sınırları

• textChunkLimit - giden metin parçası boyutu (varsayılan: 4000 karakter)
• streaming.chunkMode - "length" (varsayılan) sınırda böler; "newline" satır sonu sınırlarını tercih eder
• mediaMaxMb - medya yükleme/indirme sınırı (varsayılan: 30 MB)

Akış

Feishu/Lark, etkileşimli kartlar (Card Kit akış API'si) aracılığıyla akışlı yanıtları destekler. Etkinleştirildiğinde bot, metin üretirken kartı gerçek zamanlı olarak günceller.

{  channels: {    feishu: {      streaming: {        mode: "partial", // akışlı kart çıktısı (varsayılan: "partial")        block: { enabled: true }, // tamamlanmış blok akışını etkinleştir      },    },  },}

Tam yanıtı tek bir mesajda göndermek için streaming.mode: "off" değerini ayarlayın; renderMode: "raw" (kartlar yerine düz metin) da kart akışını devre dışı bırakır. streaming.block.enabled varsayılan olarak kapalıdır; yalnızca tamamlanan asistan bloklarının son yanıttan önce gönderilmesini istediğinizde etkinleştirin. Eski Boole streaming değeri ve düz blockStreaming / blockStreamingCoalesce / chunkMode anahtarları, openclaw doctor --fix aracılığıyla bu iç içe yapıya taşınır.

Kota optimizasyonu

İki isteğe bağlı bayrakla Feishu/Lark API çağrılarının sayısını azaltın:

• typingIndicator (varsayılan true): yazıyor tepkisi çağrılarını atlamak için false olarak ayarlayın
• resolveSenderNames (varsayılan true): gönderen profili sorgularını atlamak için false olarak ayarlayın

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

Grup oturumu kapsamı ve konu dizileri

channels.feishu.groupSessionScope (üst düzeyde, hesap başına veya grup başına), grup mesajlarının ajan oturumlarıyla nasıl eşleştirileceğini denetler:

Konu kapsamlarında yerel Feishu/Lark konu grupları, standart konu oturumu anahtarı olarak thread_id (omt_*) olayını kullanır. Yerel bir konu başlatma olayında thread_id yoksa OpenClaw, turu yönlendirmeden önce bunu Feishu'dan tamamlar. OpenClaw'ın dizilere dönüştürdüğü normal grup yanıtları, ilk turun ve takip eden turların aynı oturumda kalması için yanıt kök mesaj kimliğini (om_*) kullanmaya devam eder.

Bot yanıtlarının satır içinde yanıt vermek yerine bir Feishu konu dizisi oluşturmasını veya sürdürmesini sağlamak için replyInThread: "enabled" değerini (üst düzeyde veya grup başına) ayarlayın. topicSessionMode, groupSessionScope değerinin kullanımdan kaldırılmış öncülüdür; groupSessionScope tercih edin.

Feishu çalışma alanı araçları

Plugin; Feishu belgeleri, sohbetleri, bilgi tabanı, bulut depolama, izinler ve Bitable için ajan araçlarının yanı sıra bunlarla eşleşen skills (feishu-doc, feishu-drive, feishu-perm, feishu-wiki) içerir. Araç aileleri channels.feishu.tools tarafından denetlenir:

tools.base, tools.bitable için bir diğer addır; ikisi de ayarlandığında açıkça belirtilen bitable değeri önceliklidir. Hesap başına denetimler accounts.<id>.tools altında bulunur.

Uygulama tam drive:drive kapsamına zaten sahip değilse kök dizinin dışındaki doğrudan feishu_drive info sorguları için drive:drive.metadata:readonly iznini verin. Her iki kapsam da yoksa info, drive:drive:readonly üzerinden eski kök dizin sorgusunu kullanılabilir durumda tutar.

ACP oturumları

Feishu/Lark, DM'ler ve grup dizisi mesajları için ACP'yi destekler. Feishu/Lark ACP metin komutlarıyla çalışır; yerel eğik çizgi komutu menüleri yoktur, bu nedenle /acp ... mesajlarını doğrudan konuşmada kullanın.

Kalıcı ACP bağlaması

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

Sohbetten ACP başlatma

Bir Feishu/Lark DM'sinde veya dizisinde:

/acp spawn codex --thread here

--thread here, DM'ler ve Feishu/Lark dizisi mesajları için çalışır. Bağlı konuşmadaki takip mesajları doğrudan bu ACP oturumuna yönlendirilir.

Çok ajanlı yönlendirme

Feishu/Lark DM'lerini veya gruplarını farklı ajanlara yönlendirmek için bindings kullanın.

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

Yönlendirme alanları:

• match.channel: "feishu"
• match.peer.kind: "direct" (DM) veya "group" (grup sohbeti)
• match.peer.id: kullanıcı Open ID'si (ou_xxx) veya grup kimliği (oc_xxx)

Sorgulama ipuçları için Grup/kullanıcı kimliklerini edinme bölümüne bakın.

Kullanıcı başına ajan yalıtımı (Dinamik Ajan Oluşturma)

Her DM kullanıcısı için otomatik olarak yalıtılmış ajan örnekleri oluşturmak üzere dynamicAgentCreation etkinleştirin. Her kullanıcı şunlara sahip olur:

• Bağımsız çalışma alanı dizini
• Ayrı USER.md / SOUL.md / MEMORY.md
• Özel konuşma geçmişi
• Yalıtılmış skills ve durum

Bu, her kullanıcının kendine ait özel bir yapay zekâ asistanı deneyimine sahip olmasını istediğiniz herkese açık botlar için zorunludur.

Hızlı kurulum

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Kritik: Her kullanıcının DM'sini kendi "ana oturumu" yapar    // USER.md / SOUL.md / MEMORY.md dosyalarını otomatik olarak yükler    // Daha güçlü yalıtım için bunun yerine "per-channel-peer" kullanın    dmScope: "main",  },}

Nasıl çalışır?

Yeni bir kullanıcı ilk DM'sini gönderdiğinde:

1. Kanal benzersiz bir agentId oluşturur: varsayılan hesap için feishu-{user_open_id} veya adlandırılmış bir hesap için sınırlandırılmış, hesap önekli bir kimlik özeti
2. workspaceTemplate yolunda yeni bir çalışma alanı oluşturur
3. Ajanı kaydeder ve bu kullanıcı için bir bağlama oluşturur
4. Çalışma alanı yardımcısı ilk erişimde önyükleme dosyalarının (AGENTS.md, SOUL.md, USER.md vb.) bulunmasını sağlar
5. Bu kullanıcıdan gelecek tüm mesajları kullanıcının özel ajanına yönlendirir

Yapılandırma seçenekleri

Şablon değişkenleri:

• {agentId} - oluşturulan ajan kimliği (ör. feishu-ou_xxxxxx veya feishu-support-<identity_digest>)
• {userId} - gönderenin Feishu open_id değeri (ör. ou_xxxxxx)

Oturum kapsamı

session.dmScope, doğrudan mesajların ajan oturumlarıyla nasıl eşleştirileceğini denetler. Bu, tüm kanalları etkileyen genel bir ayardır.

Ödünleşim: "main" kullanmak, önyükleme dosyalarının (USER.md, SOUL.md, MEMORY.md) otomatik olarak yüklenmesini sağlar; ancak tüm kanallardaki tüm DM'lerin aynı oturum anahtarı kalıbını paylaşması anlamına gelir. Yalıtımın önyükleme dosyalarının otomatik yüklenmesinden daha önemli olduğu herkese açık çok kullanıcılı botlar için "per-channel-peer" kullanmayı ve önyükleme dosyalarını elle yönetmeyi değerlendirin.

Tipik çok kullanıcılı dağıtım

{  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: {    // Yalıtım gereksinimlerinize göre dmScope seçin:    // Önyüklemeyi otomatik yüklemek için "main", daha güçlü yalıtım için "per-channel-peer"    dmScope: "main",  },  bindings: [], // Boş - dinamik ajanlar otomatik olarak bağlanır}

Doğrulama

Dinamik oluşturmanın çalıştığını doğrulamak için Gateway günlüklerini kontrol edin:

feishu: ou_xxxxxx kullanıcısı için "feishu-ou_xxxxxx" dinamik ajanı oluşturuluyor  çalışma alanı: /home/user/.openclaw/workspace-feishu-ou_xxxxxx  ajan dizini: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

Oluşturulan tüm çalışma alanlarını listeleyin:

ls -la ~/.openclaw/workspace-*

Notlar

• Çalışma alanı yalıtımı: Her kullanıcı kendi çalışma alanı dizinine ve agent örneğine sahip olur. Kullanıcılar normal mesajlaşma akışı içinde birbirlerinin konuşma geçmişini veya dosyalarını göremez.
• Güvenlik sınırı: Bu, düşmanca ortak kiracı güvenlik sınırı değil, bir mesajlaşma bağlamı yalıtım mekanizmasıdır. Agent işlemi ve ana makine ortamı paylaşılır.
• Yapılandırma yazmaları etkin kalmalıdır: Dinamik agent oluşturma, agent'ları ve bağlamaları yapılandırmaya yazar; channels.feishu.configWrites, false olduğunda atlanır (varsayılan: etkin).
• bindings boş olmalıdır: Dinamik agent'lar kendi bağlamalarını otomatik olarak kaydeder
• Yükseltme yolu: Mevcut manuel bağlamalar dinamik agent'larla birlikte çalışmaya devam eder
• session.dmScope geneldir: Bu, yalnızca Feishu'yu değil, tüm kanalları etkiler

Yapılandırma referansı

Tam yapılandırma: Gateway yapılandırması

Desteklenen mesaj türleri

Alma

• ✅ Metin
• ✅ Zengin metin (gönderi)
• ✅ Görseller
• ✅ Dosyalar
• ✅ Ses
• ✅ Video/medya
• ✅ Çıkartmalar

Gelen Feishu/Lark sesli mesajları, ham file_key JSON yerine medya yer tutucuları olarak normalleştirilir. tools.media.audio yapılandırıldığında OpenClaw, sesli not kaynağını indirir ve agent işlem sırasından önce paylaşılan ses dökümünü çalıştırır; böylece agent konuşmanın dökümünü alır. Feishu, ses yükünde doğrudan döküm metni içeriyorsa bu metin başka bir ASR çağrısı yapılmadan kullanılır. Bir ses dökümü sağlayıcısı olmadan da agent, ham Feishu kaynak yükü yerine <media:audio> yer tutucusunu ve kaydedilen eki alır.

Gönderme

• ✅ Metin
• ✅ Görseller
• ✅ Dosyalar
• ✅ Ses
• ✅ Video/medya
• ✅ Etkileşimli kartlar (akış güncellemeleri dahil)
• ⚠️ Zengin metin (gönderi tarzı biçimlendirme; Feishu/Lark'ın tüm içerik oluşturma yeteneklerini desteklemez)

Yerel Feishu/Lark ses baloncukları, Feishu audio ileti türünü kullanır ve Ogg/Opus yükleme ortamı (file_type: "opus") gerektirir. Mevcut .opus ve .ogg ortamı doğrudan yerel ses olarak gönderilir. MP3/WAV/M4A ve diğer olası ses biçimleri, yalnızca yanıt sesli teslim istediğinde (audioAsVoice / TTS sesli not yanıtları dâhil ileti aracı asVoice) ffmpeg ile 48kHz Ogg/Opus biçimine dönüştürülür. Sıradan MP3 ekleri normal dosyalar olarak kalır. ffmpeg eksikse veya dönüştürme başarısız olursa OpenClaw bir dosya ekine geri döner ve nedenini günlüğe kaydeder.

Konular ve yanıtlar

• ✅ Satır içi yanıtlar
• ✅ Konu yanıtları
• ✅ Bir konu iletisi yanıtlanırken medya yanıtları konu bağlamını korur

Konu grubu oturum yönlendirmesi Grup oturumu kapsamı ve konu dizileri altında ele alınmıştır.

İlgili

• Kanallara Genel Bakış - desteklenen tüm kanallar
• Eşleştirme - DM kimlik doğrulaması ve eşleştirme akışı
• Gruplar - grup sohbeti davranışı ve bahsetme kısıtlaması
• Kanal Yönlendirmesi - iletiler için oturum yönlendirmesi
• Güvenlik - erişim modeli ve güçlendirme