Развертывание и подключение GenericAgent: чат-боты для всех платформ — WeChat/QQ/Feishu

Обзор проекта

GenericAgent — это крайне минималистичный фреймворк автономных Agent’ов, способный к самосовершенствованию. Его ядро — всего ~3K строк кода: с помощью 9 атомарных инструментов + Agent Loop примерно в 100 строк он наделяет любой LLM системным контролем над локальной машиной.

Философия проекта довольно интересная: не закладывать навыки заранее — получать способности через эволюцию. Когда GenericAgent решает новую задачу, путь выполнения автоматически «застывает» в виде Skill. Чем дольше вы используете систему, тем больше навыков накапливается — образуется дерево навыков, полностью принадлежащее вам, которое выросло из seed-кода в 3K строк.

По сравнению с OpenClaw (~530K строк кода), GenericAgent выбирает путь минимализма: развертывание простое (pip install + API Key), не требуется сложная оркестрация сервисов. При этом сохраняются ключевые возможности — полноценный браузерный контроль, операции с клавиатурой/мышью, управление мобильными устройствами через ADB и многое другое.

---

Сложность / Время / Результат

• Сложность: для новичков; не требуется глубокий опыт программирования
• Время: около 30 минут
• Результат: вы освоите развертывание и настройку GenericAgent, а также подключение к трём ключевым IM-платформам — WeChat/QQ/Feishu — и сможете управлять компьютером с помощью ИИ прямо с телефона, где бы вы ни находились

---

Портрет целевой аудитории

• Backend- или full-stack-разработчики с опытом 1–5 лет
• Пользователи, которые хотят собрать личного AI-помощника и автоматизированные рабочие процессы
• Тем, кому интересна Agent-технология, и кто хочет быстро попробовать разработку «чтобы ИИ действительно делал работу за вас»
• Есть потребность в подключении IM-платформ с несколькими каналами (например, требуется удалённое управление компьютером через WeChat/QQ)

---

Ключевые зависимости и среда

---

Полная структура проекта

GenericAgent/
├── agentmain.py              # Главная точка входа, поддержка командной строки
├── launch.pyw                # Запуск настольного GUI
├── agent_loop.py             # Основной Agent Loop (около 100 строк)
├── llmcore.py                # Управление сессией LLM
├── ga.py                     # GenericAgentHandler: память и диспетчеризация инструментов
├── frontends/                # Адаптеры для IM-платформ
│   ├── wechatapp.py         # Bot для WeChat
│   ├── qqapp.py             # Bot для QQ
│   ├── fsapp.py             # Bot для Feishu
│   ├── tgapp.py             # Bot для Telegram
│   ├── wecomapp.py          # Bot для Enterprise WeChat
│   ├── dingtalkapp.py       # Bot для DingTalk
│   ├── tuiapp.py            # UI в терминале
│   └── ...
├── assets/
│   ├── mykey_template.py    # Шаблон конфигурации API Key
│   ├── tools_schema.json    # Определения 9 атомарных инструментов
│   ├── sys_prompt*.txt      # Системные подсказки
│   └── tmwd_cdp_bridge/    # Плагин для внедрения в браузер
├── memory/                   # Каталог хранения памяти
└── temp/                     # Временные файлы и логи

---

Пошаговая инструкция

Шаг 1: Установка проекта и зависимостей

Сначала клонируйте репозиторий и установите базовые зависимости:

# Клонирование репозитория
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# Установка базовых зависимостей
pip install requests

# Установка зависимостей для GUI (настольный режим)
pip install streamlit pywebview

# Или установка зависимостей для UI в терминале
pip install requests textual

Шаг 2: Настройка API Key

Скопируйте шаблон конфигурации:

cp assets/mykey_template.py mykey.py

Отредактируйте mykey.py и вставьте вашу конфигурацию для LLM. Ниже пример использования Defapi (на примере Claude):

# Использование Defapi для проксирования Claude (официально — полцены)
native_claude_config = {
    'name': 'claude-defapi',                    # отображаемое имя
    'apikey': 'sk-ant-your-defapi-key',         # key, предоставленный Defapi
    'apibase': 'https://api.defapi.org',        # эндпоинт со стороны Defapi
    'model': 'claude-sonnet-4-6',               # или claude-opus-4-7
    'fake_cc_system_prompt': True,              # прокси-сервису нужно включить
    'thinking_type': 'adaptive',
    'max_tokens': 16384,
}

GenericAgent автоматически определяет формат протокола по именам переменных:

• есть native + claude → NativeClaudeSession (родное поле tools)
• есть native + oai → NativeOAISession (родное поле tools для OpenAI)
• есть claude (без native) → ClaudeSession (инструменты текстового протокола)

Шаг 3: Запуск GenericAgent

Сначала проверьте, что режим командной строки работает:

python agentmain.py

Вы должны увидеть интерактивный приглашение >, и можете ввести фразу для теста:

> Создай hello.txt на рабочем столе, а содержимое пусть будет Hello World

Если всё в порядке, Agent выполнит задачу и вернёт результат.

Переключитесь в режим настольного GUI:

python launch.pyw

---

Шаг 4: Подключение Bot для WeChat

Bot для WeChat поддерживает вход по персональному QR-коду — подключается самым простым способом.

Установка дополнительных зависимостей:

pip install pycryptodome qrcode requests

Конфигурация (опционально; можно и без неё, но рекомендуется задать whitelist):

В mykey.py добавьте:

# WeChat whitelist: укажите WeChat ID, если не заполнить — разрешены все пользователи
wechat_allowed_users = []

Запуск Bot для WeChat:

python frontends/wechatapp.py

При первом запуске появится окно с QR-кодом — отсканируйте его в WeChat, чтобы подтвердить вход. После успешной авторизации ваш WeChat станет интерфейсом для диалога с GenericAgent.

Шаг 5: Подключение Bot для QQ

Bot для QQ использует официальный API роботов QQ и не требует публичного webhook — сообщения принимаются через WebSocket с долгим соединением.

Зависимости:

pip install qq-botpy

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

1. Перейдите на QQ Open Platform, создайте робота и получите AppID и AppSecret
2. В mykey.py добавьте:

qq_app_id = "ваш_APP_ID"
qq_app_secret = "ваш_APP_SECRET"
qq_allowed_users = ["user_openid"]  # или ['*'] — разрешить всех

Запуск Bot для QQ:

python frontends/qqapp.py

После того как пользователь впервые отправит сообщение роботу, его openid сохранится в temp/qqapp.log.

Шаг 6: Подключение Bot для Feishu

Bot для Feishu поддерживает множество форматов сообщений: текст, rich-текст, изображения, файлы, аудио, интерактивные карточки и т.д.

Установка зависимостей:

pip install lark-oapi

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

1. На платформе разработчиков Feishu создайте корпоративное приложение и получите AppID и AppSecret
2. В mykey.py добавьте:

fs_app_id = "cli_xxxxxxxxxxxxxxxx"
fs_app_secret = "xxxxxxxxxxxxxxxx"
fs_allowed_users = ["ou_xxxxxxxxxxxxxxxx"]  # или ['*'] — разрешить всех

Запуск Bot для Feishu:

python frontends/fsapp.py

Шаг 7: Проверка и настройка

Все Bot поддерживают эти универсальные команды:

• /new — начать новый диалог, очистив текущий контекст
• /continue — вывести снапшоты сессий, которые можно восстановить
• /continue N — восстановить N-ю историю диалогов

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

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

# Терминал 1: WeChat
python frontends/wechatapp.py

# Терминал 2: QQ
python frontends/qqapp.py

# Терминал 3: Feishu
python frontends/fsapp.py

---

Частые проблемы и способы устранения

1. После настройки API Key появляется ошибка аутентификации

Причина: ошибка в имени переменной или неверная конфигурация fake_cc_system_prompt

Решение:

• Проверьте, что имя переменной содержит правильные ключевые слова (например native_claude, oai_config и т.п.)
• Для прокси-сервиса обязательно fake_cc_system_prompt: True
• Проверьте, что apibase указан корректно (например, для Defapi это https://api.defapi.org)

2. После сканирования QR в WeChat вход не проходит

Причина: ограничения WeChat по поведенческому контролю для новых устройств

Решение:

• Попробуйте подтвердить вход в приложении на телефоне (иногда требуется повторная верификация)
• Убедитесь, что аккаунт WeChat не ведёт себя аномально
• Уменьшите частоту использования Bot, чтобы не спровоцировать ограничения

3. QQ Bot не получает сообщения

Причина: робот не включён или неверно настроены права

Решение:

• На QQ Open Platform проверьте, что робот включён
• Проверьте корректность подписки на события (нужно подписаться на событие «сообщения в личку»)
• Откройте temp/qqapp.log и убедитесь, что openid пользователя корректно записывается

4. Высокая задержка ответа у Bot для Feishu

Причина: сам LLM-инференс работает медленно или есть задержки в сети

Решение:

• Используйте более быстрые модели (например GPT-4o-mini, MiniMax-M2)
• Проверьте задержку сети до LLM API
• Уменьшите max_tokens, чтобы ускорить ответ первого токена

5. Bot не запоминает контекст диалога

Причина: выполнена команда /new или сессия истекла

Решение:

• Используйте /continue, чтобы восстановить историю сессии
• Убедитесь, что в memory/ есть права на запись
• Проверьте, есть ли записи диалогов в каталоге temp/model_responses/

6. Ошибка времени выполнения ModuleNotFoundError

Причина: отсутствует зависимость

Решение:

# Пусть Agent сам установит
> Помоги мне установить все нужные Python-зависимости

# Или вручную установить популярные зависимости
pip install requests pycryptodome qrcode streamlit pywebview

---

Дополнительное чтение / направления для развития

Возможности автоматизации браузера

После того как вы разблокируете web-инструменты, GenericAgent сможет управлять «настоящим браузером», где вы уже авторизованы, не теряя вашу сессию:

> Выполнить web setup sop, чтобы разблокировать web-инструменты

Дальше вы можете использовать так:

> Открой Taobao, найди iPhone 16, отсортируй по цене
> Зайди на B站, посмотри историю видео, которые я смотрел недавно

Браузерный плагин находится в assets/tmwd_cdp_bridge/ и поддерживает популярные браузеры, включая Chrome/Edge.

Подробности механизма самосовершенствования

Ключевое отличие GenericAgent в том, что после выполнения каждой задачи автоматически закрепляется путь выполнения в виде Skill. В следующий раз, когда вы столкнётесь с похожей задачей, можно просто вызывать готовый Skill — без повторного «разбора полётов».

Это означает:

• Чем дольше вы используете систему, тем лучше Agent понимает ваш рабочий процесс
• Дерево навыков полностью ваше и не будет похоже на чьи-то «заранее заготовленные навыки»
• Seed-код на 3K строк способен вырастить бесконечные возможности

Экосистема Skill-ов

Сообщество уже накопило сотни тысяч Skill-ов (публикация в официальном аккаунте), и вы можете:

• Попросить Agent найти: Найди мне skill для выполнения XXX
• Просто импортировать: Открой XXX и сделай по этому skill

Режимы для продвинутых пользователей

Все расширенные функции GenericAgent самодокументируются — просто задайте вопрос Agent:

Сравнение навыков программирования с Claude Code

Многих разработчиков интересует один вопрос: может ли GenericAgent заменить Claude Code или Codex?

Ответ: он умеет программировать, но не может полностью заменить.

Возможности программирования GenericAgent

GenericAgent выполняет произвольный код через инструмент code_run и в сочетании с файловыми операциями вроде file_read/file_write/file_patch обладает полноценными возможностями программирования. Если подключить модель, хорошо умеющую писать код (например Claude, GPT-4o), то он может:

• читать и записывать файлы
• выполнять команды в терминале
• дебажить код
• объяснять логику кода

# Настроить Claude как бэкенд
native_claude_config = {
    'apikey': 'your-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,
}

После чего вы можете программировать на естественном языке:

> Напиши функцию быстрой сортировки, а потом запусти тест
> Реализуй HTTP-сервер на Python
> Объясни, как работает этот React-компонент

Отличия от Claude Code / Codex

Ключевое отличие в том, что Claude Code работает через собственные протоколы и цепочки инструментов (похоже на MCP), поэтому GenericAgent не может напрямую вызывать их. Но есть следующие косвенные способы:

Способ 1: использовать Codeg параллельно

Codeg позволяет одновременно запустить GenericAgent + Claude Code + Codex и организовать совместную работу в одном UI:

# Разместите GenericAgent и Codeg в одном уровне директорий
/workspace/
  ├── GenericAgent/
  └── codeg/

# Codeg автоматически обнаружит GenericAgent, после чего они будут использоваться параллельно

Способ 2: через API-прокси (транзит)

NativeClaudeSession в GenericAgent использует протокол, совместимый с Claude Code. Если прокси-сервис (например, Defapi) поддерживает прозрачную передачу Claude Code, вы сможете вызывать программные возможности Claude через GenericAgent:

# Программирование в GenericAgent с возможностями Claude
native_claude_config = {
    'name': 'claude-defapi',
    'apikey': 'your-defapi-key',
    'apibase': 'https://api.defapi.org',
    'model': 'claude-sonnet-4-6',
    'fake_cc_system_prompt': True,  # Прозрачная передача протокола Claude Code
}

Итог

---

Reference

• GitHub: lsdefine/GenericAgent
• Technical Report: arXiv:2604.17091
• Учебник для новичков: Datawhale Hello GenericAgent
• Руководство по настройке Feishu: assets/SETUP_FEISHU.md