Feishu (Lark)

В этом руководстве описывается настройка канала Qwen Code в Feishu (飞书) / Lark.

Предварительные требования

Учётная запись организации Feishu
Приложение Feishu с App ID и App Secret (см. ниже)

Создание приложения

Перейдите на Feishu Open Platform
Создайте новое приложение (или используйте существующее)

В приложении включите возможность Bot (添加应用能力 → 机器人)

В разделе Event Subscriptions (事件与回调) выберите Long Connection (使用长连接接收事件)

Добавьте событие im.message.receive_v1 (接收消息)

Запишите App ID (Client ID) и App Secret (Client Secret) со страницы учётных данных приложения

Необходимые разрешения

Включите следующие разрешения в разделе Permissions & Scopes (权限管理):

im:message — Чтение и отправка сообщений
im:message:send_as_bot — Отправка сообщений от имени бота
im:resource — Доступ к ресурсам сообщений (изображения, файлы)

Публикация приложения

После настройки разрешений и событий создайте версию и опубликуйте её. Бот не будет работать, пока приложение не будет опубликовано и одобрено.

Конфигурация

Добавьте канал в ~/.qwen/settings.json:


{
  "channels": {
    "my-feishu": {
      "type": "feishu",
      "clientId": "<your-app-id>",
      "clientSecret": "<your-app-secret>",
      "senderPolicy": "open",
      "sessionScope": "user",
      "cwd": "/path/to/your/project",
      "groupPolicy": "open",
      "collapsible": true,
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Параметры конфигурации

Параметр	Описание
`clientId`	App ID приложения Feishu
`clientSecret`	App Secret приложения Feishu
`collapsible`	Сворачивать длинные ответы в раскрывающиеся секции (по умолчанию: `false`)
`collapsibleThreshold`	Порог количества символов для сворачивания (по умолчанию: `500`)
`webhookPort`	Если задан, используется режим HTTP-вебхука вместо WebSocket
`verificationToken`	Токен проверки для режима вебхука
`encryptKey`	Ключ шифрования для режима вебхука

Запуск


# Запустить только канал Feishu
qwen channel start my-feishu
 
# Или запустить все настроенные каналы вместе
qwen channel start

Откройте Feishu и отправьте сообщение боту. Вы увидите интерактивную карточку с потоковым ответом.

Режимы подключения

WebSocket (по умолчанию)

Режим WebSocket использует исходящее длинное соединение — не требуется публичный URL или сервер. Этот режим рекомендуется для большинства развёртываний.

Webhook

Если вам нужен режим вебхука (например, для общих приложений), укажите webhookPort в конфигурации:


{
  "channels": {
    "my-feishu": {
      "type": "feishu",
      "webhookPort": 9321,
      "verificationToken": "<from-feishu-console>",
      "encryptKey": "<from-feishu-console>"
    }
  }
}

Затем укажите URL запроса в Feishu Open Platform как http://<your-server>:9321.

Групповые чаты

Боты Feishu работают как в личных сообщениях, так и в групповых беседах. Чтобы включить поддержку групп:

Установите groupPolicy в "allowlist" или "open" в конфигурации канала
Добавьте бота в группу Feishu
Упомяните бота через @ в группе, чтобы вызвать ответ

По умолчанию бот требует упоминания @ в групповых чатах (requireMention: true). Установите "requireMention": false для конкретной группы, чтобы бот отвечал на все сообщения.

Возможности

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

Ответы отображаются в виде интерактивных карточек Feishu с обновлениями в реальном времени. На карточке отображается индикатор “генерация”, пока формируется ответ, и кнопка Stop для отмены генерации.

Контекст по цитате/ответу

Когда вы отвечаете на (цитируете) сообщение, процитированное содержимое автоматически включается в качестве контекста для агента. Это работает для:

Текстовых и rich-text сообщений
Интерактивных карточек (предыдущие ответы бота)

Изображения и файлы

Вы можете отправлять боту фотографии и документы:

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

Одновременные сообщения

Несколько пользователей могут одновременно отправлять сообщения в одном групповом чате. Каждое сообщение получает собственную независимую карточку и ответ — они не мешают друг другу.

Ключевые отличия от DingTalk

Формат ответа: Использует интерактивные карточки Feishu (схема v2) с нативной поддержкой Markdown, включая таблицы
Потоковый режим: Содержимое карточки обновляется на месте с помощью PATCH-запросов с регулировкой (интервал 1,5 с)
Подключение: WebSocket через @larksuiteoapi/node-sdk — та же исходящая модель, публичный URL не требуется
Индикатор работы: В процессе обработки добавляется реакция «OnIt» в виде эмодзи
Контекст цитаты: Поддерживается цитирование как текстовых сообщений, так и интерактивных карточек

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

Бот не подключается

Убедитесь, что App ID и App Secret указаны правильно
Убедитесь, что в подписках на события выбрано Долгое подключение
Проверьте, что подписано событие im.message.receive_v1
Проверьте вывод терминала на наличие ошибок подключения

Бот не отвечает в группах

Проверьте, что groupPolicy установлен в "allowlist" или "open" (по умолчанию — "disabled")
Убедитесь, что вы упомянули бота в сообщении группы (@mention)
Проверьте, что бот добавлен в группу

Карточка остаётся в состоянии «generating»

Обычно это указывает на то, что ответ завершён, но финальное обновление карточки не удалось
Проверьте логи терминала на ошибки API (ограничение частоты запросов, ограничения размера карточки)
Очень длинные ответы с множеством таблиц могут превышать лимиты элементов карточки Feishu

Цитата не включает содержимое карточки

Бот читает содержимое карточки через параметр API card_msg_content_type=user_card_content
Убедитесь, что у бота есть разрешение im:message на чтение сообщений