Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.
Практический гайд До 12 минут Windows · Telegram · Ollama

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

Локальный AI-агент в Telegram: подключаем Hermes к Ollama
Temporary fallback cover; replace in editorial pass.

Локальный AI-агент работает на вашем компьютере, а Telegram становится удобным пультом управления с телефона. В этой статье соберём минимальный шлюз для Windows: Telegram-бот будет принимать сообщения только от разрешённого пользователя и передавать их локальной модели Ollama.

Важно разделить роли. Telegram отвечает за интерфейс и доставку сообщений, небольшой Python-шлюз — за проверку доступа, а Ollama — за локальный HTTP API модели. Hermes можно использовать как установленный локальный агент или как рабочий профиль поверх Ollama; сам принцип подключения остаётся тем же: шлюз обращается к локальной точке Ollama.

Что получится в конце

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 выполните проверки по порядку:

  1. /id — убедитесь, что видите свой user ID.
  2. /status — бот должен ответить «Ollama доступна».
  3. /model — проверьте выбранное имя модели.
  4. Отправьте короткий вопрос обычным сообщением.

Для проверки ограничения доступа попросите другого пользователя отправить сообщение вашему боту или используйте другой аккаунт. Ответ должен быть «Доступ запрещён». Само знание токена без разрешённого 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.