Локальный AI-агент в Telegram: подключаем Hermes к Ollama

Локальный AI-агент работает на вашем компьютере, а Telegram становится удобным пультом управления с телефона. В этой статье соберём минимальный шлюз для Windows: Telegram-бот будет принимать сообщения только от разрешённого пользователя и передавать их локальной модели Ollama.
Важно разделить роли. Telegram отвечает за интерфейс и доставку сообщений, небольшой Python-шлюз — за проверку доступа, а Ollama — за локальный HTTP API модели. Hermes можно использовать как установленный локальный агент или как рабочий профиль поверх Ollama; сам принцип подключения остаётся тем же: шлюз обращается к локальной точке Ollama.
Что получится в конце
- Ollama запущена на Windows и отвечает локально.
- Telegram-бот принимает команды с телефона.
- Доступ разрешён только одному Telegram user ID.
- Команды
/id,/statusи/modelпомогают проверить связку. - Локальный API не публикуется в интернет.
1. Подготовьте Ollama и модель
Установите Ollama для Windows обычным способом и убедитесь, что команда доступна в PowerShell. Затем загрузите модель, которую планируете использовать. Ниже используется имя-пример llama3.2; замените его на модель, которая уже есть у вас.
ollama pull llama3.2
ollama list
ollama run llama3.2
Окно с ollama run можно закрыть после проверки ответа. Фоновый API Ollama обычно доступен локально по адресу http://127.0.0.1:11434. Проверим его из PowerShell:
Invoke-RestMethod http://127.0.0.1:11434/api/tags
Если команда вернула список моделей, локальная часть готова. Не меняйте адрес на 0.0.0.0 и не пробрасывайте порт 11434 на роутере: Telegram-шлюзу достаточно обращаться к Ollama внутри этого же компьютера.
2. Создайте Telegram-бота
В Telegram откройте официального бота для управления ботами, создайте нового бота и сохраните выданный токен в безопасном месте. Токен — это пароль: его нельзя помещать в статью, репозиторий или публичный чат.
Узнать свой user ID можно после запуска шлюза командой /id. До этого подготовьте только токен. В примере ниже он хранится в переменной окружения, а не в исходном файле.
3. Создайте изолированное окружение Python
В PowerShell создайте отдельную папку проекта и виртуальное окружение:
mkdir hermes-telegram-gateway
cd hermes-telegram-gateway
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install python-telegram-bot httpx
Если PowerShell запрещает запуск скрипта активации, используйте временную настройку только для текущего окна:
Set-ExecutionPolicy -Scope Process Bypass
.venv\Scripts\Activate.ps1
4. Добавьте шлюз
Создайте файл bot.py и вставьте код ниже. Это рабочий минимальный пример: он не выполняет команды Windows, не открывает файлы и не публикует Ollama наружу. В модель передаётся только текст сообщения.
import os
import httpx
from telegram import Update
from telegram.ext import (
Application,
CommandHandler,
ContextTypes,
MessageHandler,
filters,
)
TELEGRAM_TOKEN = os.environ["TELEGRAM_TOKEN"]
OLLAMA_URL = os.getenv("OLLAMA_URL", "http://127.0.0.1:11434")
OLLAMA_MODEL = os.getenv("OLLAMA_MODEL", "llama3.2")
# Заполните после первого запуска командой /id.
ALLOWED_USER_ID = int(os.getenv("ALLOWED_USER_ID", "0"))
def is_allowed(update: Update) -> bool:
user = update.effective_user
return bool(user and user.id == ALLOWED_USER_ID)
async def reject(update: Update) -> None:
if update.message:
await update.message.reply_text("Доступ запрещён.")
async def id_command(
update: Update, context: ContextTypes.DEFAULT_TYPE
) -> None:
if not update.effective_user or not update.message:
return
await update.message.reply_text(
f"Ваш Telegram user ID: {update.effective_user.id}"
)
async def status_command(
update: Update, context: ContextTypes.DEFAULT_TYPE
) -> None:
if not is_allowed(update):
await reject(update)
return
try:
async with httpx.AsyncClient(timeout=10) as client:
response = await client.get(f"{OLLAMA_URL}/api/tags")
response.raise_for_status()
await update.message.reply_text("Ollama доступна.")
except Exception as error:
await update.message.reply_text(
f"Ollama недоступна: {type(error).__name__}"
)
async def model_command(
update: Update, context: ContextTypes.DEFAULT_TYPE
) -> None:
if not is_allowed(update):
await reject(update)
return
await update.message.reply_text(
f"Текущая модель: {OLLAMA_MODEL}"
)
async def chat(
update: Update, context: ContextTypes.DEFAULT_TYPE
) -> None:
if not update.message or not update.message.text:
return
if not is_allowed(update):
await reject(update)
return
payload = {
"model": OLLAMA_MODEL,
"prompt": update.message.text,
"stream": False,
}
try:
async with httpx.AsyncClient(timeout=120) as client:
response = await client.post(
f"{OLLAMA_URL}/api/generate",
json=payload,
)
response.raise_for_status()
data = response.json()
answer = data.get("response", "").strip()
await update.message.reply_text(
answer or "Модель вернула пустой ответ."
)
except httpx.HTTPStatusError:
await update.message.reply_text(
"Ollama вернула ошибку. Проверьте имя модели."
)
except Exception as error:
await update.message.reply_text(
f"Ошибка шлюза: {type(error).__name__}"
)
def main() -> None:
application = (
Application.builder()
.token(TELEGRAM_TOKEN)
.build()
)
application.add_handler(CommandHandler("id", id_command))
application.add_handler(CommandHandler("status", status_command))
application.add_handler(CommandHandler("model", model_command))
application.add_handler(
MessageHandler(filters.TEXT & ~filters.COMMAND, chat)
)
application.run_polling()
if __name__ == "__main__":
main()
5. Запустите и зафиксируйте user ID
В первом запуске разрешённый ID ещё неизвестен. Поэтому временно запускаем бота с нулевым значением, отправляем /id и читаем число в ответе. Команда /id не вызывает Ollama и нужна только для первичной настройки.
$env:TELEGRAM_TOKEN="ВСТАВЬТЕ_ТОКЕН_БОТА"
$env:OLLAMA_MODEL="llama3.2"
$env:ALLOWED_USER_ID="0"
python bot.py
Откройте чат с ботом, нажмите Start и отправьте /id. Скопируйте полученный user ID. Остановите программу сочетанием Ctrl+C, затем запустите её снова уже с вашим числом:
$env:ALLOWED_USER_ID="123456789"
python bot.py
Число 123456789 — пример, а не настоящий идентификатор. Используйте только значение, которое бот показал в вашем чате.
6. Проверьте шлюз
В Telegram выполните проверки по порядку:
/id— убедитесь, что видите свой user ID./status— бот должен ответить «Ollama доступна»./model— проверьте выбранное имя модели.- Отправьте короткий вопрос обычным сообщением.
Для проверки ограничения доступа попросите другого пользователя отправить сообщение вашему боту или используйте другой аккаунт. Ответ должен быть «Доступ запрещён». Само знание токена без разрешённого user ID не даёт доступа через этот код, но токен всё равно нужно защищать и перевыпустить при утечке.
Безопасные настройки
- Храните
TELEGRAM_TOKENв переменной окружения, а не вbot.py. - Оставляйте
OLLAMA_URLравнымhttp://127.0.0.1:11434. - Не добавляйте в шлюз выполнение произвольных команд PowerShell без отдельной модели разрешений.
- Не пересылайте модели пароли, токены, персональные данные и содержимое рабочих каталогов.
- Ограничение по user ID — базовый фильтр, а не полноценная система аутентификации.
- Если токен бота попал в публичное место, немедленно перевыпустите его через интерфейс управления ботами.
Типовые ошибки
«Команда ollama не найдена»
Ollama не установлена, не добавлена в PATH или PowerShell был открыт до установки. Перезапустите терминал и проверьте установку. При необходимости запускайте Ollama из установленного приложения, затем повторите ollama list.
«Ollama недоступна»
Проверьте, что Ollama запущена, а локальный API отвечает на http://127.0.0.1:11434/api/tags. Если используется другой адрес или порт, задайте его через $env:OLLAMA_URL.
Модель не найдена
Значение OLLAMA_MODEL должно точно совпадать с именем из вывода ollama list. Это может быть не только короткое имя, но и имя с тегом.
Telegram не отвечает
Проверьте токен, интернет-соединение и то, что запущен именно тот процесс Python, которому задана переменная TELEGRAM_TOKEN. Один токен не следует одновременно обслуживать несколькими экземплярами бота.
Бот отвечает «Доступ запрещён»
Сравните значение ALLOWED_USER_ID с результатом команды /id. Не добавляйте кавычки внутрь самой переменной и перезапустите процесс после изменения настройки.
Ограничения решения
Этот пример использует long polling: программа сама получает обновления Telegram и должна постоянно работать на компьютере. При выключенном или спящем Windows-компьютере бот не ответит. История диалога также не сохраняется: каждый запрос отправляется в модель отдельно.
Это намеренно минимальный шлюз. Он не включает автоматический запуск Windows, очередь запросов, журналирование, несколько пользователей, подтверждение опасных действий или полноценное подключение инструментов Hermes. Такие функции стоит добавлять по одной и отдельно проверять права каждого действия.
Итог
Мы получили локальный Telegram-шлюз к Ollama: бот принимает сообщения с телефона, проверяет user ID и отправляет разрешённые запросы локальной модели. Hermes можно подключать поверх той же модели и локального окружения, сохраняя главный принцип безопасности: Telegram не должен открывать наружу административный доступ к Windows.
Для следующего шага откройте раздел гайдов, а определения терминов сверяйте в глоссарии Agent Lab Journal.