Конфигурация — AiHummer Документация

AiHummer настраивается через каталог настроек; переменные окружения используются только для начальной загрузки. gateway.env — только загрузочные параметры: DSN базы, адреса/порты, мастер-ключ и подобное. Все остальные ключи живут в базе данных и меняются из админ‑панели на лету или через CLI aihummer settings. Ведущее правило простое: всё настраиваемое конфигурируется в веб‑интерфейсе — не только через переменные окружения и не зашито в код.

Порядок разрешения

Каждая настройка каталога разрешается одинаково, побеждает первое совпадение:

База данных — значение, заданное через админ‑панель или aihummer settings set.
Значение по умолчанию — встроенное значение из релиза.

Окружение в этой цепочке сознательно не участвует: для ключей каталога переменная AIHUMMER_* в gateway.env игнорируется, даже если она задана. Так у каждой настройки ровно один источник истины — база данных, — и значение из веб‑интерфейса не может быть незаметно перекрыто забытой строкой в env-файле.

[!NOTE] Для изменения поведения в промышленной эксплуатации вы не правите конфиг-файлы — вы меняете настройку в админ‑панели (Управление → Настройки, страница с поиском) или командой aihummer settings set <KEY> <VALUE> (get / list — для чтения), и изменение вступает в силу для этого рабочего пространства. Установщик сам сеет стартовые значения каталога в базу через aihummer settings set.

Что применяется сразу, а что требует перезапуска

Как вступает в силу изменённая настройка, зависит от ключа:

Поведение	Примеры	Когда применяется
Применяются сразу	включение инструментов, макс. глубина суб-агентов	Перечитываются на лету, без перезапуска
Требуют перезапуска	адрес прослушивания, проводка некоторых сервисов	Применяются при следующем перезапуске gateway

«Горячие» ключи перечитываются сразу, поэтому переключение инструмента или изменение subagent-depth вступает в силу при следующей обработке запроса. Некоторые структурные ключи вступают в силу только после перезапуска; админ‑панель помечает, что есть что.

Загрузочные переменные остаются только в окружении

Переменные окружения — только для начальной загрузки. Несколько переменных обязаны присутствовать в окружении, потому что они нужны ещё до того, как существует каталог настроек (и база, из которой он читает). Эти загрузочные переменные доступны только через окружение и не выводятся в админ‑панели:

Переменная	Почему загрузочная
`AIHUMMER_DATABASE_URL`	БД должна существовать до чтения любой настройки из БД.
`AIHUMMER_DB_APP_URL`	DSN ограниченной роли, активирующий RLS.
`AIHUMMER_MASTER_KEY`	base64-32 байта; разблокирует секреты-в-покое / хранилище секретов / BYOK.
`AIHUMMER_GATEWAY_ADDR`	Публичный адрес прослушивания (по умолчанию `:8780`) — API, привязка устройств, WS/SSE, входящие и прокси приложения/pocket.
`AIHUMMER_WEBUI_ADDR`	Приватный адрес прослушивания веб‑интерфейса администратора (по умолчанию `:8781`), раздаётся по корню `/`; установите `0`, чтобы отключить.
`AIHUMMER_BLOB_DIR`	Путь к каталогу медиафайлов на файловой системе — нужен при старте.
`AIHUMMER_OIDC_ISSUER`	Защищает `/v1/admin/*` до того, как веб‑интерфейс станет доверенным.

К той же загрузочной категории относится и инфраструктурная проводка вроде OTLP-endpoint телеметрии. Всё, чего нет в этом коротком списке, — ключ каталога: он живёт в БД, и окружение для него игнорируется.

[!WARNING] Что произойдёт: зашифрованные секреты будет невозможно восстановить — резервная копия базы без AIHUMMER_MASTER_KEY не позволит расшифровать секреты. При каком условии: если мастер-ключ утерян или хранится в том же месте, что и погибшая резервная копия. Как исправить заранее: храните AIHUMMER_MASTER_KEY и его резервную копию отдельно от резервной копии базы данных.

Конфиг-файл

Для установок без контейнеров загрузочное окружение лежит в одном файле, который загружает systemd-юнит:

~/.aihummer/etc/gateway.env

Правьте этот файл только для загрузочных значений, затем перезапустите службу gateway, чтобы применить изменения:

# ~/.aihummer/etc/gateway.env (фрагмент)
AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer
AIHUMMER_MASTER_KEY=base64-32-bytes...
AIHUMMER_GATEWAY_ADDR=:8780
AIHUMMER_WEBUI_ADDR=:8781
AIHUMMER_OIDC_ISSUER=https://idp.example/realms/main

systemctl restart aihummer-gateway

Ожидаемый результат: служба перезапустилась без ошибок (systemctl status aihummer-gateway — active (running)), новые загрузочные значения действуют.

Всё за пределами этих загрузочных ключей — агенты, инструменты, режим памяти, стратегии рассуждения, бюджеты, правила безопасности и прочее — управляется из настроек админ‑панели (или через aihummer settings), а не из этого файла: окружение для таких ключей игнорируется.

Подключение опциональных возможностей

Многие функции выключены, пока вы не укажете для них обслуживающий сервис. Все эти ключи — настройки каталога (живут в БД): задавайте их в админ‑панели (Управление → Настройки) или через CLI; писать их в gateway.env бесполезно — окружение для них игнорируется. Значения для дополнительных сервисов, установленных из пакета (STT/TTS и т.д.), установщик сеет в базу сам.

# Подключить реальную модель (не задано → детерминированный mock)
aihummer settings set AIHUMMER_LLM_PROVIDER openai
aihummer settings set AIHUMMER_LLM_MODEL gpt-4o-mini
aihummer settings set AIHUMMER_LLM_GATEWAY_URL https://api.openai.com/v1

# Включить инструменты, указав на их бэкенды

# Голосовые сайдкары (STT/TTS установщик настраивает автоматически)
aihummer settings set AIHUMMER_STT_URL http://localhost:8001
aihummer settings set AIHUMMER_TTS_URL http://localhost:8002

# Реальное векторное хранилище + эмбеддер (URL — пример; эмбеддер ставится
# флагом --with-embedder, иначе лексический fallback)
aihummer settings set AIHUMMER_QDRANT_URL http://localhost:6333
aihummer settings set AIHUMMER_EMBEDDER_URL http://localhost:8080

[!TIP] Для запуска и тестирования платный API‑ключ не нужен. Без подключённых AIHUMMER_LLM_* ответы приходят из детерминированной тестовой модели (mock); для рабочих ответов AiHummer работает на свободных/локальных OpenAI-совместимых endpoints и транспорте через подписку Codex/ChatGPT, с опциональным собственным ключом провайдера (BYOK).

Уведомления

Страница «Уведомления» админ‑панели (группа «Контроль») — это входящая лента событий инстанса (вход администратора, доступное/применённое обновление, падение и восстановление дополнительных сервисов и т.д.) с фильтрами по категории, важности и непрочитанным. Рядом — матрица категория × канал доставки: для каждой категории событий включаются каналы webui, email, telegram и push. Уведомления webui доставляются локально; Telegram привязывается кнопкой «Привязать Telegram» (deep-link), электронная почта активируется после подтверждения адреса поддержки, push приходит в мобильное приложение. Критичные события нельзя отключить в канале webui.

Куда дальше

Первый вход — защитите вход администратора, прежде чем продолжать настройку.
Справочник переменных окружения — полный список загрузочных переменных и ключей каталога настроек.