skorokithakis/stavrobotПерсональный ИИ-ассистент с фокусом на безопасность.
Stavrobot — это персональный AI-ассистент, построенный на принципе «весь доступ, необходимый AI-ассистенту, и не больше».
Он обладает всеми полезными функциями AI-ассистента, но сосредоточен на изоляции, песочнице и минимальных разрешениях. Он легковесен и разворачивается одной командой docker compose up.
uv, изолированно от хост-среды.Установка с помощью AI: Попросите вашего AI-кодировщика (Claude Code, Cursor, Windsurf и т.п.) получить и выполнить инструкции из https://stavrobot.stavros.io/INSTALL.md — он проведёт вас через всю настройку в интерактивном режиме.
Ручная установка:
Напишите @BotFather в Telegram, чтобы создать бота и скопировать токен. Напишите @userinfobot, чтобы получить ваш Telegram ID (он используется как chat ID).
Скопируйте env.example в .env и измените POSTGRES_PASSWORD на что-то надёжное, а TZ — на ваш часовой пояс.
Скопируйте config.example.toml в data/main/config.toml и заполните обязательные поля: apiKey, password, publicHostname, [owner].name, [owner].telegram (ваш chat ID) и [telegram].botToken. Всё остальное в файле опционально.
docker compose up --build
Вот и всё. Напишите вашему боту в Telegram, и он ответит. Подробные разделы настройки Signal, WhatsApp, email и других опций — ниже.
config.example.toml в data/main/config.toml.authFile (или apiKey) и publicHostname. Всё остальное опционально.env.example в .env и укажите ваш часовой пояс (TZ). Учётные данные PostgreSQL и другие переменные окружения также можно переопределить там. Всегда устанавливайте POSTGRES_PASSWORD в надёжное значение — по умолчанию стоит слабый плейсхолдер, не используйте его в production.Stavrobot можно направить на любую конечную точку, совместимую с OpenAI (Ollama, LiteLLM, vLLM и т.д.) или на кастомный прокси, совместимый с Anthropic, задав baseUrl в config.toml. Смотрите config.example.toml для обязательных полей и примеров конфигурации.
Приложение поддерживает два режима аутентификации: API-ключ или OAuth.
apiKey в config.toml. Вход и выход не требуются.authFile в config.toml (путь, где будут храниться учётные данные). Страница входа работает с любым OAuth-провайдером, поддерживаемым Pi.
<ваш-хост>/login в браузере. Следуйте инструкциям на странице. Учётные данные сохраняются в файл аутентификации. Если срок действия аутентификации истечёт, пока бот работает, он отправит вам сообщение с URL для входа через вашу платформу обмена сообщениями.authFile. При следующем сообщении бот обнаружит отсутствие учётных данных и снова предложит войти.Контейнер coder опционален (нужен только для функции самостоятельного программирования). Он использует Claude Code с подписочной аутентификацией (OAuth), отдельно от основного API-ключа приложения.
Профили Docker Compose разделяются запятыми, так что их можно комбинировать (например COMPOSE_PROFILES=signal,coder).
COMPOSE_PROFILES в вашем файле .env, включив coder (например, COMPOSE_PROFILES=coder или COMPOSE_PROFILES=signal,coder, если вы также используете Signal).docker compose --profile coder up --builddocker compose exec -u coder coder claude (будет предложено войти, если вы ещё этого не сделали).[coder].model в вашем конфиге — псевдоним модели Claude Code (sonnet, opus или haiku).Signal требует отдельный номер телефона — не ваш личный. Подойдёт предоплаченная SIM-карта или VoIP-номер.
COMPOSE_PROFILES=signal в вашем файле .env, чтобы включить контейнер signal-bridge.docker compose --profile signal builddocker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' — отсканируйте QR-код телефоном (Signal > Настройки > Привязанные устройства).docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +ВАШ_НОМЕР register', затем подтвердите: docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +ВАШ_НОМЕР verify КОД'.[signal].account в вашем конфиге.docker compose up --build/settings.docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Отправь сообщение \"Привет от Stavrobot\" на мой номер Signal.'})}).then(r=>r.text()).then(console.log)"
[telegram].botToken в вашем конфиге.[owner].telegram в конфиге./settings.WhatsApp требует отдельный номер телефона, иначе вы будете писать сами себе, что не имеет смысла.
WhatsApp использует Baileys — неофициальную библиотеку WhatsApp Web, которая подключается как сопутствующее устройство (как WhatsApp Web). Отдельный номер телефона не нужен — она привязывается к вашему существующему аккаунту WhatsApp.
Риск: Baileys использует неофициальный API. WhatsApp может блокировать аккаунты, использующие его. Используйте на свой страх и риск.
[whatsapp] в ваш config.toml (смотрите config.example.toml для формата).docker compose up --builddocker compose logs -f app)../data/whatsapp./settings.Email использует Cloudflare Email Worker для входящей доставки и SMTP для исходящей. Полный код воркера и подробные инструкции по настройке см. в config.example.toml.
[email] в ваш config.toml с SMTP-учётными данными и случайным webhookSecret.config.example.toml) и задайте переменные окружения WEBHOOK_URL и WEBHOOK_SECRET на воркере./settings.docker compose up --build
API доступно по адресу http://localhost:10567/chat.
Примечание: Docker Compose открывает приложение только на localhost:10567. Чтобы сделать его доступным извне (требуется для вебхуков Telegram/Signal и настройки publicHostname), настройте обратный прокси (например, Nginx, Caddy), указывающий на localhost:10567. Также можно открыть порт напрямую, но это не рекомендуется, так как трафик будет незашифрован.
Требуется Node.js >= 20 и работающий экземпляр PostgreSQL.
npm install && npm run build && npm start
Примечание: выполнение Python и интеграция Signal работают только внутри Docker-контейнеров.
У Stavrobot трехуровневая система знаний: воспоминания, блокнот и база данных. Бот будет в основном управлять ими самостоятельно, но вам важно знать о них, чтобы помогать боту использовать их правильно.
Воспоминания всегда целиком внедряются в системный промпт. Используйте их экономно, так как они попадают в контекст при каждом обращении, и большое их количество может увеличить контекст. Пример хорошего воспоминания: «пользователь предпочитает неформальный стиль общения» — то, что бот должен знать каждый раз, даже если это стоит дополнительной длины контекста.
Блокнот (scratchpad) — место для реже используемых знаний, но относящихся к определённой теме. Записи блокнота имеют заголовок и тело. Заголовок автоматически попадает в контекст. Используйте это для важных, но не столь часто нужных вещей, обычно относящихся к конкретной теме.
Например, хорошей записью в блокноте будет «диетические предпочтения» с подробностями о том, что вы любите есть, когда и т.д. Бот будет видеть, что существует тема «диетические предпочтения», но не будет загружать сам текст в контекст автоматически, обращаясь к нему по запросу.
Когда вы общаетесь с ботом о еде, он будет знать, что есть запись в блокноте «диетические предпочтения», к которой можно обратиться, и обычно будет делать это самостоятельно.
База данных — третий уровень для структурированных или массовых данных, которым не место в воспоминаниях или блокноте. У бота есть полный доступ на чтение и запись к PostgreSQL через неограниченный SQL, так что он может создавать таблицы, выполнять запросы и хранить что угодно. Используйте это для списков, логов, структурированных записей или любых данных, которые удобнее искать запросами, чем читать как прозу.
Обычно бот сам хорошо понимает, что где использовать, но иногда стоит явно указать, какую информацию куда поместить.
Stavrobot может отправлять сообщения от вашего имени через Signal, Telegram, WhatsApp или email. Нужно договориться с другом об ужине? Скажите боту найти время, удобное для вас обоих — он напишет, согласует дату и добавит в календарь. Хотите записаться на приём, скоординировать групповую встречу или задать кому-то вопрос, пока вы заняты? Просто скажите боту, что нужно и с кем поговорить.
Бот для каждого разговора создаёт выделенного суб-агента со своими инструкциями и контекстом, чтобы вести диалог с собеседником, не засоряя ваш основной чат. Когда задача выполнена, он отключает контакт и сообщает вам результат.
Для безопасности общение требует выполнения двух условий, прежде чем бот сможет с кем-то заговорить:
/settings и добавьте его номер телефона (Signal или WhatsApp) или chat ID (Telegram). Это делается один раз для каждого человека. Бот не может изменять этот список и не может отправлять сообщения никому, кто в него не внесён, что бы вы ни сказали.Типичный сценарий: вы один раз добавляете номер друга в белый список через /settings, затем говорите боту «найди время на ужин с Алексеем на следующей неделе». Бот создаёт запись контакта для Алексея, запускает суб-агента, пишет Алексею в Signal, обсуждает дату и сообщает вам результат.
Навыки — это текстовые файлы с инструкциями, которые обучают бота новым возможностям: создавать таблицы, сохранять знания, делать страницы или следовать определённым рабочим процессам. Это не код, а инструкции на естественном языке, которые бот читает и выполняет.
Чтобы установить систему навыков, скажите боту получить https://stavrobot.stavros.io/skills/bootstrap.md и следовать инструкциям.
Полный список доступных навыков — на https://stavrobot.stavros.io/skills/index.md. Чтобы установить навык, просто скажите боту получить и установить его по этому URL. Бот покажет, что делает навык, и запросит подтверждение перед установкой.
Файлы навыков находятся в ветке pages этого репозитория (размещены через Cloudflare Pages). Чтобы добавить навык, добавьте Markdown-файл в папку skills/ в этой ветке. Каждый файл навыка содержит YAML-шапку с полями title, description, version и опциональным author, а затем инструкции на естественном языке в теле. Смотрите SKILL-AUTHORING.md для полного руководства по созданию. Отправляйте PR в ветку pages.
Смотрите PLUGIN.md — там есть всё, что нужно знать для создания плагина Stavrobot. Этот же документ подходит как справочник и для людей, и для LLM.
Плагины довольно необходимы для базовой функциональности бота, например, возможность «слышать» голосовые сообщения, отправлять голосовые сообщения, узнавать о местах вокруг вас, искать в интернете и т.д.
Эти возможности не предоставляются «из коробки», чтобы вы могли настроить бота так, как хотите. Тем не менее, рекомендуется установить плагины, иначе вам будет не хватать критически важных функций.
Вы можете найти некоторые плагины от разработчиков здесь:
Три основных Docker-контейнера: app (сервер на TypeScript, принимает POST /chat, обрабатывает вебхуки Telegram на POST /telegram/webhook, обрабатывает входящие email-вебхуки на POST /email/webhook, и запускает WhatsApp в процессе через Baileys), postgres (PostgreSQL 17 для постоянного хранения состояния) и plugin-runner (сервер на Node.js — выводит список, проверяет и выполняет плагины, как локально созданные, так и установленные через git). Опциональный контейнер coder (безголовый агент Claude Code для создания и изменения редактируемых плагинов) включается через профиль coder Docker Compose. Основной агент может создавать суб-агентов, каждый со своей историей разговора, системным промптом и белым списком инструментов. Собеседники — это записи контактов, закреплённые за агентами для маршрутизации входящих сообщений.