Feishu

Feishu/Lark — це універсальна платформа для співпраці, де команди спілкуються, обмінюються документами, керують календарями та виконують роботу разом.

Статус: готово до production для особистих повідомлень бота й групових чатів. WebSocket є типовим режимом; режим Webhook необов’язковий.

Швидкий старт

openclaw channels login --channel feishu

openclaw gateway restart

Керування доступом

Особисті повідомлення

Налаштуйте dmPolicy, щоб керувати тим, хто може писати боту в особисті повідомлення:

• "pairing" - невідомі користувачі отримують код сполучення; підтвердьте через CLI
• "allowlist" - спілкуватися можуть лише користувачі, перелічені в allowFrom (типово: лише власник бота)
• "open" - дозволити публічні особисті повідомлення лише коли allowFrom містить "*"; з обмежувальними записами спілкуватися можуть лише відповідні користувачі
• "disabled" - вимкнути всі особисті повідомлення

Підтвердити запит на сполучення:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Групові чати

Політика груп (channels.feishu.groupPolicy):

Типово: allowlist

Вимога згадки (channels.feishu.requireMention):

• true - вимагати @згадку (типово)
• false - відповідати без @згадки
• Перевизначення для окремої групи: channels.feishu.groups.<chat_id>.requireMention
• Широкомовні @all і @_all не вважаються згадками бота. Повідомлення, у якому згадано і @all, і безпосередньо бота, все одно зараховується як згадка бота.

Приклади конфігурації груп

Дозволити всі групи, @згадка не потрібна

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

Дозволити всі групи, але все ще вимагати @згадку

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

Дозволити лише певні групи

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

У режимі allowlist ви також можете допустити групу, додавши явний запис groups.<chat_id>. Явні записи не перевизначають groupPolicy: "disabled". Типові налаштування з wildcard у groups.* налаштовують відповідні групи, але самі по собі не допускають групи.

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

Обмежити відправників у межах групи

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

Отримати ID групи/користувача

ID груп (chat_id, формат: oc_xxx)

Відкрийте групу у Feishu/Lark, натисніть значок меню у верхньому правому куті та перейдіть до Налаштувань. ID групи (chat_id) наведено на сторінці налаштувань.

ID користувачів (open_id, формат: ou_xxx)

Запустіть Gateway, надішліть особисте повідомлення боту, а потім перевірте журнали:

openclaw logs --follow

Знайдіть open_id у виводі журналу. Також можна перевірити запити на сполучення, що очікують:

openclaw pairing list feishu

Поширені команди

Усунення несправностей

Бот не відповідає в групових чатах

1. Переконайтеся, що бота додано до групи
2. Переконайтеся, що ви @згадали бота (типово обов’язково)
3. Перевірте, що groupPolicy не дорівнює "disabled"
4. Перевірте журнали: openclaw logs --follow

Бот не отримує повідомлення

1. Переконайтеся, що бот опублікований і схвалений у Feishu Open Platform / Lark Developer
2. Переконайтеся, що підписка на події містить im.message.receive_v1
3. Переконайтеся, що вибрано постійне з’єднання (WebSocket)
4. Переконайтеся, що надано всі потрібні області дозволів
5. Переконайтеся, що Gateway запущено: openclaw gateway status
6. Перевірте журнали: openclaw logs --follow

Налаштування через QR не реагує в мобільному застосунку Feishu

1. Запустіть налаштування знову: openclaw channels login --channel feishu
2. Виберіть ручне налаштування
3. У Feishu Open Platform створіть власний застосунок і скопіюйте його App ID та App Secret
4. Вставте ці облікові дані в майстер налаштування

App Secret став відомий стороннім

1. Скиньте App Secret у Feishu Open Platform / Lark Developer
2. Оновіть значення у своїй конфігурації
3. Перезапустіть Gateway: openclaw gateway restart

Розширена конфігурація

Кілька облікових записів

{  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 керує тим, який обліковий запис використовується, коли вихідні API не вказують accountId. accounts.<id>.tts використовує ту саму форму, що й messages.tts, і глибоко об’єднується з глобальною конфігурацією TTS, тому налаштування Feishu із кількома ботами можуть зберігати спільні облікові дані провайдера глобально, перевизначаючи лише голос, модель, персону або автоматичний режим для кожного облікового запису.

Ліміти повідомлень

• textChunkLimit - розмір фрагмента вихідного тексту (типово: 2000 символів)
• mediaMaxMb - ліміт завантаження/скачування медіа (типово: 30 MB)

Потокове передавання

Feishu/Lark підтримує потокові відповіді через інтерактивні картки. Коли це ввімкнено, бот оновлює картку в реальному часі під час генерації тексту.

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

Установіть streaming: false, щоб надіслати повну відповідь одним повідомленням. blockStreaming типово вимкнено; увімкніть його лише тоді, коли потрібно передавати завершені блоки асистента перед фінальною відповіддю.

Оптимізація квоти

Зменште кількість викликів API Feishu/Lark за допомогою двох необов’язкових прапорців:

• typingIndicator (типово true): установіть false, щоб пропускати виклики реакції набору тексту
• resolveSenderNames (типово true): установіть false, щоб пропускати пошук профілів відправників

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

Сеанси ACP

Feishu/Lark підтримує ACP для особистих повідомлень і повідомлень у групових тредах. ACP у Feishu/Lark керується текстовими командами - нативних меню slash-команд немає, тому використовуйте повідомлення /acp ... безпосередньо в розмові.

Постійне прив’язування ACP

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

Створити ACP з чату

У особистому повідомленні або треді Feishu/Lark:

/acp spawn codex --thread here

--thread here працює для особистих повідомлень і повідомлень у тредах Feishu/Lark. Подальші повідомлення у прив’язаній розмові спрямовуються безпосередньо до цього сеансу ACP.

Маршрутизація кількох агентів

Використовуйте bindings, щоб спрямовувати особисті повідомлення або групи Feishu/Lark до різних агентів.

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

Поля маршрутизації:

• match.channel: "feishu"
• match.peer.kind: "direct" (особисте повідомлення) або "group" (груповий чат)
• match.peer.id: Open ID користувача (ou_xxx) або ID групи (oc_xxx)

Див. Отримати ID групи/користувача, щоб отримати поради з пошуку.

Довідник конфігурації

Повна конфігурація: Конфігурація Gateway

Підтримувані типи повідомлень

Отримання

• ✅ Текст
• ✅ Форматований текст (допис)
• ✅ Зображення
• ✅ Файли
• ✅ Аудіо
• ✅ Відео/медіа
• ✅ Стікери

Вхідні аудіоповідомлення Feishu/Lark нормалізуються як медіазаповнювачі замість необробленого JSON file_key. Коли налаштовано tools.media.audio, OpenClaw завантажує ресурс голосової нотатки та запускає спільну транскрипцію аудіо перед ходом агента, тому агент отримує транскрипт мовлення. Якщо Feishu включає текст транскрипта безпосередньо в аудіокорисне навантаження, цей текст використовується без ще одного виклику ASR. Без постачальника транскрипції аудіо агент усе одно отримує заповнювач <media:audio> разом зі збереженим вкладенням, а не необроблене корисне навантаження ресурсу Feishu.

Надсилання

• ✅ Текст
• ✅ Зображення
• ✅ Файли
• ✅ Аудіо
• ✅ Відео/медіа
• ✅ Інтерактивні картки (зокрема потокові оновлення)
• ⚠️ Форматований текст (форматування в стилі допису; не підтримує повні можливості створення вмісту Feishu/Lark)

Нативні аудіобульбашки Feishu/Lark використовують тип повідомлення Feishu audio і потребують завантаженого медіа Ogg/Opus (file_type: "opus"). Наявні медіа .opus і .ogg надсилаються безпосередньо як нативне аудіо. MP3/WAV/M4A та інші ймовірні аудіоформати перекодовуються в Ogg/Opus 48 кГц за допомогою ffmpeg лише тоді, коли відповідь запитує доставку голосом (audioAsVoice / інструмент повідомлень asVoice, зокрема відповіді TTS у вигляді голосових нотаток). Звичайні вкладення MP3 залишаються звичайними файлами. Якщо ffmpeg відсутній або перетворення завершується невдало, OpenClaw повертається до файлового вкладення й журналює причину.

Потоки та відповіді

• ✅ Вбудовані відповіді
• ✅ Відповіді в потоці
• ✅ Медіавідповіді залишаються обізнаними про потік під час відповіді на повідомлення в потоці

Для groupSessionScope: "group_topic" і "group_topic_sender" нативні тематичні групи Feishu/Lark використовують подієвий thread_id (omt_*) як канонічний ключ тематичного сеансу. Якщо нативна подія початку теми не містить thread_id, OpenClaw доповнює його з Feishu перед маршрутизацією ходу. Звичайні відповіді в групі, які OpenClaw перетворює на потоки, і надалі використовують ідентифікатор кореневого повідомлення відповіді (om_*), щоб перший хід і наступний хід залишалися в одному сеансі.

Пов’язане

• Огляд каналів - усі підтримувані канали
• Спарювання - автентифікація приватних повідомлень і потік спарювання
• Групи - поведінка групового чату та контроль згадок
• Маршрутизація каналів - маршрутизація сеансів для повідомлень
• Безпека - модель доступу та посилення захисту