Feishu

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

Требуемый плагин

Установите плагин Feishu:

openclaw plugins install @openclaw/feishu

Локальная установка (при запуске из git-репозитория):

openclaw plugins install ./extensions/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. Сервер вебхука Feishu по умолчанию привязывается к 127.0.0.1; устанавливайте webhookHost только если вам намеренно нужен другой адрес привязки.

Verification Token (режим вебхука)

При использовании режима вебхука установите channels.feishu.verificationToken в вашей конфигурации. Чтобы получить значение:

1. В Feishu Open Platform откройте ваше приложение
2. Перейдите в Development → Events & Callbacks (开发配置 → 事件与回调)
3. Откройте вкладку Encryption (加密策略)
4. Скопируйте Verification Token

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

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-соединение: длинное соединение через SDK Feishu, публичный 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 = требовать упоминание @ (по умолчанию)
• false = отвечать без упоминаний

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

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

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

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

{
  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

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

Получение

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

Отправка

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

DiscordGoogle Chat