Feishu

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

Статус: готово к промышленной эксплуатации для личных сообщений боту и групповых чатов. 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. Убедитесь, что выбрано постоянное подключение (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 — размер фрагмента исходящего текста (по умолчанию: 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

Плагин включает инструменты агента для документов, чатов, базы знаний, облачного хранилища, разрешений и Bitable в Feishu, а также соответствующие 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 с частотой 48 кГц с помощью ffmpeg только тогда, когда в ответе запрошена голосовая доставка (audioAsVoice / asVoice инструмента сообщений, включая ответы TTS в виде голосовых сообщений). Обычные вложения MP3 остаются обычными файлами. Если ffmpeg отсутствует или преобразование завершается с ошибкой, OpenClaw использует файловое вложение и записывает причину в журнал.

Ветки и ответы

• ✅ Встроенные ответы
• ✅ Ответы в ветках
• ✅ Ответы с медиафайлами сохраняют привязку к ветке при ответе на сообщение в ветке

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

Связанные материалы

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