Переменные окружения

Большинство рабочих настроек хранится в БД. Здесь перечислены только загрузочные, инфраструктурные и совместимые переменные окружения.

Конфигурация AiHummer делится на две строго разные группы:

Загрузочные (gateway.env) — то, что шлюзу нужно знать до того, как он может прочитать базу: DSN базы данных, адреса прослушивания, каталоги статики, мастер-ключ. Только эти ключи читаются из окружения.
Каталог настроек (БД) — все остальные параметры. Они хранятся в базе и задаются в веб-интерфейсе (Управление → Настройки) или командой aihummer settings set <KEY> <VALUE>. Для этих ключей значение в gateway.env сознательно игнорируется — даже если оно выставлено, оно не действует.

Модель конфигурации

gateway.env — только начальная загрузка. Порядок разрешения:

ключ Каталога настроек: значение из БД → встроенное значение по умолчанию (окружение игнорируется);
загрузочный ключ: только переменная окружения.

То есть единственный источник истины для настраиваемых параметров — база данных (веб-интерфейс / aihummer settings), а окружение несёт лишь то, без чего процесс не стартует.

Для каждого ключа каталога тип, значение по умолчанию, секретность и необходимость перезапуска отображаются в его карточке в веб-интерфейсе (Управление → Настройки). В облачных инстансах загрузочные переменные управляются платформой; вам доступны ключи каталога настроек.

Файл конфигурации при установке на своём сервере находится по пути:

# ~/.aihummer/etc/gateway.env
AIHUMMER_DATABASE_URL=postgres://...
AIHUMMER_MASTER_KEY=base64-32-bytes

[!TIP] Не вписывайте параметры Каталога настроек в gateway.env — это не даст эффекта. Меняйте их в веб-интерфейсе (Управление → Настройки, есть поиск) или через aihummer settings set. Часть изменений (переключатели инструментов, глубина суб-агентов) применяется сразу, другие требуют перезапуска службы — карточка настройки помечает, что есть что.

Загрузочные переменные (gateway.env)

Единственные ключи, которые шлюз действительно читает из окружения. Изменение любой из них требует перезапуска службы; в облаке они управляются платформой.

Ядро и база данных

Переменная	Тип	По умолчанию	Секрет	Назначение
`AIHUMMER_DATABASE_URL`	DSN	—	да	Обязательно. DSN Postgres. Без неё шлюз работает только в режиме health-only.
`AIHUMMER_DB_APP_URL`	DSN	—	да	DSN ограниченной роли, активирующий Row-Level Security (для локальных установок ставится автоматически).
`AIHUMMER_GATEWAY_ADDR`	адрес	`:8780`	нет	Публичный адрес прослушивания — весь внешний трафик: API (`/v1/*`), привязка устройств, WS/SSE, входящие вебхуки, прокси приложения/pocket и пробы работоспособности.
`AIHUMMER_WEBUI_ADDR`	адрес	`:8781`	нет	Приватный адрес прослушивания веб-интерфейса администратора, раздаётся по корневому пути `/`; в идеале привязан к внутреннему интерфейсу. Установите `0`, чтобы отключить.
`AIHUMMER_DEFAULT_WORKSPACE_ID`	строка	—	нет	Выбирает рабочее пространство по умолчанию для настроенных входящих интеграций.
`AIHUMMER_HOME_ROOT`	путь	из пути бинарного файла	нет	Корень установки; привязывает каталоги admin-ui/blob/установщика и файлы ключей.
`AIHUMMER_BLOB_DIR`	путь	—	нет	Включает сервис медиа/файлов (каталог хранилища). Здесь же хранятся приватные (частная загрузка) артефакты плагинов под ссылками `blob:`, которые разрешает deployer.
`AIHUMMER_ADMIN_UI_DIR`	путь	—	нет	Отдаёт админ-SPA по `/admin/`.

Секреты и инфраструктура

Переменная	Тип	По умолчанию	Секрет	Назначение
`AIHUMMER_MASTER_KEY`	base64 (32 байта)	—	да	Включает шифрование секретов, хранилище секретов и BYOK.
`AIHUMMER_MEDIA_TOKEN_SECRET`	строка	—	да	Сохраняет валидность подписанных URL для скачивания между перезапусками.
`AIHUMMER_OTEL_ENDPOINT`	URL	—	нет	OTLP-endpoint для отправки трейсов/метрик.
`AIHUMMER_DOWNLOAD_BASE_URL`	URL	CDN вендора	нет	Базовый URL артефактов релизов (источник самообновления).

[!WARNING] AiHummer предоставляет базовые метрики Prometheus по GET /metrics и при необходимости отправляет расширенную телеметрию через OTLP. /debug/pprof не публикуется. Для трейсов и подробных метрик направьте AIHUMMER_OTEL_ENDPOINT на ваш коллектор.

Каталог настроек (БД — веб-интерфейс или `aihummer settings`)

Все ключи ниже живут в базе. Тип, значение по умолчанию, секретность и необходимость перезапуска каждого ключа показаны в его карточке в веб-интерфейсе. Задавайте их в веб-интерфейсе (Управление → Настройки) или так:

aihummer settings set AIHUMMER_LLM_PROVIDER openai

Значение такого ключа в gateway.env игнорируется.

Безопасность

Ключ	Назначение
`AIHUMMER_APPROVAL_TOOLS`	Инструменты, требующие одобрения человеком перед выполнением.
`AIHUMMER_AIRGAPPED`	`1` блокирует управляемые моделью исходящие подключения в интернет (изолированный режим).
`AIHUMMER_AUDIT_RETENTION_DAYS`	Срок хранения журнала аудита админ-панели.
`AIHUMMER_INBOUND_SECRET`	HMAC-секрет для вызовов коннектор → gateway `/v1/inbound/*`.

Аутентификация и SSO

Ключ	Назначение
`AIHUMMER_OIDC_ISSUER`	Защищает `/v1/admin/*`. Без неё (и без LDAP/SAML) админ-панель доверяет dev-заголовкам — никогда не выставляйте такой инстанс наружу.

LDAP/AD и SAML настраиваются вместе с OIDC для корпоративного входа; SCIM обеспечивает автоматическое создание пользователей. См. Вебхуки, SCIM и привязку устройств.

LLM и модели

Ключ	Назначение
`AIHUMMER_LLM_PROVIDER`	Используемый провайдер модели.
`AIHUMMER_LLM_MODEL`	Имя модели.
`AIHUMMER_LLM_GATEWAY_URL`	Базовый URL OpenAI-совместимого LLM-шлюза/endpoint (путь `AIHUMMER_LLM_*`; отличается от нативного `AIHUMMER_OPENAI_BASE_URL`). См. BYOK и провайдеры.
`AIHUMMER_OPENAI_API_KEY`	Ключ для OpenAI-совместимого провайдера.
`AIHUMMER_SUBAGENT_MAX_DEPTH`	Максимальная глубина порождаемых суб-агентов.

[!NOTE] Если модель не подключена, шлюз переходит на детерминированную тестовую модель (mock) — она проверяет маршрут и интерфейс, но не выполняет рабочие задачи. Для запуска платный API-ключ не нужен; для рабочих ответов подключите локальную модель, транспорт через подписку Codex/ChatGPT или собственный ключ.

Инструменты

Ключ	Назначение
`AIHUMMER_FS_ROOT`	Включает `filesystem_read`, в песочнице под этим корнем.
`AIHUMMER_DB_QUERY_DSN`	Включает `db_query` (только чтение) к этому DSN.
`AIHUMMER_CODE_EXEC`	Переключает инструмент `code_exec` (по умолчанию выключен на общих хостах).

Веб-поиск и браузер управляются установщиком: они ставятся из коробки, отключаются флагами --no-search / --no-browser, а внешний инстанс подключается флагами --external-search=URL / --external-browser=URL — отдельных операторских настроек у них нет.

Полный Каталог инструментов описывает, что делает каждый инструмент.

Голос и дополнительные сервисы

Ключ	Назначение
`AIHUMMER_STT_URL`	URL сервиса speech-to-text (заполняется установщиком).
`AIHUMMER_TTS_URL`	URL сервиса text-to-speech (заполняется установщиком).
`AIHUMMER_VIDEO_URL`	URL сервиса понимания видео.

Дополнительные сервисы — это отдельные HTTP-сервисы; шлюз обращается к ним по URL.

Векторы и эмбеддинги

Ключ	Назначение
`AIHUMMER_QDRANT_URL`	Реальное векторное хранилище (Qdrant). Отсутствует → in-memory хранилище.
`AIHUMMER_EMBEDDER_URL`	Реальный сервис эмбеддингов. Отсутствует → hash-эмбеддер.

Протокольные поверхности (опционально)

Ключ	Назначение
`AIHUMMER_MCP_PUBLISH`	Ровно `1` открывает внешний MCP-сервер по `POST /v1/mcp`. Сам по себе не экспортирует ни одного инструмента.
`AIHUMMER_MCP_EXPORT_TOOLS`	Точные имена инструментов через запятую, которые увидит MCP-клиент. Пусто (умолчание) — экспортируется НОЛЬ инструментов.
`AIHUMMER_A2A_PUBLISH`	`1` включает A2A-поверхность (`/.well-known/agent.json`, `/a2a/message`).

Только для dev-сборок

Переменная	Назначение
`AIHUMMER_PLUGIN_PUBKEY`	Дополнительный доверенный публичный ключ (base64 ed25519) для проверки подписи плагинов. Только dev-сборки — в релизных сборках игнорируется (ключ реестра закреплён в бинарном файле).
`AIHUMMER_PLUGIN_DEV_UNSIGNED`	`1` разрешает установку неподписанных плагинов. Только dev-сборки — в релизных сборках игнорируется. Никогда на инстансе, доступном извне.

[!WARNING] В релизных сборках корень доверия плагинов запечён в бинарный файл и не переопределяется ни окружением, ни настройками — это защита от подмены.

Модель доверия (official → закреплённый ключ, private → trust-store, неподписанные → блок) описана в Установке и обновлениях.

Куда дальше

Какие инструменты включает каждый ключ: Каталог инструментов.
Ежедневное управление инстансом: Справочник CLI.