Бот Feishu

Feishu (Lark) — платформа командного общения для обмена сообщениями и совместной работы. Этот плагин подключает OpenClaw к боту Feishu/Lark через WebSocket-подписку на события, позволяя получать сообщения без публичного webhook-URL.

Встроенный плагин

Feishu поставляется в комплекте с текущими выпусками OpenClaw, отдельная установка плагина не требуется.

Если вы используете более старую сборку или пользовательскую установку без встроенного Feishu, установите вручную:

openclaw plugins install @openclaw/feishu

Быстрый старт

Канал Feishu можно добавить двумя способами:

Способ 1: мастер настройки (рекомендуется)

Если вы только установили OpenClaw, запустите мастер:

openclaw onboard

Мастер проведёт вас через:

1. Создание приложения Feishu и получение учётных данных
2. Настройку учётных данных приложения в OpenClaw
3. Запуск шлюза

После настройки проверьте статус шлюза:

• openclaw gateway status
• openclaw logs --follow

Способ 2: настройка через CLI

Если начальная установка уже выполнена, добавьте канал через CLI:

openclaw channels add

Выберите Feishu, затем введите App ID и App Secret.

После настройки управляйте шлюзом:

• openclaw gateway status
• openclaw gateway restart
• openclaw logs --follow

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

1. Откройте Feishu Open Platform

Перейдите на Feishu Open Platform и войдите.

Для тенантов Lark (глобальная версия) используйте https://open.larksuite.com/app и задайте domain: "lark" в конфигурации Feishu.

2. Создайте приложение

1. Нажмите Create enterprise app
2. Заполните название и описание приложения
3. Выберите иконку приложения

3. Скопируйте учётные данные

В разделе Credentials & Basic Info скопируйте:

• App ID (формат: cli_xxx)
• App Secret

Предупреждение: Храните App Secret в тайне.

4. Настройте разрешения

В разделе Permissions нажмите Batch import и вставьте:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

5. Включите возможность бота

В App Capability > Bot:

1. Включите возможность бота
2. Задайте имя бота

6. Настройте подписку на события

Предупреждение: Перед настройкой подписки на события убедитесь:

1. Вы уже выполнили openclaw channels add для Feishu
2. Шлюз запущен (openclaw gateway status)

В Event Subscription:

1. Выберите Use long connection to receive events (WebSocket)
2. Добавьте событие: im.message.receive_v1

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

7. Опубликуйте приложение

1. Создайте версию в Version Management & Release
2. Отправьте на проверку и опубликуйте
3. Дождитесь одобрения администратора (корпоративные приложения обычно одобряются автоматически)

Шаг 2: Настройте OpenClaw

Настройка через мастер (рекомендуется)

openclaw channels add

Выберите Feishu и вставьте App ID + App Secret.

Настройка через файл конфигурации

Отредактируйте ~/.openclaw/openclaw.json:

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "My AI assistant",
        },
      },
    },
  },
}

При использовании connectionMode: "webhook" задайте verificationToken и encryptKey. Webhook-сервер Feishu привязывается к 127.0.0.1 по умолчанию; задайте webhookHost, только если вам намеренно нужен другой адрес привязки.

Verification Token и Encrypt Key (режим webhook)

При использовании режима webhook задайте channels.feishu.verificationToken и channels.feishu.encryptKey в конфигурации. Для получения значений:

1. В Feishu Open Platform откройте ваше приложение
2. Перейдите в Development > Events & Callbacks
3. Откройте вкладку Encryption
4. Скопируйте Verification Token и Encrypt Key

На скриншоте ниже показано расположение Verification Token. Encrypt Key указан в том же разделе Encryption.

Настройка через переменные окружения

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Домен Lark (глобальная версия)

Если ваш тенант на Lark (международная версия), задайте домен lark (или полную строку домена). Можно задать на уровне channels.feishu.domain или для конкретного аккаунта (channels.feishu.accounts.<id>.domain).

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

Флаги оптимизации квоты

Два опциональных флага для снижения использования API Feishu:

• typingIndicator (по умолчанию true): при false пропускаются вызовы реакции набора текста.
• resolveSenderNames (по умолчанию true): при false пропускаются вызовы получения профиля отправителя.

Задайте на верхнем уровне или для конкретного аккаунта:

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

Шаг 3: Запуск + тестирование

1. Запустите шлюз

openclaw gateway

2. Отправьте тестовое сообщение

В Feishu найдите вашего бота и отправьте сообщение.

3. Подтвердите спаривание

По умолчанию бот ответит кодом спаривания. Подтвердите его:

openclaw pairing approve feishu <CODE>

После подтверждения можно общаться в обычном режиме.

Обзор

• Канал бота Feishu: бот Feishu, управляемый шлюзом
• Детерминированная маршрутизация: ответы всегда возвращаются в Feishu
• Изоляция сессий: ЛС разделяют основную сессию; группы изолированы
• WebSocket-соединение: длинное соединение через Feishu SDK, публичный URL не требуется

Контроль доступа

Прямые сообщения

• По умолчанию: dmPolicy: "pairing" (неизвестные пользователи получают код спаривания)

• Подтверждение спаривания:

  openclaw pairing list feishu
  openclaw pairing approve feishu <CODE>

• Режим списка доступа: задайте channels.feishu.allowFrom с разрешёнными Open ID

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

1. Групповая политика (channels.feishu.groupPolicy):

• "open" = разрешить всех в группах (по умолчанию)
• "allowlist" = разрешить только из groupAllowFrom
• "disabled" = отключить групповые сообщения

2. Требование упоминания (channels.feishu.groups.<chat_id>.requireMention):

• true = требовать @mention (по умолчанию)
• false = отвечать без упоминаний

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

Разрешить все группы, требовать @mention (по умолчанию)

{
  channels: {
    feishu: {
      groupPolicy: "open",
      // requireMention по умолчанию: true
    },
  },
}

Разрешить все группы, без требования @mention

{
  channels: {
    feishu: {
      groups: {
        oc_xxx: { requireMention: false },
      },
    },
  },
}

Разрешить только определённые группы

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // ID групп Feishu (chat_id) выглядят как: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Ограничить отправителей в группе (список доступа отправителей)

Помимо разрешения самой группы, все сообщения в этой группе фильтруются по open_id отправителя: обрабатываются только сообщения пользователей из groups.<chat_id>.allowFrom; сообщения остальных участников игнорируются (это полный гейтинг на уровне отправителя, не только для управляющих команд вроде /reset или /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // ID пользователей Feishu (open_id) выглядят как: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Получение ID групп/пользователей

ID групп (chat_id)

ID групп выглядят как oc_xxx.

Способ 1 (рекомендуется)

1. Запустите шлюз и @упомяните бота в группе
2. Выполните openclaw logs --follow и найдите chat_id

Способ 2

Используйте отладчик API Feishu для списка групповых чатов.

ID пользователей (open_id)

ID пользователей выглядят как ou_xxx.

Способ 1 (рекомендуется)

1. Запустите шлюз и напишите боту в ЛС
2. Выполните openclaw logs --follow и найдите open_id

Способ 2

Проверьте запросы спаривания для получения Open ID пользователей:

openclaw pairing list feishu

Основные команды

Примечание: Feishu пока не поддерживает нативное меню команд, поэтому команды нужно отправлять текстом.

Команды управления шлюзом

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

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

1. Убедитесь, что бот добавлен в группу
2. Убедитесь, что вы @упоминаете бота (поведение по умолчанию)
3. Проверьте, что groupPolicy не задан как "disabled"
4. Проверьте логи: openclaw logs --follow

Бот не получает сообщения

1. Убедитесь, что приложение опубликовано и одобрено
2. Убедитесь, что подписка на события включает im.message.receive_v1
3. Убедитесь, что длинное соединение включено
4. Убедитесь, что разрешения приложения полные
5. Убедитесь, что шлюз запущен: openclaw gateway status
6. Проверьте логи: openclaw logs --follow

Утечка App Secret

1. Сбросьте App Secret в Feishu Open Platform
2. Обновите App Secret в конфигурации
3. Перезапустите шлюз

Ошибки отправки сообщений

1. Убедитесь, что у приложения есть разрешение im:message:send_as_bot
2. Убедитесь, что приложение опубликовано
3. Проверьте логи для детальной информации об ошибках

Расширенная конфигурация

Несколько аккаунтов

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          botName: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          botName: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

defaultAccount определяет, какой аккаунт Feishu используется, когда исходящие API не указывают accountId явно.

Ограничения сообщений

• textChunkLimit: размер исходящего текстового чанка (по умолчанию: 2000 символов)
• mediaMaxMb: лимит загрузки/скачивания медиа (по умолчанию: 30 МБ)

Стриминг

Feishu поддерживает потоковые ответы через интерактивные карточки. При включении бот обновляет карточку по мере генерации текста.

{
  channels: {
    feishu: {
      streaming: true, // включить потоковый вывод через карточки (по умолчанию true)
      blockStreaming: true, // включить блочный стриминг (по умолчанию true)
    },
  },
}

Задайте streaming: false, чтобы дождаться полного ответа перед отправкой.

Мульти-агентная маршрутизация

Используйте bindings для маршрутизации ЛС или групп Feishu к разным агентам.

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

Поля маршрутизации:

• match.channel: "feishu"
• match.peer.kind: "direct" или "group"
• match.peer.id: Open ID пользователя (ou_xxx) или ID группы (oc_xxx)

См. Получение ID групп/пользователей для советов по поиску.

Справочник конфигурации

Полная конфигурация: Конфигурация шлюза

Ключевые настройки:

Справочник dmPolicy

Поддерживаемые типы сообщений

Приём

• Текст
• Форматированный текст (post)
• Изображения
• Файлы
• Аудио
• Видео
• Стикеры

Отправка

• Текст
• Изображения
• Файлы
• Аудио
• Форматированный текст (частичная поддержка)