🏠 Главная › user guide › feishu

Настройка Фейшу/Жаворонка

Hermes Agent интегрируется с Feishu и Lark в качестве полнофункционального бота. После подключения вы можете общаться с агентом в личных сообщениях или групповых чатах, получать результаты задач cron в домашнем чате, а также отправлять текстовые, графические, аудио и файловые приложения через обычный шлюзовой поток.

Интеграция поддержки обоих устройств:

Как себя ведет Гермес

Контекст Поведение
Личные сообщения Гермес отвечает за каждое сообщение.
Групповые чаты Гермес отвечает только тогда, когда бота упоминают @ в чате.
Общие групповые чаты По умолчанию история сессии изолирована для пользователя внутри общего чата.

Это поведение в общих чатах контролируется в config.yaml:

group_sessions_per_user: true

Установите «false», только если вы явно хотите один общий диалог в чате.

Шаг 1: Создайте приложение Feishu / Lark

рекомендуется: Сканирование для создания (одна команда)

hermes gateway setup

Выберите Feishu / Lark и отсканируйте QR-код с помощью мобильного приложения Feishu или Lark. Гермес автоматически создает приложение-бот с указанными разрешениями и сохраняет учетные данные.

Альтернатива: Ручная настройка

Если сканер для изготовления недоступен, мастер переходит к ручному вводу:

  1. Откройте консоль разработчика Feishu или Lark:
  2. Фейшу: https://open.feishu.cn/
  3. Жаворонок: https://open.larksuite.com/
  4. Создайте новое приложение.
  5. В разделе Учётные данные и основная информация скопируйте Идентификатор приложения и Секрет приложения.
  6. Включите возможность Бот для приложения.
  7. Запустите «Настройка шлюза Гермеса», выберите Feishu / Lark и введите учётные данные при запросе.:::предупреждение Храните секрет приложения в секрете. Любой, у кого он есть, может выдать себя за ваше приложение.

Шаг 2: Выберите режим подключения

рекомендуется: Режим WebSocket

Используйте режим WebSocket, когда Hermes работает на вашем ноутбуке, на рабочей станции или в конфиденциальном режиме. Публичный URL-адрес не требуется. Официальный SDK Lark обеспечивает и поддерживает постоянное исходное WebSocket-соединение с автоматическим переподключением.

FEISHU_CONNECTION_MODE=websocket

Требования: Должен быть установлен пакет Python websockets. SDK управляет жизненным циклом соединений, удержанием активности и автоматическим переподключением внутри себя.

Как это работает: Адаптер запускает WebSocket-клиент SDK Lark в фоновом потоке исполнителя. Входящие события (сообщения, состояния, действия с карточками) отправляются в основной цикл asyncio. При отключении SDK автоматически переподключается.

Опционально: Режим Webhook

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

FEISHU_CONNECTION_MODE=webhook

В режиме вебхука Hermes запускает HTTP-сервер (через aiohttp) и обслуживает конечную точку Feishu по адресу:

/feishu/webhook

Требования: Должен быть установлен пакет Python aiohttp.

Вы можете настроить адрес привязки и путь вебхук-сервера:

FEISHU_WEBHOOK_HOST=127.0.0.1   # по умолчанию: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # по умолчанию: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # по умолчанию: /feishu/webhook

Когда Feishu отправляет запрос на проверку URL-адреса (type: url_verification), вебхук автоматически отвечает, чтобы вы могли перейти к подписке в консоли разработчика Feishu.

Шаг 3: Настраиваем Гермес

Вариант А: Интерактивная настройка

hermes gateway setup

Выберите Фейшу/Жаворонок и заполните поля.

Вариант Б: Ручная настройка

Добавьте следующее в ~/.hermes/.env:

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# Опционально, но настоятельно рекомендуется
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

FEISHU_DOMAIN принимает:

Шаг 4: Запустите шлюз

hermes gateway

Затем отправьте сообщение боту из Feishu/Lark, чтобы убедиться, что соединение активно.

Домашний чат

Используйте /set-home в чате Feishu/Lark, чтобы отметить его как домашний канал для результатов задач cron и кроссплатформенных каналов.

Вы также можете предварительно настроить его:

FEISHU_HOME_CHANNEL=oc_xxx

Безопасность

Белый список пользователей

Для производственного использования установите белый список Open ID Feishu:

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

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

Ключ шифрования вебхука

При работе в режиме вебхука установите ключ шифрования для проверки подлинности входящего приложения вебхука:

FEISHU_ENCRYPT_KEY=your-encrypt-key

Этот ключ находится в разделе Подписки событий схемы вашего приложения Feishu. Если он установлен, после каждого запроса вебхука используйте алгоритм:

SHA256(timestamp + nonce + encrypt_key + body)

Вычисленный хэш сравнивается с заголовком x-жаворонка-подписи с использованием сравнения, безопасного во времени. Запросы с недействительной или отсутствующей подписью отклоняются с HTTP 401.:::совет В режиме WebSocket проверка лицензии обрабатывается собственным SDK, поэтому FEISHU_ENCRYPT_KEY опционален. В режиме веб-перехватчика он настоятельно рекомендуется для производства.

Верификация токенов

Дополнительный уровень аутентификации, который теперь подает «токен» внутри услуги вебхука:

FEISHU_VERIFICATION_TOKEN=your-verification-token

Этот токен также находится в разделе Подписки событий вашего приложения Feishu. Если он установлен, каждая входящая функция вебхука должна поддерживать соответствующий токен в заголовке своего объекта. Несовпадающие токены отклоняются с HTTP 401.

Оба параметра FEISHU_ENCRYPT_KEY и FEISHU_VERIFICATION_TOKEN могут использоваться вместе для многоуровневой защиты.

Политика групповых сообщений

Переменная управляющая тема FEISHU_GROUP_POLICY, отвечает ли Hermes в групповых чатах и как:

FEISHU_GROUP_POLICY=allowlist   # по умолчанию
Значение Поведение
открытый Hermes отвечает на @упоминания от любого пользователя в любой группе.
белый список Hermes отвечает только за @упоминания пользователей, признанные в FEISHU_ALLOWED_USERS.
инвалид Гермес полностью игнорирует все групповые сообщения.

Во всех режимах бот должен быть явно упомянут @ (или @all) в группе, прежде чем сообщение будет обработано. Личные сообщения всегда обходят этот шлюз.

Установите FEISHU_REQUIRE_MENTION=false, чтобы позволить Hermes читать весь групповой трафик без необходимости @упоминаний:

FEISHU_REQUIRE_MENTION=false

Для початового контроля установите require_mention в записи group_rules — см. раздел Почтовый контроль доступа ниже.

Идентификация бота

Гермес автоматически определяет open_id и отображаемое имя бота при запуске. Вам необходимо хранить их вручную, только если авторизация не может связаться с API Feishu, или если ваше приложение использует идентификаторы пользователей с видимостью действия клиента:

FEISHU_BOT_OPEN_ID=ou_xxx     # только если автоопределение не удаётся
FEISHU_BOT_USER_ID=xxx        # требуется, если ваше приложение использует sender_id_type=user_id
FEISHU_BOT_NAME=MyBot         # только если автоопределение не удаётся

Обмен сообщениями между ботами

По умолчанию Гермес игнорирует сообщения, отправленные другими ботами. Включите обмен сообщениями между ботами, если хотите, чтобы Hermes участвовал в оркестровке A2A или получал уведомления от других ботов в той же группе.

FEISHU_ALLOW_BOTS=mentions   # по умолчанию: none
Значение Поведение
none Игнорировать все сообщения от других ботов (по умолчанию).
mentions Принимать только когда другой бот @упоминает Hermes.
all Принимать каждое сообщение от другого бота.

Также настраивается как feishu.allow_bots в config.yaml (переменная окружения имеет приоритет, если установлены оба).

Другие боты не должны быть добавлены в FEISHU_ALLOWED_USERS — этот белый список применяется только к отправителям-людям.

Предоставьте область application:bot.basic_info:read, чтобы отображать имена других ботов; без неё другие боты всё равно будут маршрутизироваться корректно, но будут отображаться как их open_id.

Интерактивные действия с карточками

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

Подсказки об обновлении, управляемые шлюзом, используют нативную карточку Feishu Да / Нет вместо отката к простым текстовым ответам. Когда hermes update --gateway требует подтверждения, адаптер записывает выбранный ответ в файл .update_response Hermes и заменяет карточку встроенным разрешённым состоянием.

События действий с карточками отправляются с MessageType.COMMAND, поэтому они проходят через обычный конвейер обработки команд.

Это также то, как работает одобрение команд — когда агенту нужно выполнить опасную команду, он отправляет интерактивную карточку с кнопками Разрешить один раз / Сессия / Всегда / Отклонить. Пользователь нажимает кнопку, и обратный вызов действия карточки доставляет решение об одобрении обратно агенту.

Требуемая конфигурация приложения Feishu

Интерактивные карточки требуют трёх шагов настройки в консоли разработчика Feishu. Отсутствие любого из них вызывает ошибку 200340, когда пользователи нажимают кнопки на карточках.

  1. Подпишитесь на событие действия с карточкой: В разделе Подписки на события добавьте card.action.trigger в подписанные события.

  2. Включите возможность интерактивных карточек: В разделе Возможности приложения > Бот убедитесь, что переключатель Интерактивная карточка включён. Это сообщает Feishu, что ваше приложение может получать обратные вызовы действий с карточками.

  3. Настройте URL запроса карточки (только для режима webhook): В разделе Возможности приложения > Бот > URL запроса карточки сообщения установите URL той же конечной точки, что и ваш вебхук событий (например, https://your-server:8765/feishu/webhook). В режиме WebSocket это обрабатывается автоматически SDK.

    ⚠️ Warning

    Без всех трёх шагов Feishu успешно отправит интерактивные карточки (для отправки требуется только разрешение im:message:send), но нажатие любой кнопки вернёт ошибку 200340. Карточка кажется работающей — ошибка проявляется только когда пользователь взаимодействует с ней.

Интеллектуальные ответы на комментарии к документам

Помимо чата, адаптер также может отвечать на @упоминания, оставленные на документах Feishu/Lark. Когда пользователь комментирует документ (выделение локального текста или комментарий ко всему документу) и @упоминает бота, Hermes читает документ плюс окружающую ветку комментариев и публикует ответ LLM встроенно в ветку.

Работает на основе события drive.notice.comment_add_v1, обработчик:

3-уровневый контроль доступа

Ответы на комментарии к документам предоставляются только по явному разрешению — нет неявного режима «разрешить всем». Разрешения разрешаются в следующем порядке (первое совпадение выигрывает, по полю):

  1. Точный документ — правило, ограниченное конкретным токеном документа.
  2. Wildcard — правило, соответствующее шаблону документов.
  3. Верхний уровень — правило по умолчанию для рабочего пространства.

Доступны две политики на правило:

Правила находятся в ~/.hermes/feishu_comment_rules.json (разрешения pairing в ~/.hermes/feishu_comment_pairing.json) с горячей перезагрузкой по mtime — изменения вступают в силу при следующем событии комментария без перезапуска шлюза.

CLI:

# Просмотр текущих правил и состояния pairing
python -m gateway.platforms.feishu_comment_rules status

# Симуляция проверки доступа для конкретного документа + пользователя
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>

# Управление разрешениями pairing во время выполнения
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add <user_open_id>
python -m gateway.platforms.feishu_comment_rules pairing remove <user_open_id>

Требуемая конфигурация приложения Feishu

В дополнение к уже предоставленным разрешениям чата/карточек, добавьте событие комментария к диску:

Поддержка медиа

Входящие (получение)

Адаптер получает и кэширует следующие типы медиа от пользователей:

Тип Расширения Как обрабатывается
Изображения .jpg,.jpeg,.png,.gif,.webp,.bmp Загружаются через API Feishu и кэшируются локально
Аудио .ogg,.mp3,.wav,.m4a,.aac,.flac,.opus,.webm Загружаются и кэшируются; небольшие текстовые файлы автоматически извлекаются
Видео .mp4,.mov,.avi,.mkv,.webm,.m4v,.3gp Загружаются и кэшируются как документы
Файлы .pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx и другие Загружаются и кэшируются как документы

Медиа из сообщений с форматированным текстом (post), включая встроенные изображения и вложения файлов, также извлекаются и кэшируются.

Для небольших текстовых документов (.txt,.md) содержимое файла автоматически внедряется в текст сообщения, чтобы агент мог прочитать его напрямую без необходимости в инструментах.

Исходящие (отправка)

Метод Что отправляет
send Текстовые или форматированные (post) сообщения (автоопределение на основе содержимого markdown)
send_image / send_image_file Загружает изображение в Feishu, затем отправляет как нативный пузырь изображения (с опциональной подписью)
send_document Загружает файл в API Feishu, затем отправляет как вложение файла
send_voice Загружает аудиофайл как вложение файла Feishu
send_video Загружает видео и отправляет как нативное медиа-сообщение
send_animation GIF-файлы понижаются до вложений файлов (у Feishu нет нативного пузыря для GIF)

Маршрутизация загрузки файлов автоматическая на основе расширения:

Рендеринг Markdown и запасной вариант Post

Когда исходящий текст содержит форматирование markdown (заголовки, жирный шрифт, списки, блоки кода, ссылки и т.д.), адаптер автоматически отправляет его как сообщение Feishu post со встроенным тегом md, а не как обычный текст. Это обеспечивает богатое отображение в клиенте Feishu.

Если API Feishu отклоняет полезную нагрузку post (например, из-за неподдерживаемых конструкций markdown), адаптер автоматически переключается на отправку как обычного текста с удалённым markdown. Этот двухэтапный запасной вариант гарантирует, что сообщения всегда доставляются.

Сообщения с обычным текстом (без обнаруженного markdown) отправляются как простой тип сообщения text.

Реакции статуса обработки

Пока агент работает, бот показывает реакцию Печатает на ваше сообщение. Она очищается, когда приходит ответ, или заменяется на Крестик, если обработка не удалась.

Установите FEISHU_REACTIONS=false, чтобы отключить это.

Защита от всплесков и пакетная обработка

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

Пакетная обработка текста

Когда пользователь отправляет несколько текстовых сообщений подряд, они объединяются в одно событие перед отправкой:

Настройка Переменная окружения По умолчанию
Период тишины HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS 0.6с
Макс. сообщений в пакете HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES 8
Макс. символов в пакете HERMES_FEISHU_TEXT_BATCH_MAX_CHARS 4000

Пакетная обработка медиа

Несколько вложений медиа, отправленных подряд (например, перетаскивание нескольких изображений), объединяются в одно событие:

Настройка Переменная окружения По умолчанию
Период тишины HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS 0.8с

Последовательная обработка в чате

Сообщения в одном чате обрабатываются последовательно (по одному) для поддержания связности диалога. У каждого чата своя блокировка, поэтому сообщения в разных чатах обрабатываются параллельно.

Ограничение скорости (режим Webhook)

В режиме webhook адаптер применяет ограничение скорости по IP для защиты от злоупотреблений:

Запросы, превышающие лимит, получают HTTP 429 (Too Many Requests).

Отслеживание аномалий вебхука

Адаптер отслеживает количество последовательных ошибочных ответов на IP-адрес. После 25 последовательных ошибок с одного IP в течение 6-часового окна записывается предупреждение. Это помогает обнаружить неправильно настроенные клиенты или попытки сканирования.

Дополнительные защиты вебхука: - Лимит размера тела: максимум 1 МБ - Тайм-аут чтения тела: 30 секунд - Принудительный Content-Type: принимается только application/json

Настройка WebSocket

При использовании режима websocket вы можете настроить поведение переподключения и ping:

platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120   # Секунды между попытками переподключения (по умолчанию: 120)
      ws_ping_interval: 30         # Секунды между WebSocket ping (опционально; по умолчанию SDK, если не установлено)
Настройка Ключ конфига По умолчанию Описание
Интервал переподключения ws_reconnect_interval 120с Как долго ждать между попытками переподключения
Интервал пинг ws_ping_interval (по умолчанию SDK) Частота поддерживающих пинг-сообщений WebSocket

Почтовый контроль доступа

Помимо глобальной FEISHU_GROUP_POLICY, вы можете установить подробные правила для каждого группового чата с помощью group_rules в config.yaml:

platforms:
  feishu:
    extra:
      default_group_policy: "open"     # По умолчанию для групп, не указанных в group_rules
      admins:                          # Пользователи, которые могут управлять настройками бота
        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_group_chat_id_2":
          policy: "admin_only"
        "oc_group_chat_id_3":
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"
        "oc_free_chat":
          policy: "open"
          require_mention: false       # переопределяет FEISHU_REQUIRE_MENTION для этого чата
Политика Описание
open Любой в группе может использовать бота
allowlist Только пользователи из allowlist группы могут использовать бота
blacklist Все, кроме пользователей из blacklist группы, могут использовать бота
admin_only Только пользователи из глобального списка admins могут использовать бота в этой группе
disabled Бот игнорирует все сообщения в этой группе

Установите require_mention: false в записи group_rules, чтобы пропустить требование @упоминания для этого конкретного чата. Если не указано, чат наследует глобальное значение FEISHU_REQUIRE_MENTION.

Группы, не перечисленные в group_rules, используют default_group_policy (по умолчанию равно значению FEISHU_GROUP_POLICY).

Дедупликация

Входящие сообщения дедуплицируются с использованием ID сообщений с TTL 24 часа. Состояние дедупликации сохраняется между перезапусками в ~/.hermes/feishu_seen_message_ids.json.

Настройка Переменная окружения По умолчанию
Размер кэша HERMES_FEISHU_DEDUP_CACHE_SIZE 2048 записей

Все переменные окружения

Переменная Обязательная По умолчанию Описание
FEISHU_APP_ID ✅ — Feishu/Lark App ID
FEISHU_APP_SECRET ✅ — Feishu/Lark App Secret
FEISHU_DOMAIN — feishu feishu (Китай) или lark (международная)
FEISHU_CONNECTION_MODE — websocket websocket или webhook
FEISHU_ALLOWED_USERS — (пусто) Список open_id через запятую для белого списка пользователей
FEISHU_ALLOW_BOTS — none Принимать сообщения от других ботов: none, mentions или all
FEISHU_REQUIRE_MENTION — true Должны ли групповые сообщения @упоминать бота
FEISHU_HOME_CHANNEL — — ID чата для вывода cron/уведомлений
FEISHU_ENCRYPT_KEY — (пусто) Ключ шифрования для проверки подписи вебхука
FEISHU_VERIFICATION_TOKEN — (пусто) Токен верификации для аутентификации полезной нагрузки вебхука
FEISHU_GROUP_POLICY — allowlist Политика групповых сообщений: open, allowlist, disabled
FEISHU_BOT_OPEN_ID — (пусто) open_id бота (для обнаружения @упоминаний)
FEISHU_BOT_USER_ID — (пусто) user_id бота (для обнаружения @упоминаний)
FEISHU_BOT_NAME — (пусто) Отображаемое имя бота (для обнаружения @упоминаний)
FEISHU_WEBHOOK_HOST — 127.0.0.1 Адрес привязки вебхук-сервера
FEISHU_WEBHOOK_PORT — 8765 Порт вебхук-сервера
FEISHU_WEBHOOK_PATH — /feishu/webhook Путь конечной точки вебхука
HERMES_FEISHU_DEDUP_CACHE_SIZE — 2048 Максимальное количество отслеживаемых ID дедуплицированных сообщений
HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS — 0.6 Период тишины подавления дребезга текстовых всплесков
HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES — 8 Максимум сообщений, объединяемых в один текстовый пакет
HERMES_FEISHU_TEXT_BATCH_MAX_CHARS — 4000 Максимум символов, объединяемых в один текстовый пакет
HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS — 0.8 Период тишины подавления дребезга медиа-всплесков

Настройки WebSocket и почтового ACL конфигурируются через config.yaml в разделе platforms.feishu.extra (см. Настройка WebSocket и Почтовый контроль доступа выше).

Устранение неполадок

Проблема Исправление
lark-oapi not installed Установите SDK: pip install lark-oapi
websockets not installed; websocket mode unavailable Установите websockets: pip install websockets
aiohttp not installed; webhook mode unavailable Установите aiohttp: pip install aiohttp
FEISHU_APP_ID or FEISHU_APP_SECRET not set Установите обе переменные окружения или настройте через hermes gateway setup
Another local Hermes gateway is already using this Feishu app_id Только один экземпляр Hermes может использовать один app_id одновременно. Сначала остановите другой шлюз.
Бот не отвечает в группах Убедитесь, что бот @упомянут, проверьте FEISHU_GROUP_POLICY и убедитесь, что отправитель есть в FEISHU_ALLOWED_USERS, если политика allowlist
Webhook rejected: invalid verification token Убедитесь, что FEISHU_VERIFICATION_TOKEN соответствует токену в конфигурации подписок на события вашего приложения Feishu
Webhook rejected: invalid signature Убедитесь, что FEISHU_ENCRYPT_KEY соответствует ключу шифрования в конфигурации вашего приложения Feishu
Сообщения Post отображаются как обычный текст API Feishu отклонил полезную нагрузку post; это нормальное поведение запасного варианта. Проверьте логи для деталей.
Изображения/файлы не получены ботом Предоставьте области разрешений im:message и im:resource вашему приложению Feishu
Идентификация бота не определена автоматически Обычно временная проблема сети при обращении к конечной точке информации о боте Feishu. Установите FEISHU_BOT_OPEN_ID и FEISHU_BOT_NAME вручную в качестве обходного пути.
Сообщения от других ботов всё ещё игнорируются после включения FEISHU_ALLOW_BOTS Hermes ещё не может идентифицировать себя — установите FEISHU_BOT_OPEN_ID (и FEISHU_BOT_USER_ID, если ваше приложение использует sender_id_type=user_id).
Другие боты отображаются как ou_xxxxxx вместо имени Предоставьте область application:bot.basic_info:read.
Ошибка 200340 при нажатии кнопок одобрения Включите возможность Интерактивная карточка и настройте URL запроса карточки в консоли разработчика Feishu. См. Требуемая конфигурация приложения Feishu выше.
Webhook rate limit exceeded Более 120 запросов/минуту с одного IP. Обычно это неправильная конфигурация или цикл.

Набор инструментов

Feishu / Lark использует предустановку платформы hermes-feishu, которая включает те же основные инструменты, что и Telegram и другие платформы обмена сообщениями на основе шлюза.