Hermes Agent API: подключаем агента к Open WebUI и своим программам

Hermes Agent API — это встроенный в Hermes Agent HTTP-сервер, который говорит на языке OpenAI. Любая программа, умеющая работать с OpenAI, — веб-чат Open WebUI, официальная библиотека openai для Python, обычный curl — получает доступ не к голой модели, а к вашему агенту: с терминалом, файлами, памятью и навыками. Включается он двумя строками в ~/.hermes/.env и по умолчанию слушает только 127.0.0.1:8642. Ниже — проверенный порядок действий: включить API, убедиться, что он отвечает, подключить веб-чат для сотрудников (включая ловушку Linux-сервера, о которой молчит инструкция), вызвать агента из своей программы и закрыть то, что API открывает.

Главное коротко

• API-сервер — это агент, а не прокси к модели. Каждый запрос выполняет полноценный агент на той машине, где запущен Hermes, со всеми инструментами, включая терминал.
• Ключ короче 16 символов сервер не примет — и не скажет об этом в консоли. Пример your-secret-key из документации по Open WebUI — ровно 15 символов: шлюз запустится, а API — нет.
• На Linux-сервере рецепт с host.docker.internal из коробки не сработает. Hermes слушает только 127.0.0.1, а контейнер приходит с другого адреса. Рабочий вариант — сетевой режим host, он разобран в шаге 4.
• Ключ API открывает не только чат. По нему доступны история сессий профиля, задания по расписанию и запуски агента, поэтому обращаться с ним нужно как с паролем администратора.

На чём это проверено

Статья написана по релизу Hermes Agent v0.22.2 (опубликован 15 октября 2026 года). Все команды Hermes из статьи выполнены на чистой установке этой версии под Linux: включение API, ответы /health, /v1/models, /v1/chat/completions и /v1/responses, потоковая выдача, поведение при коротком ключе и при открытии сервера наружу. Вместо платной нейросети к агенту была подключена локальная заглушка в формате OpenAI, поэтому ответы в примерах — служебные; слой API от этого не меняется. Значения по умолчанию сверены с исходным кодом релиза (gateway/platforms/api_server.py, gateway/config_env.py, hermes_cli/auth.py).

Open WebUI — версия v0.12.3 (16 октября 2026 года). Её параметры сверены с исходным кодом (backend/start.sh, backend/open_webui/config.py) и README проекта. Сам контейнер Open WebUI в этой проверке не запускался, поэтому для него приводятся только параметры, подтверждённые исходниками.

Оба проекта выпускают обновления часто: только между 14 и 15 октября у Hermes вышли v0.22.0, v0.22.1 и v0.22.2. Если ваша версия заметно новее, сверяйтесь с первоисточниками в конце статьи.

Что должно быть готово

• Установленный Hermes Agent — по пошаговой инструкции по установке Hermes Agent.
• Подключённая модель и рабочий шлюз (gateway) — это разобрано в статье о первичной настройке Hermes: ключи, модель, мессенджер.
• Для веб-чата — Docker на той же машине.

Проверьте версию:

hermes --version

Первая строка ответа должна выглядеть так: Hermes Agent v0.22.2 (2026.9.24). Если версия старше, обновитесь командой hermes update.

Что такое API-сервер Hermes и чем он не является

API-сервер — одна из «платформ» шлюза Hermes, такая же, как Telegram или Discord. Только вместо мессенджера к агенту приходят HTTP-запросы в формате OpenAI. Основные адреса:

Адрес	Зачем нужен	Нужен ли ключ
GET /health	Проверка, что сервер жив	Нет
GET /v1/models	Список «моделей» — для выпадающего меню в чат-клиентах	Да
POST /v1/chat/completions	Классический чат: клиент каждый раз присылает всю историю	Да
POST /v1/responses	Формат Responses: история может храниться на стороне Hermes	Да

Кроме них есть собственные интерфейсы Hermes: запуски с подпиской на события и остановкой, управление сессиями, задания по расписанию, список навыков. Что умеет именно ваша версия, показывает запрос GET /v1/capabilities с ключом — он возвращает перечень поддерживаемых функций. Для подключения чата и своих скриптов хватает четырёх адресов из таблицы.

Четыре вещи, которые важно понять до настройки:

• Команды выполняются там, где работает Hermes. Если Open WebUI открыт на ноутбуке, а Hermes стоит на сервере, то ls, работа с файлами и браузер агента выполняются на сервере, а не на ноутбуке. Так прямо написано в документации Hermes.
• Название модели в запросе почти ничего не решает. Сервер отдаёт одну «модель» — hermes-agent (или имя профиля). Если клиент по привычке пришлёт gpt-4o, Hermes всё равно ответит той моделью, что настроена у агента. Мы это проверили: запрос с "model": "gpt-4o" ушёл к модели по умолчанию.
• Системный промпт клиента дополняет агента, а не заменяет его. Инструкция из Open WebUI ложится поверх собственного промпта Hermes; инструменты, память и навыки остаются на месте.
• Каждый запрос — полноценный ход агента, а не один вызов модели. По пути агент может запустить несколько инструментов, поэтому ответ приходит медленнее, чем от голой нейросети, и стоит больше токенов: вместе с вопросом модель получает описания всех доступных инструментов. В нашей проверке даже на короткое приветствие Hermes передал модели описания 19 инструментов.

Для бизнеса это два сценария: общий веб-чат с агентом для сотрудников и программный доступ к агенту из сайта, CRM или скриптов. Если же нужно, чтобы агент сам разбирал заявки, готовил отчёты и документы прямо в ваших системах, мы встроим агента в процессы 1С, Битрикс24 и сайта — API Hermes в такой связке лишь один из способов подключения.

Шаг 1. Включить API-сервер

Две команды: флаг включения и ключ доступа. Ключ генерируем сразу стойким — 32 случайных байта в шестнадцатеричном виде:

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY "$(openssl rand -hex 32)"

Ожидаемый ответ — по строке на каждую команду:

✓ Set API_SERVER_ENABLED in /home/<пользователь>/.hermes/.env
✓ Set API_SERVER_KEY in /home/<пользователь>/.hermes/.env

Обе настройки попадают в ~/.hermes/.env: в v0.22.2 все имена в верхнем регистре config set пишет именно туда. Страница документации об Open WebUI утверждает, что флаг уходит в config.yaml, — в проверенной версии это не так, но на работу не влияет.

Требования к ключу. Hermes принимает ключ длиной не меньше 16 символов и отвергает очевидные заглушки: changeme, placeholder, example, dummy, your-api-key, строки из одних x и похожие. Причина в исходном коде названа прямо: этот адрес запускает работу агента с доступом к терминалу, и угадываемый ключ равен удалённому выполнению команд.

Ключ понадобится в следующих шагах. Посмотреть его можно так (команда выведет секрет на экран — не делайте этого при демонстрации экрана):

grep '^API_SERVER_KEY=' ~/.hermes/.env

Шаг 2. Перезапустить шлюз и найти строку запуска

Если шлюз установлен как служба (так он настраивается в инструкции по установке):

hermes gateway restart

Если вы запускаете шлюз вручную в терминале — остановите его Ctrl+C и запустите снова:

hermes gateway run

В консоли вы увидите только рамку «Hermes Gateway Starting...». Строка о запуске API пишется в журнал, поэтому проверяйте его:

grep "API server listening" ~/.hermes/logs/gateway.log | tail -1

Правильный результат:

... INFO gateway.platforms.api_server: [Api_Server] API server listening on http://127.0.0.1:8642 (model: hermes-agent)

Если строки нет, а в журнале есть No messaging platforms enabled. (или подключились только ваши мессенджеры), значит ключ не прошёл проверку. Мы воспроизвели это с ключом your-secret-key: шлюз стартовал без ошибок, порт 8642 так и не открылся. Сгенерируйте ключ командой из шага 1 и перезапустите шлюз.

Шаг 3. Проверить тремя запросами

Сначала — что сервер жив. Этот адрес открыт без ключа:

curl -s http://127.0.0.1:8642/health

{"status": "ok", "platform": "hermes-agent", "version": "0.22.2"}

Затем — что без ключа он никого не пускает:

curl -s http://127.0.0.1:8642/v1/models

{"error": {"message": "Invalid gateway API key (API_SERVER_KEY)", "type": "gateway_auth_error", "code": "gateway_auth_failed"}}

Это ответ с кодом 401 — так и должно быть. Теперь с ключом:

KEY=$(grep '^API_SERVER_KEY=' ~/.hermes/.env | cut -d= -f2-)
curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8642/v1/models

{"object": "list", "data": [{"id": "hermes-agent", "object": "model", ...}]}

И первый настоящий запрос к агенту:

curl -s http://127.0.0.1:8642/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Ответь одной фразой: ты на связи?"}]}'

В ответе ищите "object": "chat.completion", текст агента в choices[0].message.content и расход токенов в usage. Ответ может занять заметное время: агент вправе вызвать инструменты, прежде чем ответить.

Имя hermes-agent отдаёт профиль по умолчанию. У именованного профиля «моделью» будет его имя, а задать своё название можно переменной API_SERVER_MODEL_NAME.

Шаг 4. Веб-чат для сотрудников: Open WebUI

Open WebUI — самый популярный самостоятельно размещаемый веб-интерфейс для чата с нейросетями: учётные записи, история диалогов, выбор модели. К Hermes он подключается как к OpenAI. Запросы идут от сервера Open WebUI к серверу Hermes, а не из браузера, поэтому настройка CORS (API_SERVER_CORS_ORIGINS) для этой связки не нужна.

Вариант А. Mac или Windows с Docker Desktop

Команды ниже берут ключ из переменной KEY, которую мы задали в шаге 3; если вы открыли новый терминал, задайте её снова той же командой. Здесь работает рецепт из документации Hermes. Docker Desktop сам направляет имя host.docker.internal на ваш компьютер. Мы лишь добавили 127.0.0.1 перед портом: по документации Docker опубликованный порт по умолчанию доступен не только с этого компьютера, но и снаружи.

docker run -d -p 127.0.0.1:3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY="$KEY" \
  -e ENABLE_OLLAMA_API=false \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Интерфейс откроется по адресу http://localhost:3000.

Вариант Б. Linux-сервер: ловушка 127.0.0.1

На Linux тот же рецепт с добавкой --add-host=host.docker.internal:host-gateway выглядит рабочим, но моделей в Open WebUI не будет. По документации Docker host-gateway указывает на внутренний IP-адрес хоста, а Hermes по умолчанию слушает только 127.0.0.1. Мы проверили: пока API привязан к 127.0.0.1, по другому адресу той же машины он не отвечает вовсе. README Open WebUI описывает ровно этот симптом для Ollama и советует сетевой режим host. Для Hermes он подходит так же:

docker run -d --network=host \
  -e HOST=127.0.0.1 \
  -e OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1 \
  -e OPENAI_API_KEY="$KEY" \
  -e ENABLE_OLLAMA_API=false \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Что здесь важно:

• В режиме host параметр -p не используется, и Open WebUI слушает свой стандартный порт 8080, а не 3000.
• HOST=127.0.0.1 — переменная из стартового скрипта Open WebUI (по умолчанию там 0.0.0.0). С ней веб-чат не торчит в интернет вместе с сервером.
• ENABLE_OLLAMA_API=false убирает пустой раздел Ollama из списка моделей. Если Ollama у вас действительно стоит рядом, эту строку не добавляйте.

Открыть чат со своего компьютера проще всего через SSH-туннель:

ssh -L 8080:127.0.0.1:8080 пользователь@адрес-сервера

Пока туннель открыт, интерфейс доступен на вашем компьютере по адресу http://localhost:8080. Для постоянного доступа сотрудников из офиса и дома нужен обратный прокси с HTTPS или VPN — это отдельная настройка сервера.

Второй выход — открыть сам API наружу (hermes config set API_SERVER_HOST 0.0.0.0). Мы его проверили, и Hermes сам предупреждает в журнале:

API server is network-accessible (0.0.0.0) AND the terminal backend is 'local' (unsandboxed). Agent work dispatched through this endpoint runs as the host user with full terminal/file access.

Иначе говоря, любой, кто дотянется до порта и подберёт ключ, получит терминал вашего пользователя. Без межсетевого экрана и песочницы этот вариант не используйте.

Первый вход и типичные сюрпризы

• Первая зарегистрированная учётная запись становится администратором. Зарегистрируйтесь сразу после запуска, пока адрес не увидел никто другой.
• Первый запуск небыстрый. По данным документации Hermes, Open WebUI при первом старте скачивает модели для поиска по документам. Следите за журналом командой docker logs -f open-webui.
• Переменные окружения читаются только при первом запуске. Дальше Open WebUI хранит подключения в своей базе (в коде за это отвечает настройка ENABLE_PERSISTENT_CONFIG, по умолчанию включена). Чтобы поменять адрес или ключ позже, откройте аватар → Admin Settings → Connections → раздел OpenAI API и отредактируйте подключение.
• В списке моделей появится hermes-agent. Выберите его и пишите. При потоковой выдаче Open WebUI показывает короткие отметки о работе инструментов — какую команду агент запустил, что ищет.

Шаг 5. Вызов агента из своей программы

Официальная библиотека OpenAI для Python работает с Hermes без доработок — достаточно указать адрес и ключ. Мы проверили этот код с библиотекой openai 2.24.0:

import os
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8642/v1",
    api_key=os.environ["HERMES_API_KEY"],
)

reply = client.chat.completions.create(
    model="hermes-agent",
    messages=[{"role": "user", "content": "Сколько будет 2+2?"}],
)
print(reply.choices[0].message.content)

Ключ передавайте через переменную окружения HERMES_API_KEY, а не вписывайте в код.

Диалог с памятью на стороне Hermes. Формат Chat Completions не хранит состояние: программа каждый раз присылает всю переписку. Если удобнее, чтобы историю помнил сервер, используйте /v1/responses с именованным разговором:

curl -s http://127.0.0.1:8642/v1/responses \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "input": "Заявка 1042: клиент просит перенести доставку на пятницу", "conversation": "zayavka-1042"}'

Следующий запрос с тем же "conversation": "zayavka-1042" продолжает разговор. Мы проверили: второй запрос пришёл к модели вместе с предыдущим обменом репликами. Учтите ограничение из документации: сервер хранит не больше 100 ответов и вытесняет самые старые. Это механизм для текущих диалогов, а не архив переписки с клиентами.

Ещё два ограничения, о которых лучше знать заранее:

• Файлы через API не загрузить. Картинки можно передать прямо в сообщении, а документы и вложения сервер отклоняет с ошибкой 400 unsupported_content_type.
• Одновременно выполняется до 10 запусков агента. Сверх лимита сервер отвечает HTTP 429 с текстом Too many concurrent runs (max 10). Лимит меняется ключом gateway.api_server.max_concurrent_runs в config.yaml; значение 0 снимает ограничение.

Безопасность: что вы открываете вместе с API

• Ключ API равен доступу к терминалу и к истории разговоров. Храните его в менеджере паролей или в хранилище секретов, не в коде и не в чатах. Если ключ утёк — сгенерируйте новый (шаг 1), перезапустите шлюз и обновите подключение в Open WebUI: старый ключ там сохранён в базе.
• Оставьте адрес 127.0.0.1. Значение по умолчанию — правильное. Всё, что должно ходить к API, лучше запускать на той же машине или пускать через туннель.
• Вынесите терминал агента в песочницу. Запросы через API выполняет тот же агент, поэтому изоляция терминала защищает и этот канал. Как её включить, разобрано в статье о песочнице Hermes Agent в Docker.
• Не включайте CORS без нужды. API_SERVER_CORS_ORIGINS нужен, только если браузер обращается к Hermes напрямую. Open WebUI и серверные скрипты в этом не нуждаются.
• Одно подключение — один агент на всех. Все пользователи Open WebUI, которые работают через одно подключение, общаются с одним профилем Hermes: у них общие память, навыки и терминал. Отдельный агент на сотрудника или отдел — это отдельные профили Hermes со своими ключами. Схема их запуска в 2026 году менялась, поэтому настраивайте её по актуальной странице документации о нескольких шлюзах (ссылка ниже).

Что ломается чаще всего

Симптом	Причина	Что сделать
В журнале нет строки «API server listening», порт 8642 закрыт	Ключ короче 16 символов или похож на заглушку	Новый ключ через openssl rand -hex 32, перезапуск шлюза
/v1/models отвечает 401 gateway_auth_failed	Ключ в клиенте не совпадает с API_SERVER_KEY	Сверить ключ; в Open WebUI — исправить сохранённое подключение
Проверка подключения в Open WebUI проходит, а моделей нет	В адресе нет суффикса /v1	Адрес должен заканчиваться на :8642/v1
На Linux Open WebUI не видит Hermes, хотя curl с сервера работает	Контейнер обращается не к 127.0.0.1	Вариант Б: --network=host
Поменяли OPENAI_API_KEY в команде запуска — ничего не изменилось	Open WebUI хранит подключение в своей базе после первого запуска	Admin Settings → Connections
HTTP 429 Too many concurrent runs	Достигнут лимит одновременных запусков	Повторить позже или поднять max_concurrent_runs
В журнале Could not bind 127.0.0.1:8642	Порт занят другой программой или вторым экземпляром Hermes	Освободить порт или задать API_SERVER_PORT и перезапустить шлюз
Ответ приходит через минуту и больше	Агент выполняет инструменты: команды, поиск, чтение файлов	Это нормально; в потоковом режиме видно, что он делает

Когда стоит позвать специалистов

Всё описанное выше рассчитано на самостоятельную работу: для одного человека или небольшой команды на одном сервере этого достаточно. Помощь со стороны оправдана в нескольких случаях:

• веб-чатом пользуются сотрудники вне офиса, и нужны HTTPS, VPN или единый вход;
• нужны отдельные агенты для отделов с разной памятью и правами;
• агент через API работает с боевыми данными: CRM, учётом, клиентской перепиской;
• некому следить за обновлениями двух быстро меняющихся проектов и за тем, чтобы обновление одного не сломало связку с другим.

Частые вопросы

Нужен ли для этого аккаунт OpenAI?

Нет. «Совместимый с OpenAI» — это только формат запросов. Отвечает та модель, которую вы подключили к Hermes: облачная любого поддерживаемого провайдера или локальная.

Можно ли подключить другой чат-клиент вместо Open WebUI?

Документация Hermes перечисляет LobeChat, LibreChat, AnythingLLM, NextChat, ChatBox, Jan и другие клиенты, которые умеют работать с собственным адресом OpenAI. Принцип тот же: адрес с /v1 и ключ API_SERVER_KEY. В этой статье мы проверяли только Open WebUI и библиотеку для Python.

Можно ли держать API и Telegram-бота одновременно?

Да. API-сервер — ещё одна платформа того же шлюза, рядом с мессенджерами. Агент, память и навыки у них общие.

Где выполняются команды, если Open WebUI на ноутбуке, а Hermes на сервере?

На сервере. Все инструменты агента работают там, где запущен API-сервер Hermes. Чтобы агент работал с файлами ноутбука, Hermes нужно запускать на ноутбуке.

Что ещё открывает ключ API, кроме чата?

Больше, чем кажется. По тому же ключу доступны история сессий профиля (/api/sessions), задания по расписанию (/api/jobs) и запуски агента с остановкой и подтверждениями (/v1/runs). Список сессий не ограничен разговорами через API: в нашей проверке в нём оказалась и сессия, начатая из командной строки. Поэтому выдавайте ключ только тем людям и программам, которым вы доверили бы самого агента.

Источники

• Документация Hermes Agent, API Server: hermes-agent.nousresearch.com/docs/user-guide/features/api-server
• Документация Hermes Agent, интеграция с Open WebUI: hermes-agent.nousresearch.com/docs/user-guide/messaging/open-webui
• Документация Hermes Agent, несколько шлюзов и профилей: hermes-agent.nousresearch.com/docs/user-guide/multi-profile-gateways
• Релиз Hermes Agent v0.22.2: github.com/NousResearch/hermes-agent/releases/tag/v0.22.2
• Open WebUI, исходный код и README: github.com/open-webui/open-webui
• Docker, публикация портов: docs.docker.com/engine/network/port-publishing
• Docker, параметр --add-host и host-gateway: docs.docker.com/reference/cli/docker/container/run

Если веб-чат и API агента нужны не в тестовом режиме, а как рабочий инструмент команды, мы развернём Hermes Agent с API и веб-чатом на вашем сервере и возьмём на себя обновления, доступы и резервные копии.