ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Адаптер WeChat ClawBot (WechatClaw) - Документация по функциональным возможностям платформы

Основная информация

  • Название модуля: ErisPulse-WechatClaw
  • Идентификатор платформы: wechatclaw
  • Версия модуля: 0.1.0
  • Автор поддержки: wsu2059q
  • Последнее обновление: 2026-11-17
  • Зависимости: qrcode, pycryptodome

Позиционирование платформы

Адаптер для подключения личных аккаунтов WeChat, основанный на официальном iLink Bot API Tencent (канал робота WeChat ClawBot): авторизация по сканированию QR-кода, автоматическая запись токенов, получение через длинный опрос. Официальный канал, не использует обратные протоколы; возможности ограничены тем, что разрешено официальной открытой платформой WeChat.

Подключение и привязка

  • При пустой настройке token адаптер при запуске выводит QR-код для входа (терминальный ASCII-рисунок + резервная ссылка), после подтверждения сканирования с телефона в WeChat привязка завершается
  • Сканирование через панель Dashboard (рекомендуется): адаптер регистрирует расширение «Вход по QR-коду в WeChat» в «Мастере добавления аккаунта», привязка осуществляется через прямое сканирование на панели (согласование с соглашением по сканированию панели адаптера Bilibili)
  • После успешной привязки token / bot_user_id / base_url автоматически сохраняются в config.toml с помощью без потерь TOML-движка фреймворка (с сохранением комментариев пользователя), перезапуск не требует повторного сканирования
  • В случае истечения срока действия токена (возврат 401/403 при долгой опросе) в логах отображается сообщение «Очистите токен и повторите сканирование»

Эндпоинты для входа по QR-коду (для внешних фронтенд-интерфейсов)

Адаптер при запуске регистрирует эндпоинты POST /wechatclaw/qr/start и POST /wechatclaw/qr/poll:

  • qr/start: получение QR-кода, возвращает {success, task_id, poll_token, qr_img} (qr_img — это SVG в виде data URI)
  • qr/poll: запрос с task_id и poll_token (защита от несанкционированного опроса, отсутствие возвращает 403), возвращает {success, status}, где status ∈ pending / scan / done / timeout
  • При done учетные данные автоматически записываются в конфигурацию, в ответе присутствует account

Стандартизация выравнивания

События и ответы следуют стандарту преобразования событий и спецификации ответа API.

  • В верхнем уровне события сообщения содержит стандартный message_id (используется официальный message_id, при отсутствии возвращается client_id/seq)
  • Идентификатор события содержит учетную запись ({bot_id}:{message_id}), идемпотентность и изоляция между учетными записями обрабатываются фреймворком
  • Ответ при отправке содержит стандартные поля: status / retcode / data / message_id / message + верхний уровень wechatclaw_raw

События сообщений

  • Тип события: message / private (официальный канал — личные сообщения, нет функции группового чата)
  • Входящие сообщения: text, image, voice, file, video
  • Медиа-сегменты не сохраняются на диск: содержат wechatclaw_cdn (описание CDN + ключ), загружаются и расшифровываются по требованию с помощью call_api("download_media")

Контекстные токены и ответы

Протокол требует, чтобы ответ содержал context_token (отправляется вместе с полученным сообщением). Адаптер кэширует для пользователя последний контекст:

  • Ответы в цепочке событий (event.reply() / Send.To("user", ...)) автоматически содержат контекст этого пользователя
  • Активные личные сообщения ограничены протоколом: пользователи без контекста сессии могут быть отклонены платформой (ошибка возвращается в errcode)

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

Метод Описание Официальный API
Text(text) Отправка текста (Markdown автоматически преобразуется в обычный текст) sendmessage
Image(file) Отправка изображений (URL/путь/base64:///bytes, автоматическая загрузка с шифрованием) getuploadurl + CDN
Video(file) Отправка видео То же самое
File(file) Отправка файлов То же самое
Voice(file) Отправка голосовых сообщений (только кодек SILK; остальные аудио файлы отправляются как файловые сообщения) То же самое
Reply(message_id) Отправка ответа с цитированием (цитируется последнее полученное сообщение в данном диалоге) sendmessage + ref_msg

Сегменты mention / at в личных сообщениях личных аккаунтов не имеют смысла и игнорируются при отправке.

Расширение API (call_api)

Эндпоинт Параметры Описание
download_media media (входящий медиа-сегмент wechatclaw_cdn) Скачивает и сохраняет на диск, data.path возвращает локальный путь
send_typing user_id, необязательный status (1=ввод, 2=отмена) Статус "ввод текста" (требуется действительный контекст сессии)

Ограничения платформы

  • Только личные сообщения (официальный канал не поддерживает групповые чаты)
  • Некоторые видео-сообщения могут отсутствовать ключи шифрования (известная проблема официального канала), такие медиа-файлы невозможно загрузить
  • Голосовые сообщения должны быть в кодировке SILK (encode_type=6, 24 кГц)

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

Параметр Значение по умолчанию Описание
token "" Оставьте пустым для входа через сканирование QR-кода, после привязки автоматически запишется
bot_user_id "" ID официального аккаунта, после привязки автоматически запишется
base_url Официальный по умолчанию Базовый URL API, после привязки может автоматически обновиться
login_timeout 300 Время ожидания сканирования (секунды)
poll_interval 1.0 Интервал между пакетами длинной опроса (секунды, сервер удерживает соединение около 35 секунд)