Конфигурация
AiHummer настраивается через каталог настроек, а не через кучу переменных
окружения. gateway.env — только bootstrap: DSN базы, адреса/порты, мастер-ключ
и подобное. Все остальные ключи живут в базе данных и меняются из веб-админки в
рантайме или через CLI aihummer settings. Ведущее правило простое: всё
настраиваемое конфигурируется в Web UI — не только через env и не зашито в код.
Порядок разрешения
Каждая настройка каталога разрешается одинаково, побеждает первое совпадение:
- База данных — значение, заданное через админку или
aihummer settings set. - Default — встроенное значение по умолчанию из релиза.
Окружение в этой цепочке сознательно не участвует: для ключей каталога
переменная AIHUMMER_* в gateway.env игнорируется, даже если она задана.
Так у каждой настройки ровно один источник истины — база данных, — и значение из
UI не может быть незаметно перекрыто забытой строкой в env-файле.
[!NOTE] Для изменения поведения в продакшене вы не правите конфиг-файлы — вы меняете настройку в админке (Управление → Настройки, страница с поиском) или командой
aihummer settings set <KEY> <VALUE>(get/list— для чтения), и изменение вступает в силу для этого workspace. Установщик сам сеет стартовые значения каталога в базу черезaihummer settings set.
Горячие и требующие перезапуска
Как вступает в силу изменённая настройка, зависит от ключа:
| Поведение | Примеры | Когда применяется |
|---|---|---|
| Горячие | включение инструментов, макс. глубина суб-агентов | Перечитываются в рантайме, без перезапуска |
| Требуют перезапуска | адрес прослушивания, проводка некоторых сервисов | Применяются при следующем перезапуске gateway |
Горячие ключи перечитываются вживую, поэтому переключение инструмента или
изменение subagent-depth вступает в силу на следующем ходу. Некоторые
структурные ключи вступают в силу только после перезапуска; админка помечает, что
есть что.
Bootstrap-переменные остаются только в env
Несколько переменных обязаны присутствовать в окружении, потому что они нужны ещё до того, как существует каталог настроек (и база, из которой он читает). Эти bootstrap-переменные доступны только через env и не выводятся в админке:
| Переменная | Почему bootstrap |
|---|---|
AIHUMMER_DATABASE_URL |
БД должна существовать до чтения любой настройки из БД. |
AIHUMMER_DB_APP_URL |
DSN ограниченной роли, активирующий RLS. |
AIHUMMER_MASTER_KEY |
base64-32 байта; разблокирует секреты-в-покое / vault / BYOK. |
AIHUMMER_GATEWAY_ADDR |
Публичный адрес прослушивания (по умолчанию :8780) — API, пейринг, WS/SSE, входящие и прокси приложения/pocket. |
AIHUMMER_WEBUI_ADDR |
Приватный адрес прослушивания админ-Web UI (по умолчанию :8781), раздаётся по корню /; установите 0, чтобы отключить. |
AIHUMMER_BLOB_DIR |
Путь к директории блобов/медиа на файловой системе — нужен при старте. |
AIHUMMER_OIDC_ISSUER |
Защищает /v1/admin/* до того, как UI станет доверенным. |
К той же bootstrap-категории относится и ops-проводка вроде OTLP-эндпоинта телеметрии. Всё, чего нет в этом коротком списке, — ключ каталога: он живёт в БД, и env для него игнорируется.
[!WARNING] Храните
AIHUMMER_MASTER_KEYв безопасности и делайте его резервную копию отдельно от бэкапа базы данных. Он расшифровывает vault доступов; потеряете его — зашифрованные секреты восстановить нельзя.
Конфиг-файл
Для host-native установок bootstrap-окружение лежит в одном файле, который загружает systemd-юнит:
~/.aihummer/etc/gateway.envПравьте этот файл только для bootstrap-значений, затем перезапустите сервис 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/mainsystemctl restart aihummer-gatewayВсё за пределами этих bootstrap-ключей — агенты, инструменты, режим памяти,
стратегии рассуждения, бюджеты, guardrails и прочее — управляется из настроек
админки (или через aihummer settings), а не из этого файла: env для таких
ключей игнорируется.
Подключение опциональных возможностей
Многие функции выключены, пока вы не укажете их на backing-сервис. Все эти ключи
— настройки каталога (живут в БД): задавайте их в админке (Управление →
Настройки) или через CLI; писать их в gateway.env бесполезно — 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
# Включить инструменты, указав на их бэкенды
aihummer settings set SEARXNG_URL http://localhost:8888
aihummer settings set CLOAKBROWSER_CDP_URL http://localhost:9222
# Голосовые сайдкары (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] Реальная модель никогда не обязательна. Без подключённых
AIHUMMER_LLM_*ответы приходят из детерминированного mock; AiHummer также работает на свободных/локальных OpenAI-совместимых эндпоинтах и транспорте через подписку Codex/ChatGPT, с опциональным BYOK.
Уведомления
Страница «Уведомления» админки (группа «Контроль») — это входящая лента событий инстанса (вход администратора, доступное/применённое обновление, падение и восстановление сайдкаров и т.д.) с фильтрами по категории, важности и непрочитанным. Рядом — матрица категория × канал доставки: для каждой категории событий включаются каналы webui, email, telegram и push. Уведомления webui доставляются локально; Telegram привязывается кнопкой «Привязать Telegram» (deep-link), email активируется после подтверждения адреса поддержки, push приходит в мобильное приложение. Критичные события нельзя отключить в канале webui.
Куда дальше
- Защитите вход администратора: Первый вход.
- Посмотрите, где лежат файлы: Установка.
- Проверьте предварительные требования: Требования.