Feishu

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

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

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

openclaw channels login --channel feishu

openclaw gateway restart

Контроль доступу

Прямі повідомлення

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

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

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

openclaw pairing list feishuopenclaw pairing approve feishu <CODE>

Групові чати

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

За замовчуванням: allowlist

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

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

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

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

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

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

{  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". Шаблонні значення за замовчуванням у 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, надішліть DM боту, потім перевірте журнали:

openclaw logs --follow

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

openclaw pairing list feishu

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

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

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

1. Переконайтеся, що бота додано до групи
2. Переконайтеся, що ви @mention бота (потрібно за замовчуванням)
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 вимкнено за замовчуванням; вмикайте це лише тоді, коли хочете перед фінальною відповіддю надсилати завершені блоки assistant.

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

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

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

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

Сесії ACP

Feishu/Lark підтримує ACP для DM і повідомлень у групових гілках. 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 із чату

У DM або гілці Feishu/Lark:

/acp spawn codex --thread here

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

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

Використовуйте bindings, щоб маршрутизувати DM або групи 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" (DM) або "group" (груповий чат)
• match.peer.id: Open ID користувача (ou_xxx) або ID групи (oc_xxx)

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

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

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

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

Це важливо для публічних ботів, де ви хочете, щоб кожен користувач мав власний приватний досвід AI-асистента.

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

{  channels: {    feishu: {      dmPolicy: "open",      allowFrom: ["*"],      dynamicAgentCreation: {        enabled: true,        workspaceTemplate: "~/.openclaw/workspace-{agentId}",        agentDirTemplate: "~/.openclaw/agents/{agentId}/agent",      },    },  },  session: {    // Critical: makes each user's DM their "main session"    // Automatically loads USER.md / SOUL.md / MEMORY.md    // For stronger isolation, use "per-channel-peer" instead    dmScope: "main",  },}

Як це працює

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

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

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

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

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

Область сеансу

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

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

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

Перевірка

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

feishu: creating dynamic agent "feishu-ou_xxxxxx" for user ou_xxxxxxworkspace: /Users/you/.openclaw/workspace-feishu-ou_xxxxxxfeishu: dynamic agent created, new route: agent:feishu-ou_xxxxxx:main

Вивести всі створені робочі простори:

ls -la ~/.openclaw/workspace-*

Примітки

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

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

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

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

Отримання

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

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

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

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

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

Пов’язане

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