Feishu

Feishu/Lark, ekiplerin sohbet ettiği, belge paylaştığı, takvimleri yönettiği ve işleri birlikte tamamladığı hepsi bir arada bir işbirliği platformudur.

Durum: bot DM'leri + grup sohbetleri için üretime hazır. WebSocket varsayılan moddur; Webhook modu isteğe bağlıdır.

# Hızlı başlangıç

openclaw channels login --channel feishu

openclaw gateway restart

# Erişim denetimi

# Doğrudan mesajlar

Bota kimlerin DM gönderebileceğini denetlemek için dmPolicy yapılandırın:

• "pairing" - bilinmeyen kullanıcılar bir eşleştirme kodu alır; CLI üzerinden onaylayın
• "allowlist" - yalnızca allowFrom içinde listelenen kullanıcılar sohbet edebilir (varsayılan: yalnızca bot sahibi)
• "open" - yalnızca allowFrom, "*" içerdiğinde herkese açık DM'lere izin ver; kısıtlayıcı girdilerle yalnızca eşleşen kullanıcılar sohbet edebilir
• "disabled" - tüm DM'leri devre dışı bırak

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

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

# Grup sohbetleri

Grup ilkesi (channels.feishu.groupPolicy):

Varsayılan: allowlist

Bahsetme gereksinimi (channels.feishu.requireMention):

• true - @mention gerektir (varsayılan)
• false - @mention olmadan yanıt ver
• Grup bazında geçersiz kılma: channels.feishu.groups.<chat_id>.requireMention
• Yalnızca yayın amaçlı @all ve @_all, bot bahsetmeleri olarak değerlendirilmez. Hem @all hem de doğrudan botu bahseden bir mesaj yine bot bahsetmesi sayılır.

# Grup yapılandırma örnekleri

# Tüm gruplara izin ver, @mention gerekli değil

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

# Tüm gruplara izin ver, yine de @mention gerektir

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

# Yalnızca belirli gruplara izin ver

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

allowlist modunda, açık bir groups.<chat_id> girdisi ekleyerek bir grubu da kabul edebilirsiniz. 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 grupları tek başlarına kabul etmez.

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

# Grup içinde gönderenleri kısıtla

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

# Grup/kullanıcı kimliklerini alma

# Grup kimlikleri (chat_id, biçim: oc_xxx)

Grubu Feishu/Lark içinde açın, sağ üst köşedeki menü simgesine tıklayın ve Ayarlar 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, ardından günlükleri kontrol edin:

openclaw logs --follow

Günlük çıktısında open_id 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. Botu @mention ettiğ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 mesaj almıyor

1. Botun Feishu Open Platform / Lark Developer içinde yayımlandığından ve onaylandığından emin olun
2. Olay aboneliğinin im.message.receive_v1 içerdiğinden emin olun
3. Kalıcı bağlantı (WebSocket) seçildiğinden emin olun
4. Gerekli tüm izin kapsamlarının verildiğinden emin olun
5. Gateway'in çalıştığından emin olun: openclaw gateway status
6. Günlükleri kontrol edin: openclaw logs --follow

# App Secret sızdı

1. App Secret değerini Feishu Open Platform / Lark Developer içinde 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. accounts.<id>.tts, messages.tts ile aynı şekli kullanır ve genel TTS yapılandırmasının üzerine derin birleştirme uygular; böylece çok botlu Feishu kurulumları, hesap başına yalnızca ses, model, persona veya otomatik modu geçersiz kılarken paylaşılan sağlayıcı kimlik bilgilerini genel olarak tutabilir.

# Mesaj sınırları

• textChunkLimit - giden metin parçası boyutu (varsayılan: 2000 karakter)
• mediaMaxMb - medya yükleme/indirme sınırı (varsayılan: 30 MB)

# Akış

Feishu/Lark etkileşimli kartlar aracılığıyla akış yanıtlarını destekler. Etkinleştirildiğinde bot, metin oluştururken kartı gerçek zamanlı olarak günceller.

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

Tam yanıtı tek mesajda göndermek için streaming: false ayarlayın. blockStreaming varsayılan olarak kapalıdır; yalnızca tamamlanmış asistan bloklarının son yanıttan önce gönderilmesini istediğinizde etkinleştirin.

# 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 ayarlayın
• resolveSenderNames (varsayılan true): gönderen profil aramalarını atlamak için false ayarlayın

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

# ACP oturumları

Feishu/Lark, DM'ler ve grup iş parçacığı mesajları için ACP'yi destekler. Feishu/Lark ACP metin komutuyla yönlendirilir - yerel eğik çizgi komutu menüleri yoktur, bu yüzden /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'inde veya iş parçacığında:

/acp spawn codex --thread here

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

# Çok aracılı yönlendirme

Feishu/Lark DM'lerini veya gruplarını farklı aracılara 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)

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

# Yapılandırma referansı

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

# Desteklenen ileti türleri

# Alma

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

Gelen Feishu/Lark ses iletileri 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 ajan turundan önce paylaşılan ses transkripsiyonunu çalıştırır; böylece ajan konuşma transkriptini alır. Feishu, ses yükünde transkript metnini doğrudan içeriyorsa bu metin başka bir ASR çağrısı yapılmadan kullanılır. Ses transkripsiyonu sağlayıcısı olmadan ajan yine de ham Feishu kaynak yükü yerine bir <media:audio> yer tutucusu ve kaydedilmiş 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; tam Feishu/Lark yazma yeteneklerini desteklemez)

Yerel Feishu/Lark ses baloncukları Feishu audio ileti türünü kullanır ve Ogg/Opus yükleme medyası (file_type: "opus") gerektirir. Mevcut .opus ve .ogg medya doğrudan yerel ses olarak gönderilir. MP3/WAV/M4A ve diğer olası ses formatları yalnızca yanıt sesli teslimat istediğinde (audioAsVoice / ileti aracı asVoice, TTS sesli not yanıtları dahil) ffmpeg ile 48kHz Ogg/Opus'a 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 nedeni günlüğe kaydeder.

# Konular ve yanıtlar

• ✅ Satır içi yanıtlar
• ✅ Konu yanıtları
• ✅ Bir konu iletisine yanıt verirken medya yanıtları konu farkındalığını korur

groupSessionScope: "group_topic" ve "group_topic_sender" için yerel Feishu/Lark konu grupları, olay thread_id değerini (omt_*) kanonik konu oturumu anahtarı olarak kullanır. Yerel bir konu başlatıcı olayı thread_id değerini atlıyorsa OpenClaw turu yönlendirmeden önce bunu Feishu'dan doldurur. OpenClaw'ın konulara dönüştürdüğü normal grup yanıtları, ilk tur ve takip turu aynı oturumda kalsın diye yanıt kök ileti ID'sini (om_*) kullanmaya devam eder.

# İ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 denetimi
• Kanal Yönlendirme - iletiler için oturum yönlendirme
• Güvenlik - erişim modeli ve sağlamlaştırma