Мульти-бот Telegram-платформа на базі Claude AI. Один сервер -- багато ботів, кожен зі своєю роллю, пам'яттю, знаннями та інтеграціями.
- Пам'ять як першокласна сутність. Факти в SQLite (topic, tags, access_count) + щоденні diary-логи розмов + щотижневі консолідації через Claude. Консолідація запускається автоматично щоночі
- Команда ботів. Боти спілкуються через Unix-сокети (Colleague MCP), менеджер розподіляє задачі паралельно через
Promise.allSettled() - Повна ізоляція. Кожен бот -- окремий процес, .env, база, знання, пам'ять, голос, роль. Керуються з однієї адмін-панелі
- Живе управління. Веб-панель для створення ботів, галереї зображень, cron-задач, бекапів, діагностики. Модель та температура змінюються без рестарту, зміни .env потребують рестарту через UI
- Динамічні інтеграції. MCP-сервери підключаються за наявності env-змінних -- додав
BITRIX24_WEBHOOK_URL, перезапустив бота і він отримав CRM. Без зміни коду - Філософія. Базова роль (
_soul.md) -- маніфест: як думати, як спілкуватись, коли мовчати. Не "certainly!", а людська розмова
Паралельне виконання: веб-пошук, генерація зображення, Python-графік, курси валют — одним запитом
- Кілька ботів з одного інстансу Node.js
- 12 готових ролей -- від персонального асистента до вебмайстра
- Пам'ять -- факти (довгострокова) + щоденні diary-логи з консолідацією
- Голос -- голосові повідомлення та відповіді (Groq STT + Edge TTS)
- Зображення -- генерація та редагування через Gemini з авто-галереєю
- Gemini AI -- друга думка (AskGemini) та пошук з цитатами (GeminiSearch)
- Команда ботів -- спілкування через Unix-сокети, делегування задач
- Планувальник -- cron-задачі з повним доступом до інструментів
- Утиліти -- курси валют, час, Python sandbox, email, Telegraph
- Інтеграції -- Google Workspace, розумний дім, будь-які MCP-сервери
- Веб-пошук -- пошук, скрапінг, AI-браузер (Stagehand)
- Адмін-панель -- повний веб-інтерфейс для управління
- Аудіо-рекордер -- фоновий запис з мікрофона (Orange Pi / Mac), VAD-фільтр тиші, транскрипція Whisper
- Бекапи -- повні та per-bot, з SHA256-верифікацією
Відкрий https://botva-installer.onrender.com/, введи IP сервера, Telegram-токен -- і через 3-5 хвилин бот працює. Детальніше: DEPLOY.md
# 1. Клонувати
git clone https://github.com/cohe4ko/BotVa.git BotVa
cd BotVa
# 2. Встановити залежності та зібрати
./scripts/deploy.sh setup
# 3. Створити першого бота (варіант A: CLI)
npm run new-bot -- my-bot personal-assistant --emoji 🧑💼 --name "Мій Бот"
# 3. Створити першого бота (варіант B: веб-інтерфейс)
./scripts/deploy.sh admin # Запустити адмін-панель
# Відкрий http://localhost:3000 → Create Bot
# Токен та chat ID вводяться у формі створення
# 4. Налаштувати токени (якщо CLI)
# Відкрий bots/my-bot/.env:
# - TELEGRAM_BOT_TOKEN (отримати у @BotFather в Telegram)
# - ALLOWED_CHAT_ID (надіслати /chatid боту після запуску)
# 5. Запустити
./scripts/deploy.sh startПісля запуску напиши боту в Telegram -- він відповість.
Створення бота через веб-інтерфейс
Обери роль, введи Telegram-токен від @BotFather та chat ID. API-ключі можна додати пізніше.
Після створення — структура файлів та наступні кроки.
При створенні бота обираєш роль -- вона визначає спеціалізацію, інструменти та стиль.
| Роль | Slug | Опис |
|---|---|---|
| Персональний асистент | personal-assistant |
Повсякденні задачі, розклад, CRM, розумний дім |
| Дослідник | researcher |
Глибокий аналіз, верифікація фактів, звіти |
| Здоров'я | health-advisor |
Моніторинг показників, аналізи, рекомендації |
| Академічний | academic |
Наукові статті, методологія, PhD, викладання |
| Креативний | creative |
Дизайн, зображення, презентації, копірайтинг |
| Продажі | sales |
Ліди, угоди, аналіз продажів, пропозиції |
| Планувальник | planner |
Задачі, дедлайни, пріоритизація |
| База знань | knowledge-base |
Документація, FAQ, пошук знань |
| Менеджер | manager |
Координація команди ботів, делегування |
| Продукт/Ринок | product-market |
CRM-аналітика, позиціонування, конкуренти |
| Вебмайстер | webmaster |
Сайт, контент, деплой, SEO |
| Дебати та дослідження | debate-researcher |
Аналіз з протилежних позицій |
npm run new-bot -- <slug> <роль> [--emoji 🤖] [--name "Назва"]Перша взаємодія з ботом — привітання, налаштування профілю, нагадування та пошук з уточнюючими питаннями:
Бот розуміє голосові повідомлення та може відповідати голосом. STT через Groq Whisper (потрібен GROQ_API_KEY), TTS через Edge-TTS (безкоштовно). Команда /voice вмикає/вимикає голосові відповіді.
Генерація та редагування через Gemini (GOOGLE_API_KEY). Команда /img опис або просто попроси в чаті. Всі зображення зберігаються в галереї.
Трирівнева система: факти (постійне сховище з topic та tags), щоденні markdown-логи, workspace-файли (USER.md, MEMORY.md). Консолідація о NIGHT_OWL_HOUR.
Ліворуч: збереження фактів через SaveFact/SearchMemory. Праворуч: заповнення профілю через AskUser
Cron-задачі: /schedule 0 9 * * * Що в мене на сьогодні?. Стандартний 5-полевий cron.
Менеджер координує роботу, боти спілкуються через Colleague MCP (Unix-сокети). Кожен бот може звернутись до менеджера через ask_manager().
SendMedia (фото, документи, альбоми), ForwardMessage, SetReaction, PinMessage, OpenWebApp (Mini App), AskUser (кнопки, poll).
CurrencyRates (готівкові курси), GetCurrentTime, RunPython (sandbox), SendEmail (SMTP), PublishTelegraph.
Бот читає та оновлює свої файли між сесіями: USER.md (профіль), MEMORY.md (пам'ять) через ReadWorkspaceFile / WriteWorkspaceFile.
Детальний посібник: MANUAL.md
Будь-який MCP-сервер можна підключити через mcp-servers.json.
Вбудовані (в комплекті):
| Інтеграція | MCP-сервер | Потрібні змінні |
|---|---|---|
| Playwright (headless Chrome) | playwright-remote |
-- |
| Stagehand (AI-браузер) | stagehand |
GOOGLE_API_KEY |
| Google Calendar, Gmail, Drive | google-workspace |
GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET |
| Home Assistant | home-assistant |
HA_URL, HA_TOKEN |
Інші MCP-сервери (CRM, реклама, наукові бази тощо) додаються як запис в mcp-servers.json та увімкнюються в адмінці System → MCP Servers.
Система фонового запису аудіо з мікрофонів, автоматична транскрипція (Groq Whisper) та аналіз через Claude.
Компоненти:
| Компонент | Опис | Розташування |
|---|---|---|
| Receiver | HTTP-сервер, приймає WAV, транскрибує, аналізує | scripts/orange-pi-listener/receive-transcript.ts |
| Orange Pi Listener | Python-демон для SBC з мікрофоном | scripts/orange-pi-listener/listener.py |
| Mac Listener | Electron tray app для macOS | scripts/mac-listener/ |
Як працює:
- Пристрій записує аудіо чанками (за замовчуванням 5 хв)
- VAD (Voice Activity Detection) фільтрує тишу — чанки з < 15% мовлення пропускаються
- Чанки з голосом відправляються на Receiver (
POST /audio, multipart WAV) - Receiver транскрибує через Groq Whisper та зберігає щоденні конспекти
Mac Listener (tray app):
cd scripts/mac-listener && npm install && npm startEnv: UPLOAD_URL=http://host:3847/audio, DEVICE_ID=mac-1. Два режими: Toggle (ручний старт/стоп) та Continuous (автоматичні чанки). Вимагає ffmpeg.
Receiver:
npx tsx scripts/orange-pi-listener/receive-transcript.tsEnv: GROQ_API_KEY (або GROQ_API_KEYS), LISTENER_PORT=3847, ANTHROPIC_API_KEY (для аналізу).
Пристрої відображаються в адмін-панелі System → Recorder.
Веб-інтерфейс для управління ботами. Два способи запуску:
# 1. З Telegram (on-demand, автостоп через 20 хв)
/admin
# 2. Як окремий сервіс (постійний)
./scripts/deploy.sh admin| Розділ | Що робить |
|---|---|
| Dashboard | Статус ботів, запити, витрати, сервіси |
| Config | Модель, температура, env-змінні, workspace files |
| Knowledge | Файли знань бота |
| Facts | Пам'ять: перегляд, пошук, редагування |
| Tasks | Заплановані cron-задачі |
| Settings | Налаштування чатів, сесії |
| Usage | Аналітика токенів та витрат |
| System | Builtin tools, MCP servers, skills on/off |
| Images | Галерея згенерованих зображень |
| Logs | Аудит подій |
| Diagnostics | AI-діагностика системи |
| Backup | Створення та відновлення бекапів |
| Team | Управління командою ботів |
| Templates | Шаблони ролей |
| Terminal | Браузерний shell |
| Create Bot | Майстер створення нового бота |
Детальний посібник: MANUAL.md
Команди /usage, /model, /facts, /settings — управління ботом з Telegram
| Команда | Опис |
|---|---|
/start |
Привітання та chat ID |
/chatid |
Показати chat ID |
/newchat, /forget |
Очистити сесію (пам'ять залишається) |
/voice |
Увімкнути/вимкнути голосові відповіді |
/img <опис> |
Згенерувати зображення |
/model |
Перемкнути модель (Opus/Sonnet/Haiku) |
/schedule <cron> <текст> |
Створити задачу |
/usage |
Статистика токенів |
/stats |
Inline-статистика on/off |
/lang |
Мова інтерфейсу |
/admin |
Адмін-панель |
/session |
Перегляд CLI-сесій |
/cancel |
Скасувати запит |
BotVa/
├── src/ # Код платформи (TypeScript)
│ ├── index.ts # Точка входу
│ ├── bot.ts # Telegram бот
│ ├── agent.ts # Claude agent з MCP
│ ├── builtin-tools.ts # Вбудовані інструменти
│ ├── memory.ts # Система пам'яті
│ ├── db.ts # SQLite
│ ├── voice.ts # STT/TTS
│ ├── imagen.ts # Генерація зображень
│ ├── scheduler.ts # Планувальник
│ └── admin/ # Веб адмін-панель
├── roles/ # Шаблони ролей
│ ├── _soul.md # Базовий характер (для всіх ботів)
│ ├── _tools.md # Базовий routing інструментів
│ └── *.md # Ролі (personal-assistant, researcher, ...)
├── mcp-servers/ # MCP сервери
│ ├── colleague/ # Міжботова комунікація
│ └── manager/ # Координація менеджером
├── scripts/ # Скрипти управління
├── installer/ # Веб-інсталятор
├── bots/ # Дані ботів (gitignored)
├── workspace/ # Runtime дані (gitignored)
├── .env.example # Шаблон конфігурації
└── package.json
./scripts/deploy.sh setup # Встановити залежності, зібрати
./scripts/deploy.sh start # Запустити всі боти
./scripts/deploy.sh stop # Зупинити
./scripts/deploy.sh restart # Перезапустити
./scripts/deploy.sh build # Перезібрати TypeScript + MCP
./scripts/deploy.sh status # Статус
./scripts/deploy.sh backup # Бекап
./scripts/deploy.sh restore # ВідновленняДетальний гайд з конфігурацією та всіма варіантами: DEPLOY.md
- Runtime: Node.js 20+, TypeScript (strict)
- Telegram: Grammy
- AI: Anthropic Claude Agent SDK
- Database: SQLite (вбудований в Node.js)
- Web: Hono
- Voice: Edge-TTS (синтез), Groq Whisper (розпізнавання)
- Images: Google Gemini
- Browser: Stagehand / Playwright
- Тести: Vitest 4.x
Дивись CONTRIBUTING.md.
Як дізнатись свій chat ID?
Запусти бота та надішли /start або /chatid.
Як додати знання боту?
Поклади .md або .txt файли в bots/<name>/knowledge/. Також через адмін-панель (Knowledge).
Як підключити інтеграцію?
Додай відповідні змінні в .env бота. Після перезапуску бот автоматично отримає інструменти.
Як переїхати на інший сервер? Дивись розділ "Міграція" в DEPLOY.md.
MIT