Feishu

Feishu/Lark — это универсальная платформа для совместной работы, где команды общаются в чатах, делятся документами, управляют календарями и работают вместе.

Статус: готово к production для личных сообщений боту и групповых чатов. WebSocket — режим по умолчанию; режим Webhook необязателен.

Быстрый старт

openclaw channels login --channel feishu

openclaw gateway restart

Управление доступом

Личные сообщения

Настройте dmPolicy, чтобы управлять тем, кто может отправлять личные сообщения боту:

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

Подтвердить запрос на сопряжение:

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". Подстановочные значения по умолчанию в 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"],        },      },    },  },}

Получить идентификаторы групп/пользователей

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

Откройте группу в Feishu/Lark, нажмите значок меню в правом верхнем углу и перейдите в Настройки. Идентификатор группы (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 - размер фрагмента исходящего текста (по умолчанию: 2000 символов)
• mediaMaxMb - лимит загрузки/скачивания медиа (по умолчанию: 30 МБ)

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

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) или идентификатор группы (oc_xxx)

См. Получить идентификаторы групп/пользователей для советов по поиску.

Изоляция агентов по пользователям (динамическое создание агентов)

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

• Независимый каталог рабочей области
• Отдельные 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",  },}

Как это работает

Когда новый пользователь отправляет первое личное сообщение:

1. Канал генерирует уникальный agentId: feishu-{user_open_id} для аккаунта по умолчанию или ограниченный хеш идентичности с префиксом аккаунта для именованного аккаунта
2. Создаёт новую рабочую область по пути workspaceTemplate
3. Регистрирует агента и создаёт привязку для этого пользователя
4. Помощник рабочей области обеспечивает наличие начальных файлов (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" включает автоматическую загрузку файлов начальной настройки (USER.md, SOUL.md, MEMORY.md), но означает, что все ЛС во всех каналах используют один и тот же шаблон ключей сеанса. Для публичных многопользовательских ботов, где изоляция важнее автоматической загрузки начальной настройки, рассмотрите "per-channel-peer" и управляйте файлами начальной настройки вручную.

{  session: {    // Для однопользовательских личных ботов: включает автоматическую загрузку начальной настройки    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" для автоматической загрузки начальной настройки, "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 и другие вероятные аудиоформаты транскодируются в 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 превращает в темы, продолжают использовать ID корневого сообщения ответа (om_*), чтобы первый ход и последующий ход оставались в одной сессии.

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

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