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",      // Идентификаторы групп выглядят так: 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_ids выглядят так: 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, // включить вывод потоковой карточки (по умолчанию: true)      blockStreaming: true, // включить потоковую передачу завершенных блоков    },  },}

Установите 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 и состояние

Это важно для публичных ботов, где нужно, чтобы у каждого пользователя был собственный приватный опыт общения с ИИ-ассистентом.

Быстрая настройка

{  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} - сгенерированный ID агента (например, feishu-ou_xxxxxx или feishu-support-<identity_digest>)
• {userId} - Feishu open_id отправителя (например, ou_xxxxxx)

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

session.dmScope управляет тем, как личные сообщения сопоставляются с сеансами агента. Это глобальная настройка, которая влияет на все каналы.

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

{  session: {    // For single-user personal bots: enables auto bootstrap loading    dmScope: "main",     // For public multi-user bots: stronger isolation    // 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: {    // Choose dmScope based on your isolation needs:    // "main" for bootstrap auto-loading, "per-channel-peer" for stronger isolation    dmScope: "main",  },  bindings: [], // Empty - dynamic agents auto-bind}

Проверка

Проверьте журналы 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_*), чтобы первый ход и последующий ход оставались в одной сессии.

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

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