🏠 Главная › User Guide › feishu

sidebar_position: 11 title: "Feishu / Lark" description: "Set up Hermes Agent as a Feishu or Lark bot" lang: ru

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

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

Интеграция поддерживает оба режима подключения:

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

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

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

group_sessions_per_user: true

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

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

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

hermes gateway setup

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

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

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

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

:::предупреждение Держите секрет приложения в тайне. Любой, у кого он есть, может выдать себя за ваше приложение.

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

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

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

FEISHU_CONNECTION_MODE=websocket

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

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

Необязательно: режим веб-перехватчика

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

FEISHU_CONNECTION_MODE=webhook

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

/feishu/webhook

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

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

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.

Шаг 3: Настройте Гермес

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

hermes gateway setup

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

Вариант Б: настройка вручную

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

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

# Optional but strongly recommended
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

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

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

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

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

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

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

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

FEISHU_ENCRYPT_KEY=your-encrypt-key

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

SHA256(timestamp + nonce + encrypt_key + body)

Вычисленный хэш сравнивается с заголовком x-lark-signature с использованием безопасного по времени сравнения. Запросы с недействительными или отсутствующими подписями отклоняются с помощью HTTP 401.

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

Токен подтверждения

Дополнительный уровень аутентификации, который проверяет поле token внутри полезных данных веб-перехватчика:

FEISHU_VERIFICATION_TOKEN=your-verification-token

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

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

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

Переменная среды FEISHU_GROUP_POLICY определяет, будет ли Гермес отвечать в групповых чатах и если да, то каким образом:

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

Во всех режимах бот должен быть явно @упомянут (или @all) в группе перед обработкой сообщения. Прямые сообщения всегда обходят эти ворота.

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

FEISHU_REQUIRE_MENTION=false

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

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

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

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 Принимайте только тогда, когда одноранговый бот @упомянет Гермеса.
all Принимайте каждое сообщение однорангового бота.

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

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

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

Действия с интерактивными картами

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

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

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

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

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

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

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

  3. Настройте URL-адрес запроса карты (только в режиме веб-перехватчика): В разделе Функции приложения > Бот > URL-адрес запроса карточки сообщения установите URL-адрес той же конечной точки, что и веб-перехватчик событий (например, https://your-server:8765/feishu/webhook). In WebSocket mode this is handled automatically by the SDK.

⚠️ Warning

Without all three steps, Feishu will successfully *send* interactive cards (sending only requires `im:сообщение:отправить` permission), but clicking any button will return error 200340. The card appears to work — the error only surfaces when a user interacts with it.

Document Comment Intelligent Reply

Beyond chat, the adapter can also answer @-mentions left on Feishu/Lark documents. When a user comments on a document (local text selection or whole-doc comment) and @-mentions the bot, Hermes reads the document plus the surrounding comment thread and posts an LLM reply inline on the thread.

Powered by the drive.notice.comment_add_v1 event, the handler:

3-Tier Access Control

Document-comment replies are explicit-grant only — there is no implicit allow-all mode. Permissions resolve in this order (first match wins, per field):

  1. Exact doc — rule scoped to a specific document token.
  2. Wildcard — rule that matches a pattern of docs.
  3. Top-level — default rule for the workspace.

Two policies are available per rule:

CLI:

# Inspect current rules and pairing state
python -m gateway.platforms.feishu_comment_rules status

# Simulate an access check for a specific doc + user
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>

# Manage pairing grants at runtime
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>

Required Feishu App Configuration

On top of the chat/card permissions already granted, add the drive comment event:

Media Support

Inbound (receiving)

The adapter receives and caches the following media types from users:

Type Extensions How it's processed
Images .jpg, .jpeg, .png, .gif, .webp, .bmp Downloaded via Feishu API and cached locally
Audio .ogg, .mp3, .wav, .m4a, .aac, .flac, .opus, .webm Downloaded and cached; small text files are auto-extracted
Video .mp4, .mov, .avi, .mkv, .webm, .m4v, .3gp Downloaded and cached as documents
Files .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, and more Downloaded and cached as documents

Media from rich-text (post) messages, including inline images and file attachments, is also extracted and cached.

For small text-based documents (.txt, .md), the file content is automatically injected into the message text so the agent can read it directly without needing tools.

Outbound (sending)

Method What it sends
send Text or rich post messages (auto-detected based on markdown content)
send_image / send_image_file Uploads image to Feishu, then sends as native image bubble (with optional caption)
send_document Uploads file to Feishu API, then sends as file attachment
send_voice Uploads audio file as a Feishu file attachment
send_video Uploads video and sends as native media message
send _animation GIFs are downgraded to file attachments (Feishu has no native GIF bubble)

File upload routing is automatic based on extension:

Markdown Rendering and Post Fallback

When outbound text contains markdown formatting (headings, bold, lists, code blocks, links, etc.), the adapter automatically sends it as a Feishu post message with an embedded md tag rather than as plain text. This enables rich rendering in the Feishu client.

If the Feishu API rejects the post payload (e.g., due to unsupported markdown constructs), the adapter automatically falls back to sending as plain text with markdown stripped. This two-stage fallback ensures messages are always delivered.

Plain text messages (no markdown detected) are sent as the simple text message type.

Processing Status Reactions

While the agent is working, the bot shows a Ввод@@IC0077 @@CrossMark if processing failed.

Set FEISHU_REACTIONS=false to turn it off.

Burst Protection and Batching

The adapter includes debouncing for rapid message bursts to avoid overwhelming the agent:

Text Batching

When a user sends multiple text messages in quick succession, they are merged into a single event before being dispatched:

Setting Env Var Default
Quiet period HERMES_FEISHU_TEXT_BATCH_D ELAY_SECONDS 0.6s
Max messages per batch HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES 8
Max characters per batch HERMES_FEISHU_TEXT_BATCH_MAX_CHARS 4000

Media Batching

Multiple media attachments sent in quick succession (e.g., dragging several images) are merged into a single event:

Setting Env Var Default
Quiet period HERMES_FEISHU_MEDIA_BATCH_DELAY_SECONDS@@IC00 83@@application/json is accepted

WebSocket Tuning

When using websocket mode, you can customize reconnect and ping behavior:

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)
Setting Config key Default Description
Reconnect interval ws_reconnect_interval 120s How long to wait between reconnection attempts
Ping interval ws_ping_interval (SDK default) Frequency of WebSocket keepalive pings

Per-Group Access Control

Beyond the global FEISHU_GROUP_POLICY, you can set fine-grained rules per group chat using group_rules in 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
Policy Description
op ru Anyone in the group can use the bot
allowlist Only users in the group's allowlist can use the bot
blacklist Everyone except users in the group's blacklist can use the bot
admin_only Only users in the global admins list can use the bot in this group
disabled Bot ignores all messages in this group

Set require_mention: false on a group_rules entry to skip the @-mention requirement for that specific chat. When omitted, the chat inherits the global FEISHU_REQUIRE_MENTION value.

Groups not listed in group_rules fall back to default_group_policy (defaults to the value of FEISHU_GROUP_POLICY).

Deduplication

Inbound messages are deduplicated using message IDs with a 24-hour TTL. The dedup state is persisted across restarts to ~/.hermes/feishu_seen_me ssage_ids.json.

Setting Env Var Default
Cache size HERMES_FEISHU_DEDUP_CACHE_SIZE 2048 entries

All Environment Variables

Variable Required Default Description
FEISHU_APP_ID@@IC0106@ @FEISHU_APP_SECRET ✅ — Feishu/Lark App Secret
FEISHU_DOMAIN — feishu feishu (China) or lar k (international)
FEISHU_CONNECTION_MODE — websocket websocket or webho ok
FEISHU_ALLOWED_USERS — (empty) Comma-separated open_id list for user allowlist
FEISHU_ALLOW_BOTS — none Accept messages from other bots: non e, mentions, or all
FEISHU_REQUIRE_MENTION — true Whether group messages must @mention the bot
FEISHU_HOME_CHANNEL — — Chat ID for cron/notification output
FEISHU_ENCRYPT_KEY — (empty) Encrypt key for webhook signature verification
FEISHU_VERIFICATION_TOKEN@@ IC0126@@FEISHU_GROUP_POLICY — allowlist Group message policy: open, allowlist, disabled
FEISHU_BOT_OPEN_ID — (empty) Bot's open_id (for @mention detection)
FEISHU_BOT_USER_ID — (empty) Bot's user_id (for @mention detection)
FEISHU_BO T_NAME — (empty) Bot's display name (for @mention detection)
FEISHU_WEBHOOK_HOST — 127.0.0.1 Webhook server bind address
FEISHU_WEBHOOK_PORT@@I C0137@@8765 Webhook server port
FEISHU_WEBHOOK_PATH — /feishu/webhook Webhook endpoint path
HERMES_FEIS HU_DEDUP_CACHE_SIZE — 2048 Max deduplicated message IDs to track
HERMES_FEISHU_TEXT_BATCH_DELAY_SECONDS@@IC0 143@@0.6 Text burst debounce quiet period
HERMES_FEISHU_TEXT_BATCH_MAX_MESSAGES — 8 Max messages merged per text batch
HERMES_FEI SHU_TEXT_BATCH_MAX_CHARS — 4000 Max characters merged per text batch
HERMES_FEISHU_MEDIA_BATCH_DELAY_SECOND S — 0.8 Media burst debounce quiet period

WebSocket and per-group ACL settings are configured via config.yaml under platforms.feishu.extra (see WebSocket Tuning and Per-Group Access Control above).

Troubleshooting

Problem Fix
lark-oapi не установлен Install the SDK: pip install lark-oapi
websockets не установлен; режим websocket недоступен Install websockets: pip install websockets
aiohttp не установлен; режим webhook недоступен Install aiohttp: pip install aiohttp
FEISHU_APP_ID или FEISHU_APP_SECRET не установлен Set both env vars or configure via hermesшлюз setup
Другой локальный шлюз Hermes уже использует этот Feishu app_id Only one Hermes instance can use the same app_id at a time. Stop the other gateway first.
Bot doesn't respond in groups Ensure the bot is @mentioned, check FEISHU_GROUP_POLICY, and verify the sender is in FEISHU_ALLOWED_USERS if policy is allowlist
Webhook отклонен: неверная проверка token Ensure FEISHU_VERIFICATION_TOKEN matches the token in your Feishu app's Event Subscriptions config
Вебхук отклонен: недействителен подпись Ensure FEISHU_ENCRYPT_KEY matches the encrypt key in your Feishu app config
Post messages show as plain text The Feishu API rejected the post payload; this is normal fallback behavior. Check logs for details.
Images/files not received by bot Grant im:message and im:resource permission scopes to your Feishu app
Bot identity not auto-detected Usually a transient network issue reaching Feishu's bot info endpoint. Set FEISHU_BOT_OPEN_ID and FEISHU_BOT_NAME manually as a workaround.
Peer bot messages still ignored after enabling FEISHU_ALLOW_BOTS@@I C0173@@FEISHU_BOT_OPEN_ID (and FEISHU_BOT_USER_ID if your app uses sender_id_type=user_id).
Peer bots show as ou_xxxxxx instead of by name Grant the application:bot.basic_info:read scope.
Error 200340 when clicking approval buttons Enable Interactive Card capability and configure Card Request URL in the Feishu Developer Console. See Required Feishu App Configuration above.
Webhook превышен лимит скорости More than 120 requests/minute from the same IP. This is usually a misconfiguration or loop.

Toolset

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