nanobot — сверхлёгкий self-hosted AI-агент на Python

nanobot — открытый фреймворк личного AI-агента от команды HKUDS. Он написан на Python и распространяется под лицензией MIT. Авторы называют проект ультралёгким: инструменты, долговременная память, MCP-интеграции, маршрутизация моделей, под-агенты и автоматизации по расписанию уместились в небольшое читаемое ядро. При этом агент доступен откуда угодно: в браузере, в терминале и в привычных чат-приложениях — Telegram, Discord, Slack, WeChat, Feishu, почте и других.

Что умеет nanobot

nanobot позиционируется как runtime для личного AI-агента, который вы хостите сами. Список возможностей из README:

• работает в браузерном WebUI или в терминале;
• подключается к Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear и другим каналам;
• вызывает инструменты: файлы, shell, веб-поиск, загрузку страниц, MCP, cron, генерацию изображений и под-агентов;
• хранит историю сессий и долговременную память через механизм Dream;
• ведёт долгие цели и запускает автоматизации по расписанию;
• предоставляет Python SDK и OpenAI-совместимый API для интеграций;
• разворачивается как долго живущий локальный или серверный агент-шлюз.

Зачем он нужен

Авторы формулируют пять причин пользоваться именно nanobot:

• Постоянство рабочих процессов — цели, память, инструменты и контекст чата не теряются между запусками и выдерживают долгую работу.
• Чат-нативность — WebUI, API, Telegram, Feishu, Slack, Discord, Teams, почта, Mattermost и Linear.
• Свобода выбора моделей — любые OpenAI-совместимые API, локальные LLM, генерация изображений, поиск и запасные модели на случай сбоя.
• Малое ядро — читаемая внутренняя архитектура, в которую MCP, память, развёртывание и автоматизации встроены с самого начала.
• Свой стек — код можно изучать, настраивать, хостить у себя и расширять без привязки к большой платформе.

Установка

Требуется Python 3.11 или новее. Git и Bun нужны только при установке из исходников. Самый простой путь — установочный скрипт одним командом.

macOS и Linux:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

Скрипт ставит пакет nanobot-ai из PyPI и сразу запускает nanobot webui, чтобы настроить первого провайдера. Системный pip он не трогает: используется виртуальное окружение, uv, pipx или управляемый venv в ~/.nanobot/venv. С флагом --dry-run можно просто посмотреть план, ничего не меняя.

Классические способы тоже работают:

uv tool install nanobot-ai

python -m pip install nanobot-ai

Для самых свежих функций проект советует установку из исходников в editable-режиме:

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Проверить установку можно так:

nanobot --version

Если консоль, API-ключи и конфиги для вас в новинку, у проекта есть отдельное руководство Start Without Technical Background с пошаговым диалоговым сценарием установки.

Первый запуск

Рекомендуемый первый шаг — браузерный интерфейс:

nanobot webui

Команда создаёт конфиг и рабочее пространство, поднимает локальный шлюз и открывает страницу http://127.0.0.1:8765. На свежей установке модель ещё не выбрана, поэтому настройка продолжается прямо в браузере. Дальше три шага:

1. В Settings → Models выбрать провайдера, ключ и модель.
2. Создать новый топик и отправить Hello! — любой обычный ответ значит, что всё настроено верно.
3. Перед рабочими задачами выбрать рабочее пространство и режим доступа в композере.

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

nanobot gateway --background

Это единственная команда, которая переводит общий шлюз в постоянный фоновый режим. Каналы и автоматизации остаются живыми, когда все локальные клиенты закрыты. Управление привычное:

nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop

Для быстрых проверок и скриптов есть одноразовый режим:

nanobot -m "Hello!"

Интерфейсы: терминал и браузер

Обычный запуск nanobot открывает нативный терминальный клиент. Он использует каталог запуска как рабочее пространство и делит сохранённые разговоры и локальный шлюз с WebUI. Внутри есть свои приёмы:

• / — список команд, /sessions — переключение разговоров, @ — упоминание приложения, MCP-сервера или сохранённой сессии;
• Ctrl+V — вставка картинки из буфера обмена;
• /diff — просмотр изменений файлов, /context — осмотр контекста сессии, /branch — продолжение из готового ответа в новой сессии;
• /detach — выйти, оставив задачу работать на шлюзе.

Полный справочник по CLI — в документации.

WebUI поставляется прямо в пакете с PyPI, без отдельной сборки фронтенда. Это полноценная рабочая среда:

• отдельные топики под разные задачи и проекты, плюс временные чаты, которые не сохраняются в историю и память;
• до четырёх разговоров рядом в виде колонок, строк или сетки; через меню @ агент может читать контекст соседней сессии и координировать работу;
• раскрытие активности агента: рассуждения, вызовы инструментов, правки файлов с inline-диффами, вывод команд;
• индикатор контекста: размер, токены по раундам и повторное использование кеша;
• Apps для подключения MCP-серверов, каталог Skills с переиспользуемыми инструкциями и раздел Automations с календарём запусков.

Архитектура

Идея проекта проста. Всё держится на маленьком агентном цикле: сообщения приходят из чат-приложений, LLM решает, когда нужны инструменты, а память и навыки подгружаются только как контекст. Никакого тяжёлого слоя оркестрации поверх — поэтому основной путь легко читать и расширять, а каналы, инструменты, память и варианты развёртывания добавляются, не превращая систему в монолит. Подробнее об этом — в руководстве по архитектуре.

Интеграции и API

nanobot рассчитан не только на диалог с человеком. Python SDK и OpenAI-совместимый API позволяют встроить агента в локальные инструменты и скрипты: Python SDK — для программного управления, а одноразовый режим nanobot -m — для shell-автоматизации. Провайдеров, веб-поиск, MCP и настройки безопасности собирает конфигурация.

Развёртывание

Помимо локальной работы есть облачный вариант: кнопка Deploy to Render поднимает шлюз и WebUI из готового Blueprint репозитория — потребуется ключ ANTHROPIC_API_KEY и приватный токен NANOBOT_WEB_TOKEN, а Render выделит постоянный диск для сессий, памяти и истории. Для своей инфраструктуры руководство по развёртыванию описывает Docker, Docker Compose, Linux-сервисы и LaunchAgent на macOS. Единственное условие для автоматизаций: шлюз должен работать постоянно.

Кому подойдёт

nanobot — выбор для тех, кому нужен персональный агент «на всё», а не отдельный coding-ассистент. Он уместен, если вы хотите общаться с агентом из Telegram или Slack, держать память между сессиями, назначать задачи по расписанию и при этом полностью контролировать стек: свой сервер, свои модели, читаемый код на Python. Актуальная документация стабильных релизов живёт на nanobot.wiki, свежая версия для разработчиков — в документации репозитория, а последняя на момент публикации версия — v0.3.5.