Адаптер 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 секунд) |