Feishu

OpenClaw підключається до Feishu/Lark (універсальної платформи для спільної роботи) через офіційний Plugin @openclaw/feishu: особисті повідомлення бота, групові чати, потокові відповіді у вигляді карток та інструменти Feishu для документів, вікі, диска й Bitable.

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

Швидкий початок

openclaw channels login --channel feishu

openclaw gateway restart

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

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

Налаштуйте channels.feishu.dmPolicy (стандартне значення: pairing), щоб визначити, хто може надсилати боту особисті повідомлення:

Схвалення запиту на сполучення:

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Групові чати

Політика груп (channels.feishu.groupPolicy, стандартне значення: allowlist):

Вимога згадування (channels.feishu.requireMention):

• Стандартно: потрібне @згадування, крім випадків, коли чинна політика групи — "open"; тоді стандартним значенням є false, щоб повідомлення, які не можуть містити згадування (наприклад, зображення), усе одно надходили агенту.
• Явно встановіть true або false, щоб перевизначити це; перевизначення для окремої групи: channels.feishu.groups.<chat_id>.requireMention.
• Трансляційні згадування @all і @_all не вважаються згадуваннями бота. Повідомлення, у якому одночасно згадано @all і безпосередньо бота, усе одно вважається згадуванням бота.

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

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

{  channels: {    feishu: {      groupPolicy: "open", // для "open" стандартне значення requireMention — false    },  },}

Дозволити всі групи, але й надалі вимагати @згадування

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

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

{  channels: {    feishu: {      groupPolicy: "allowlist",      // Ідентифікатори груп мають такий вигляд: oc_xxx      groupAllowFrom: ["oc_xxx", "oc_yyy"],    },  },}

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

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

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

{  channels: {    feishu: {      groupPolicy: "allowlist",      groupAllowFrom: ["oc_xxx"],      groups: {        oc_xxx: {          // Значення open_id користувачів мають такий вигляд: ou_xxx          allowFrom: ["ou_user1", "ou_user2"],        },      },    },  },}

channels.feishu.groupSenderAllowFrom задає однаковий список дозволених відправників для всіх груп; значення allowFrom окремої групи має вищий пріоритет.

Отримання ідентифікаторів груп і користувачів

Ідентифікатори груп (chat_id, формат: oc_xxx)

Відкрийте групу у Feishu/Lark, натисніть піктограму меню у верхньому правому куті та перейдіть до Settings. Ідентифікатор групи (chat_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. Переконайтеся, що вибрано persistent connection (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: "Основний бот",          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },        backup: {          appId: "cli_yyy",          appSecret: "yyy",          name: "Резервний бот",          enabled: false,        },      },    },  },}

defaultAccount визначає, який обліковий запис використовується, коли вихідні API не вказують accountId. Записи облікових записів успадковують налаштування верхнього рівня; більшість ключів верхнього рівня можна перевизначити для окремого облікового запису. accounts.<id>.tts має таку саму структуру, як messages.tts, і глибоко об’єднується з глобальною конфігурацією TTS, тому конфігурації Feishu з кількома ботами можуть зберігати спільні облікові дані провайдера глобально, перевизначаючи для кожного облікового запису лише голос, модель, персону або автоматичний режим.

Обмеження повідомлень

• textChunkLimit — розмір фрагмента вихідного тексту (стандартне значення: 4000 символів)
• streaming.chunkMode — "length" (стандартне значення) розділяє текст на межі обмеження; "newline" віддає перевагу межам нових рядків
• mediaMaxMb — обмеження на завантаження та отримання медіафайлів (стандартне значення: 30 МБ)

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

Feishu/Lark підтримує потокові відповіді через інтерактивні картки (API потокового передавання Card Kit). Коли цю функцію ввімкнено, бот оновлює картку в реальному часі під час генерування тексту.

{  channels: {    feishu: {      streaming: {        mode: "partial", // потокове виведення картки (стандартне значення: "partial")        block: { enabled: true }, // увімкнення потокового передавання завершених блоків      },    },  },}

Установіть streaming.mode: "off", щоб надсилати повну відповідь одним повідомленням; renderMode: "raw" (звичайний текст замість карток) також вимикає потокові картки. streaming.block.enabled стандартно вимкнено; вмикайте його лише тоді, коли потрібно надсилати завершені блоки асистента до остаточної відповіді. Застаріле логічне значення streaming і плоскі ключі blockStreaming / blockStreamingCoalesce / chunkMode переносяться до цієї вкладеної структури за допомогою openclaw doctor --fix.

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

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

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

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

Область групового сеансу та тематичні гілки

channels.feishu.groupSessionScope (на верхньому рівні, для окремого облікового запису або окремої групи) визначає, як групові повідомлення зіставляються із сеансами агента:

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

Установіть replyInThread: "enabled" (на верхньому рівні або для окремої групи), щоб відповіді бота створювали або продовжували тематичну гілку Feishu замість вбудованої відповіді. topicSessionMode є застарілим попередником groupSessionScope; віддавайте перевагу groupSessionScope.

Інструменти робочого простору Feishu

Plugin постачається з інструментами агента для документів Feishu, чатів, бази знань, хмарного сховища, дозволів і Bitable, а також відповідними Skills (feishu-doc, feishu-drive, feishu-perm, feishu-wiki). Сімейства інструментів контролюються параметром channels.feishu.tools:

tools.base — це псевдонім для tools.bitable; якщо задано обидва значення, пріоритет має явно вказане значення bitable. Обмеження для окремих облікових записів містяться в accounts.<id>.tools.

Надайте drive:drive.metadata:readonly для прямих пошуків feishu_drive info поза кореневим каталогом, якщо застосунок ще не має повної області доступу drive:drive. Без жодної з цих областей доступу info залишає доступним застарілий пошук у кореневому каталозі через drive:drive:readonly.

Сеанси ACP

Feishu/Lark підтримує ACP для приватних повідомлень і повідомлень у гілках груп. ACP у Feishu/Lark керується текстовими командами — вбудованих меню команд із косою рискою немає, тому використовуйте повідомлення /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) або ідентифікатор групи (oc_xxx)

Поради щодо пошуку див. у розділі Отримання ідентифікаторів групи/користувача.

Ізоляція агента для кожного користувача (динамічне створення агентів)

Увімкніть dynamicAgentCreation, щоб автоматично створювати ізольовані екземпляри агентів для кожного користувача приватних повідомлень. Кожен користувач отримує власні:

• Незалежний каталог робочого простору
• Окремі USER.md / SOUL.md / MEMORY.md
• Приватну історію розмов
• Ізольовані навички та стан

Це необхідно для загальнодоступних ботів, якщо кожен користувач повинен мати власний приватний досвід взаємодії з ШІ-помічником.

Швидке налаштування

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Критично важливо: робить приватні повідомлення кожного користувача його «основним сеансом»    // Автоматично завантажує USER.md / SOUL.md / MEMORY.md    // Для посиленої ізоляції натомість використовуйте "per-channel-peer"    dmScope: "main",  },}

Як це працює

Коли новий користувач надсилає перше приватне повідомлення:

1. Канал створює унікальний agentId: feishu-{user_open_id} для типового облікового запису або обмежений дайджест ідентичності з префіксом облікового запису для іменованого облікового запису
2. Створюється новий робочий простір за шляхом workspaceTemplate
3. Агент реєструється, і для цього користувача створюється прив’язування
4. Допоміжний засіб робочого простору забезпечує наявність початкових файлів (AGENTS.md, SOUL.md, USER.md тощо) під час першого доступу
5. Усі майбутні повідомлення цього користувача спрямовуються до його виділеного агента

Параметри конфігурації

Змінні шаблону:

• {agentId} — створений ідентифікатор агента (наприклад, feishu-ou_xxxxxx або feishu-support-<identity_digest>)
• {userId} — Feishu open_id відправника (наприклад, ou_xxxxxx)

Область дії сеансу

session.dmScope визначає, як приватні повідомлення зіставляються із сеансами агентів. Це глобальне налаштування, яке впливає на всі канали.

Компроміс: використання "main" вмикає автоматичне завантаження початкових файлів (USER.md, SOUL.md, MEMORY.md), але означає, що всі приватні повідомлення в усіх каналах використовують однаковий шаблон ключа сеансу. Для загальнодоступних багатокористувацьких ботів, де ізоляція важливіша за автоматичне завантаження початкових файлів, розгляньте "per-channel-peer" і керуйте початковими файлами вручну.

Типове багатокористувацьке розгортання

{  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: {    // Виберіть dmScope відповідно до потреб в ізоляції:    // "main" для автоматичного завантаження початкових файлів, "per-channel-peer" для посиленої ізоляції    dmScope: "main",  },  bindings: [], // Порожній масив — динамічні агенти прив’язуються автоматично}

Перевірка

Перевірте журнали Gateway, щоб переконатися, що динамічне створення працює:

feishu: створення динамічного агента "feishu-ou_xxxxxx" для користувача ou_xxxxxx  робочий простір: /home/user/.openclaw/workspace-feishu-ou_xxxxxx  каталог агента: /home/user/.openclaw/agents/feishu-ou_xxxxxx/agent

Перелічіть усі створені робочі простори:

ls -la ~/.openclaw/workspace-*

Примітки

• Ізоляція робочого простору: кожен користувач отримує власний каталог робочого простору й екземпляр агента. У межах звичайного обміну повідомленнями користувачі не можуть бачити історію розмов або файли один одного.
• Межа безпеки: це механізм ізоляції контексту обміну повідомленнями, а не межа безпеки для недовірених співорендарів. Процес агента й середовище хоста є спільними.
• Запис конфігурації має залишатися ввімкненим: динамічне створення агентів записує агентів і прив’язування до конфігурації; воно пропускається, коли channels.feishu.configWrites має значення false (типово: увімкнено).
• bindings має бути порожнім: динамічні агенти автоматично реєструють власні прив’язування
• Шлях оновлення: наявні прив’язування, створені вручну, продовжують працювати разом із динамічними агентами
• session.dmScope є глобальним: це впливає на всі канали, а не лише на Feishu

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

Повна конфігурація: Конфігурація 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 із частотою 48kHz за допомогою ffmpeg лише тоді, коли відповідь запитує голосове доставлення (audioAsVoice / інструмент повідомлень asVoice, зокрема відповіді TTS у вигляді голосових нотаток). Звичайні вкладення MP3 залишаються звичайними файлами. Якщо ffmpeg відсутній або перетворення не вдається, OpenClaw повертається до вкладення файлу та записує причину в журнал.

Гілки та відповіді

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

Маршрутизацію сеансів тематичних груп описано в розділі Область групового сеансу та тематичні гілки.

Пов’язані матеріали

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