Настройка Feishu / Lark
Hermes Agent работает в Feishu и Lark как полноценный бот. После подключения с агентом можно переписываться в личных сообщениях или групповых чатах, получать результаты cron-задач в домашнем чате, а также отправлять текст, картинки, аудио и файловые вложения через обычный поток шлюза.
Поддерживаются оба режима подключения:
websocket— рекомендуемый; Hermes сам открывает исходящее соединение, и публичная точка для вебхука вам не нужнаwebhook— пригодится, если вы хотите, чтобы Feishu/Lark сами слали события в ваш шлюз по HTTP
Как ведёт себя Hermes
| Контекст | Поведение |
|---|---|
| Личные сообщения | Hermes отвечает на каждое сообщение. |
| Групповые чаты | Бот отвечает только когда его упомянули через @ в чате. |
| Общие групповые чаты | По умолчанию история сессий внутри общего чата изолирована для каждого пользователя. |
Поведение в общем чате задаётся через config.yaml:
group_sessions_per_user: trueСтавьте false только если вам действительно нужен один общий разговор на весь чат.
Шаг 1. Создание приложения Feishu / Lark
Рекомендуемый способ: создание по QR-коду (одна команда)
hermes gateway setupВыберите Feishu / Lark и отсканируйте QR-код мобильным приложением Feishu или Lark. Hermes сам создаст приложение-бота с нужными правами и сохранит учётные данные.
Альтернатива: ручная настройка
Если создание по QR-коду недоступно, мастер предложит ручной ввод:
- Откройте консоль разработчика Feishu или Lark:
- Feishu: https://open.feishu.cn/
- Lark: https://open.larksuite.com/
- Создайте новое приложение.
- В разделе Credentials & Basic Info скопируйте App ID и App Secret.
- Включите для приложения возможность Bot.
- Запустите
hermes gateway setup, выберите Feishu / Lark и введите учётные данные, когда мастер их запросит.
Держите App Secret в секрете. Любой, у кого он есть, сможет выдать себя за ваше приложение.
Настройка прав доступа
В консоли разработчика Feishu откройте Permission Management и добавьте перечисленные ниже области (scopes). На странице прав их можно импортировать пакетом.
Обязательные права:
| Scope | Назначение |
|---|---|
im:message | Получать и читать сообщения |
im:message:send_as_bot | Отправлять сообщения от имени бота |
im:resource | Доступ к картинкам, файлам и аудио, отправленным пользователями |
im:chat | Доступ к метаданным чата/группы |
im:chat:readonly | Чтение списка чатов и состава участников |
Рекомендуемые права (для полной функциональности):
| Scope | Назначение |
|---|---|
im:message.reactions:readonly | Получать события эмодзи-реакций |
admin:app.info:readonly | Автоопределение личности бота для фильтрации по @-упоминаниям |
contact:user.id:readonly | Сопоставление ID пользователей со списком разрешений |
Настройка событий
В разделе Events and Callbacks:
- Задайте режим подключения Long Connection (WebSocket) (рекомендуется) либо укажите URL вебхука
- В секции Event Configuration подпишитесь на:
im.message.receive_v1— обязательно для приёма сообщений
Публикация приложения
После настройки прав и событий перейдите в Version Management и опубликуйте новую версию приложения. Права не вступят в силу, пока версия не опубликована и не одобрена (для корпоративных приложений может потребоваться одобрение администратора).
Шаг 2. Выбор режима подключения
Рекомендуемый: режим WebSocket
Берите режим WebSocket, когда Hermes запущен на вашем ноутбуке, рабочей станции или приватном сервере. Публичный URL не нужен. Официальный SDK Lark открывает и держит постоянное исходящее WebSocket-соединение с автоматическим переподключением.
FEISHU_CONNECTION_MODE=websocketТребования: должен быть установлен Python-пакет websockets. SDK сам управляет жизненным циклом соединения, heartbeat-ами и автопереподключением.
Как это работает: адаптер запускает WebSocket-клиент Lark SDK в фоновом потоке-исполнителе. Входящие события (сообщения, реакции, действия с карточками) передаются в основной цикл asyncio. При обрыве связи SDK попытается переподключиться сам.
Опционально: режим webhook
Режим webhook стоит использовать только если у вас уже есть достижимая HTTP-точка, за которой работает Hermes.
FEISHU_CONNECTION_MODE=webhookВ режиме webhook Hermes поднимает HTTP-сервер (через aiohttp) и отдаёт точку Feishu по адресу:
/feishu/webhookТребования: должен быть установлен Python-пакет aiohttp.
Адрес привязки и путь сервера вебхуков настраиваются:
FEISHU_WEBHOOK_HOST=127.0.0.1 # default: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765 # default: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook # default: /feishu/webhookКогда Feishu присылает проверочный запрос подтверждения URL (type: url_verification), вебхук отвечает на него автоматически — так вы сможете завершить настройку подписки в консоли разработчика Feishu. Ответ на challenge защищён значением FEISHU_VERIFICATION_TOKEN, если оно задано: запросы с отсутствующим или несовпадающим токеном отклоняются, чтобы неаутентифицированная сторона не смогла «доказать» контроль над точкой, просто отразив подсунутые ею же данные challenge.
Шаг 3. Настройка Hermes
Вариант A. Интерактивная настройка
hermes gateway setupВыберите Feishu / Lark и заполните поля в диалоге.
Вариант B. Ручная конфигурация
Добавьте в ~/.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_xxxFEISHU_DOMAIN принимает значения:
feishu— для Feishu Chinalark— для Lark international
Шаг 4. Запуск шлюза
hermes gatewayПосле этого напишите боту из Feishu/Lark, чтобы убедиться, что связь установлена.
Домашний чат
Команда /set-home в чате Feishu/Lark помечает его как домашний канал для результатов cron-задач и межплатформенных уведомлений.
Можно настроить это и заранее:
FEISHU_HOME_CHANNEL=oc_xxxБезопасность
Список разрешённых пользователей
Для продакшена задайте список разрешений по Feishu Open ID:
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyyОставите список пустым — и боту сможет писать любой, кто до него дотянется. В групповых чатах перед обработкой сообщения проверяется open_id отправителя по этому списку.
Ключ шифрования вебхука
В режиме webhook задайте ключ шифрования, чтобы включить проверку подписи входящих вебхук-нагрузок:
FEISHU_ENCRYPT_KEY=your-encrypt-keyЭтот ключ находится в разделе Event Subscriptions конфигурации вашего приложения Feishu. Когда он задан, адаптер проверяет каждый вебхук-запрос по алгоритму подписи:
SHA256(timestamp + nonce + encrypt_key + body)Вычисленный хеш сравнивается со значением заголовка x-lark-signature через сравнение, устойчивое к атакам по времени. Запросы с неверной или отсутствующей подписью отклоняются с кодом HTTP 401.
В режиме WebSocket проверку подписи берёт на себя сам SDK, так что FEISHU_ENCRYPT_KEY необязателен. В режиме webhook для продакшена он крайне желателен.
Токен верификации
Дополнительный слой аутентификации — проверка поля token внутри вебхук-нагрузок:
FEISHU_VERIFICATION_TOKEN=your-verification-tokenЭтот токен тоже лежит в разделе Event Subscriptions вашего приложения Feishu. Когда он задан, каждая входящая вебхук-нагрузка обязана содержать совпадающий token в объекте header. Несовпавшие токены отклоняются с кодом HTTP 401.
FEISHU_ENCRYPT_KEY и FEISHU_VERIFICATION_TOKEN можно применять вместе — для эшелонированной защиты.
Политика групповых сообщений
Переменная окружения FEISHU_GROUP_POLICY определяет, отвечает ли Hermes в групповых чатах и как именно:
FEISHU_GROUP_POLICY=allowlist # default| Значение | Поведение |
|---|---|
open | Hermes отвечает на @-упоминания от любого пользователя в любой группе. |
allowlist | Hermes отвечает на @-упоминания только от пользователей из FEISHU_ALLOWED_USERS. |
disabled | Hermes полностью игнорирует все групповые сообщения. |
Во всех режимах перед обработкой бота нужно явно упомянуть в группе через @ (или @all). Личные сообщения этот фильтр обходят всегда.
Установите FEISHU_REQUIRE_MENTION=false, чтобы Hermes читал весь трафик группы без обязательного @-упоминания:
FEISHU_REQUIRE_MENTION=falseДля управления на уровне отдельного чата задайте require_mention в записи group_rules — см. раздел Управление доступом по группам ниже.
Личность бота
Hermes при запуске сам определяет open_id бота и его отображаемое имя. Задавать эти значения вручную нужно лишь тогда, когда автоопределение не может достучаться до API Feishu, либо когда ваше приложение использует ID пользователей в рамках арендатора (tenant-scoped):
FEISHU_BOT_OPEN_ID=ou_xxx # only when auto-detection fails
FEISHU_BOT_USER_ID=xxx # required if your app uses sender_id_type=user_id
FEISHU_BOT_NAME=MyBot # only when auto-detection failsОбмен сообщениями между ботами
По умолчанию Hermes игнорирует сообщения от других ботов. Включите обмен между ботами, если хотите, чтобы Hermes участвовал в A2A-оркестрации или получал уведомления от других ботов в той же группе.
FEISHU_ALLOW_BOTS=mentions # default: none| Значение | Поведение |
|---|---|
none | Игнорировать все сообщения от других ботов (по умолчанию). |
mentions | Принимать только когда сторонний бот упоминает Hermes через @. |
all | Принимать любое сообщение стороннего бота. |
То же настраивается через feishu.allow_bots в config.yaml (при одновременной установке приоритет у переменной окружения).
Сторонних ботов не нужно добавлять в FEISHU_ALLOWED_USERS — этот список разрешений касается только живых отправителей.
Выдайте scope application:bot.basic_info:read, чтобы отображались имена сторонних ботов; без него они всё равно маршрутизируются корректно, но показываются как open_id.
Действия с интерактивными карточками
Когда пользователь нажимает кнопки или взаимодействует с интерактивными карточками от бота, адаптер маршрутизирует это как синтетические командные события /card:
- Нажатие кнопки превращается в:
/card button {"key": "value", ...} - Полезная нагрузка
valueиз определения карточки передаётся в виде JSON. - Действия с карточками дедуплицируются в окне 15 минут, чтобы избежать двойной обработки.
Запросы на подтверждение обновления, инициированные шлюзом, используют родную карточку Feishu Yes / No вместо отката к обычным текстовым ответам. Когда hermes update --gateway требует подтверждения, адаптер записывает выбранный ответ в файл Hermes .update_response и заменяет карточку на месте, отображая итоговое состояние.
События действий с карточками отправляются с типом MessageType.COMMAND, поэтому проходят через обычный конвейер обработки команд.
Так же устроено и подтверждение команд — когда агенту нужно выполнить опасную команду, он отправляет интерактивную карточку с кнопками Allow Once / Session / Always / Deny. Пользователь нажимает кнопку, и колбэк действия карточки доставляет решение об одобрении обратно агенту.
Необходимая настройка приложения Feishu
Интерактивные карточки требуют трёх шагов настройки в консоли разработчика Feishu. Пропуск любого из них вызывает ошибку 200340 при нажатии пользователем на кнопки карточки.
-
Подпишитесь на событие действия карточки: В Event Subscriptions добавьте
card.action.triggerв список подписанных событий. -
Включите возможность Interactive Card: В App Features > Bot убедитесь, что переключатель Interactive Card включён. Так Feishu узнаёт, что ваше приложение умеет принимать колбэки действий с карточками.
-
Задайте Card Request URL (только режим webhook): В App Features > Bot > Message Card Request URL укажите тот же адрес, что и у вебхука событий (например,
https://your-server:8765/feishu/webhook). В режиме WebSocket это делает SDK автоматически.
Без всех трёх шагов Feishu успешно отправит интерактивные карточки (для отправки нужно лишь право im:message:send), но нажатие любой кнопки вернёт ошибку 200340. Карточка выглядит рабочей — ошибка всплывает только когда пользователь с ней взаимодействует.
Умный ответ на комментарии к документам
Помимо чата адаптер умеет отвечать на @-упоминания, оставленные в документах Feishu/Lark. Когда пользователь комментирует документ (выделение фрагмента текста или комментарий ко всему документу) и упоминает бота через @, Hermes читает документ вместе с окружающей веткой комментариев и публикует LLM-ответ прямо в ветке.
Работая на событии drive.notice.comment_add_v1, обработчик:
- Параллельно подтягивает содержимое документа и таймлайн комментариев (20 сообщений для веток по всему документу, 12 — для веток по локальному выделению).
- Запускает агента с наборами инструментов
feishu_doc+feishu_drive, ограниченными этой конкретной сессией комментария. - Разбивает ответы по 4000 символов и публикует их обратно как ответы в ветке.
- Кеширует посессионные данные по каждому документу на 1 час с лимитом 50 сообщений, чтобы новые комментарии к тому же документу сохраняли контекст.
Трёхуровневое управление доступом
Ответы на комментарии к документам работают только по явному разрешению — режима «разрешить всем» по умолчанию нет. Права разрешаются в таком порядке (для каждого поля побеждает первое совпадение):
- Конкретный документ — правило, привязанное к токену конкретного документа.
- Шаблон — правило, совпадающее с паттерном документов.
- Верхний уровень — правило по умолчанию для рабочего пространства.
Для каждого правила доступны две политики:
allowlist— статический список пользователей / арендаторов.pairing— статический список ∪ хранилище разрешений, выданных в рантайме. Удобно для постепенного раскатывания, когда модераторы выдают доступ на лету.
Правила лежат в ~/.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
Поверх уже выданных прав на чат/карточки добавьте событие комментариев Drive:
- Подпишитесь на
drive.notice.comment_add_v1в Event Subscriptions. - Выдайте scopes
docs:doc:readonlyиdrive:drive:readonly, чтобы обработчик мог читать содержимое документов.
События приглашения на встречу
Бота Hermes для Feishu/Lark можно пригласить в видеовстречу так же, как приглашают живого участника. Получив событие приглашения на встречу, Hermes может автоматически начать ход агента и попытаться к встрече присоединиться.
Работая на событии vc.bot.meeting_invited_v1, поток выглядит так:
- Пользователь приглашает бота в видеовстречу Feishu/Lark.
- Feishu/Lark присылает Hermes событие приглашения на встречу.
- Hermes извлекает пригласившего, тему встречи и её номер.
- Если пригласивший разрешён обычным списком шлюза или политикой pairing, агент получает номер встречи и пытается присоединиться автоматически.
- Если приглашение некорректно или агент не может присоединиться, Hermes отбрасывает событие либо коротко поясняет это в ответе пригласившему.
Некорректные приглашения, в которых нет одновременно пригласившего и meeting_no, игнорируются.
Необходимая настройка приложения Feishu
Поверх уже выданных прав на чат/карточки добавьте событие приглашения на видеовстречу:
- Подпишитесь на
vc.bot.meeting_invited_v1в Event Subscriptions. - Включите scope прав на видеоконференции, который консоль разработчика Feishu/Lark запросит для этого события.
- Оставьте включёнными
im:messageиim:message:send_as_bot, чтобы Hermes мог ответить пригласившему. - Убедитесь, что список разрешений шлюза или политика pairing допускает пригласившего. Приглашения на встречи не обходят обычные проверки доступа шлюза.
Поддержка медиа
Входящие (приём)
Адаптер принимает и кеширует следующие типы медиа от пользователей:
| Тип | Расширения | Как обрабатывается |
|---|---|---|
| Картинки | .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 и другие | Скачиваются и кешируются как документы |
Медиа из rich-text-сообщений (post), включая встроенные картинки и файловые вложения, тоже извлекается и кешируется.
Для небольших текстовых документов (.txt, .md) содержимое файла автоматически подставляется в текст сообщения, так что агент читает его напрямую, без обращения к инструментам.
Исходящие (отправка)
| Метод | Что отправляет |
|---|---|
send | Текст или rich-сообщения post (определяется автоматически по markdown-содержимому) |
send_image / send_image_file | Загружает картинку в Feishu и отправляет как родной пузырь-изображение (с необязательной подписью) |
send_document | Загружает файл через API Feishu и отправляет как файловое вложение |
send_voice | Загружает аудиофайл как файловое вложение Feishu |
send_video | Загружает видео и отправляет как родное медиа-сообщение |
send_animation | GIF понижаются до файловых вложений (родного GIF-пузыря у Feishu нет) |
Маршрутизация загрузки файла выбирается автоматически по расширению:
.ogg,.opus→ загружаются как аудиоopus.mp4,.mov,.avi,.m4v→ загружаются как медиаmp4.pdf,.doc(x),.xls(x),.ppt(x)→ загружаются с соответствующим типом документа- всё остальное → загружается как обычный потоковый файл
Рендеринг markdown и откат к post
Когда исходящий текст содержит markdown-форматирование (заголовки, жирный шрифт, списки, блоки кода, ссылки и т. д.), адаптер автоматически отправляет его как сообщение Feishu post со встроенным тегом md, а не как обычный текст. Так в клиенте Feishu получается богатое оформление.
Если API Feishu отклоняет нагрузку post (например, из-за неподдерживаемых конструкций markdown), адаптер автоматически откатывается к отправке простым текстом с вырезанной разметкой. Двухступенчатый откат гарантирует, что сообщение всё равно доставится.
Сообщения без markdown (разметка не обнаружена) отправляются простым типом text.
Реакции о статусе обработки
Пока агент работает, бот ставит на ваше сообщение реакцию Typing. Она снимается, когда приходит ответ, либо меняется на CrossMark, если обработка завершилась ошибкой.
Установите 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 для защиты от злоупотреблений:
- Окно: скользящее окно в 60 секунд
- Лимит: 120 запросов за окно на тройку (app_id, path, IP)
- Предел отслеживания: одновременно отслеживается до 4096 уникальных ключей (не даёт памяти расти бесконтрольно)
Запросы сверх лимита получают HTTP 429 (Too Many Requests).
Отслеживание аномалий вебхука
Адаптер считает подряд идущие ошибочные ответы по каждому IP-адресу. После 25 подряд идущих ошибок с одного IP в окне 6 часов в лог пишется предупреждение. Это помогает заметить неправильно настроенных клиентов или попытки сканирования.
Дополнительные защиты вебхука:
- Лимит размера тела: максимум 1 МБ
- Таймаут чтения тела: 30 секунд
- Контроль Content-Type: принимается только
application/json
Тонкая настройка WebSocket
В режиме websocket можно подстроить поведение переподключения и пинга:
platforms:
feishu:
extra:
ws_reconnect_interval: 120 # Seconds between reconnect attempts (default: 120)
ws_ping_interval: 30 # Seconds between WebSocket pings (optional; SDK default if unset)| Параметр | Ключ конфигурации | По умолчанию | Описание |
|---|---|---|---|
| Интервал переподключения | ws_reconnect_interval | 120 с | Сколько ждать между попытками переподключения |
| Интервал пинга | ws_ping_interval | (значение SDK по умолчанию) | Частота keepalive-пингов WebSocket |
Управление доступом по группам
Помимо глобального FEISHU_GROUP_POLICY, можно задать точные правила по каждому групповому чату через group_rules в config.yaml:
platforms:
feishu:
extra:
default_group_policy: "open" # Default for groups not in group_rules
admins: # Users who can manage bot settings
- "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 # overrides FEISHU_REQUIRE_MENTION for this chat| Политика | Описание |
|---|---|
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).
Дедупликация
Входящие сообщения дедуплицируются по идентификаторам сообщений с TTL в 24 часа. Состояние дедупликации сохраняется между перезапусками в ~/.hermes/feishu_seen_message_ids.json.
| Параметр | Переменная окружения | По умолчанию |
|---|---|---|
| Размер кеша | HERMES_FEISHU_DEDUP_CACHE_SIZE | 2048 записей |
Все переменные окружения
| Переменная | Обязательна | По умолчанию | Описание |
|---|---|---|---|
FEISHU_APP_ID | ✅ | — | App ID Feishu/Lark |
FEISHU_APP_SECRET | ✅ | — | App Secret Feishu/Lark |
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 | Один app_id может использовать только один экземпляр Hermes за раз. Сначала остановите другой шлюз. |
| Бот не отвечает в группах | Убедитесь, что бота упомянули через @, проверьте FEISHU_GROUP_POLICY и, если политика allowlist, проверьте, что отправитель есть в FEISHU_ALLOWED_USERS |
Webhook rejected: invalid verification token | Убедитесь, что FEISHU_VERIFICATION_TOKEN совпадает с токеном в настройках Event Subscriptions вашего приложения Feishu |
Webhook rejected: invalid signature | Убедитесь, что FEISHU_ENCRYPT_KEY совпадает с ключом шифрования в конфигурации вашего приложения Feishu |
| Сообщения post отображаются как обычный текст | API Feishu отклонил нагрузку post; это нормальное поведение отката. Подробности смотрите в логах. |
| Бот не получает картинки/файлы | Выдайте приложению Feishu права im:message и im:resource |
| Личность бота не определилась автоматически | Обычно это временная сетевая проблема с доступом к точке информации о боте в 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, а не по имени | Выдайте scope application:bot.basic_info:read. |
| Ошибка 200340 при нажатии кнопок подтверждения | Включите возможность Interactive Card и настройте Card Request URL в консоли разработчика Feishu. См. Необходимая настройка приложения Feishu выше. |
Webhook rate limit exceeded | Более 120 запросов в минуту с одного IP. Обычно это ошибка конфигурации или зацикливание. |
Набор инструментов
Feishu / Lark использует пресет платформы hermes-feishu, куда входят те же базовые инструменты, что и у Telegram и других платформ обмена сообщениями на базе шлюза.