Конфигурация AiHummer делится на две строго разные группы:
Bootstrap (gateway.env) — то, что gateway нужно знать до того, как
он может прочитать базу: DSN базы данных, адреса прослушивания, каталоги
статики, мастер-ключ. Только эти ключи читаются из окружения.
Каталог настроек (БД) — все остальные параметры. Они хранятся в базе и
задаются в веб-админке (Управление → Настройки) или командой
aihummer settings set <KEY> <VALUE>. Для этих ключей
значение в gateway.envсознательно игнорируется — даже если оно
выставлено, оно не действует.
Модель конфигурации
gateway.env — только bootstrap. Порядок разрешения:
ключ Каталога настроек: значение из БД → встроенный default
(окружение игнорируется);
bootstrap-ключ: только переменная окружения.
То есть единственный источник истины для настраиваемых параметров — база данных
(веб-админка / aihummer settings), а окружение несёт лишь то, без чего процесс
не стартует.
Файл конфигурации для host-native установки находится по пути:
[!TIP]
Не вписывайте параметры Каталога настроек в gateway.env — это не даст
эффекта. Меняйте их в веб-админке (Управление → Настройки, есть поиск) или
через aihummer settings set. Часть изменений (переключатели инструментов,
глубина суб-агентов) применяются «на горячую», другие требуют перезапуска
сервиса.
Bootstrap (gateway.env)
Единственные ключи, которые gateway действительно читает из окружения.
Ядро и база данных
Переменная
Назначение
AIHUMMER_DATABASE_URL
Обязательно. DSN Postgres. Без неё gateway работает только в режиме health-only.
Публичный адрес прослушивания (по умолчанию :8780) — весь внешний трафик: API (/v1/*), пейринг, WS/SSE, входящие вебхуки, прокси приложения/pocket и health-пробы.
AIHUMMER_WEBUI_ADDR
Приватный адрес прослушивания админ-Web UI (по умолчанию :8781), раздаётся по корневому пути /; в идеале привязан к внутреннему интерфейсу. Установите 0, чтобы отключить.
AIHUMMER_DEFAULT_WORKSPACE_ID
Включает диспетчер входящих и workspace по умолчанию для виджета.
AIHUMMER_HOME_ROOT
Корень установки (обычно выводится из пути бинарника); привязывает каталоги admin-ui/blob/установщика и файлы ключей.
AIHUMMER_BLOB_DIR
Включает сервис медиа/файлов (каталог blob-хранилища). Здесь же хранятся приватные (side-loaded) артефакты плагинов под ссылками blob:, которые резолвит deployer.
AIHUMMER_ADMIN_UI_DIR
Отдаёт админ-SPA по /admin/.
AIHUMMER_WIDGET_DIR
Отдаёт веб-виджет по /widget/.
Секреты и инфраструктура
Переменная
Назначение
AIHUMMER_MASTER_KEY
32 байта в base64; включает шифрование секретов, vault и BYOK.
AIHUMMER_MEDIA_TOKEN_SECRET
Сохраняет валидность подписанных URL для скачивания между перезапусками.
[!WARNING]
Наблюдаемость работает только по push-модели OTLP. AiHummer не
предоставляет эндпоинт Prometheus /metrics или /debug/pprof. Направьте
AIHUMMER_OTEL_ENDPOINT на ваш коллектор.
Key-gated каналы установки (alfa/beta/dev) дополнительно читают
AIHUMMER_CHANNEL_KEY / AIHUMMER_RELEASE_TOKENна этапе установки.
Каталог настроек (БД — веб-админка или aihummer settings)
Все ключи ниже живут в базе. Задавайте их в веб-админке
(Управление → Настройки) или так:
aihummer settings set AIHUMMER_LLM_PROVIDER openai
Значение такого ключа в gateway.envигнорируется.
Безопасность
Ключ
Назначение
AIHUMMER_APPROVAL_TOOLS
Инструменты, требующие одобрения человеком перед выполнением.
HMAC-секрет для вызовов коннектор → gateway /v1/inbound/*.
Аутентификация и SSO
Ключ
Назначение
AIHUMMER_OIDC_ISSUER
Защищает /v1/admin/*. Без неё (и без LDAP/SAML) админка доверяет dev-заголовкам — никогда не выставляйте такой инстанс наружу.
LDAP/AD и SAML настраиваются вместе с OIDC для корпоративного входа; SCIM
обеспечивает автоматический провижининг пользователей. См.
Вебхуки, SCIM и pairing.
LLM и модели
Ключ
Назначение
AIHUMMER_LLM_PROVIDER
Используемый провайдер модели.
AIHUMMER_LLM_MODEL
Имя модели.
AIHUMMER_LLM_GATEWAY_URL
Эндпоинт OpenAI-совместимого LLM-шлюза.
AIHUMMER_OPENAI_API_KEY
Ключ для OpenAI-совместимого провайдера.
AIHUMMER_SUBAGENT_MAX_DEPTH
Максимальная глубина порождаемых суб-агентов.
[!NOTE]
Если модель не подключена, gateway переходит на детерминированный mock,
чтобы система всё равно работала. Платный API модели никогда не обязателен —
свободные/локальные модели и транспорт через подписку Codex/ChatGPT
полноценно поддерживаются.
Инструменты
Ключ
Назначение
SEARXNG_URL
Включает инструмент web_search (URL инстанса SearXNG).
CLOAKBROWSER_CDP_URL
Включает инструменты browser/computer (URL Chrome DevTools Protocol).
AIHUMMER_FS_ROOT
Включает filesystem_read, в песочнице под этим корнем.
AIHUMMER_DB_QUERY_DSN
Включает db_query (только чтение) к этому DSN.
AIHUMMER_CODE_EXEC
Переключает инструмент code_exec (по умолчанию выключен на общих хостах).
Конфигурация AiHummer делится на **две строго разные группы**:
1. **Bootstrap (`gateway.env`)** — то, что gateway нужно знать **до** того, как
он может прочитать базу: DSN базы данных, адреса прослушивания, каталоги
статики, мастер-ключ. Только эти ключи читаются из окружения.
2. **Каталог настроек (БД)** — все остальные параметры. Они хранятся в базе и
задаются в веб-админке (**Управление → Настройки**) или командой
[`aihummer settings set <KEY> <VALUE>`](/v1.0/reference/cli). Для этих ключей
значение в `gateway.env` **сознательно игнорируется** — даже если оно
выставлено, оно не действует.
## Модель конфигурации
`gateway.env` — **только bootstrap**. Порядок разрешения:
- **ключ Каталога настроек**: `значение из БД → встроенный default`
(окружение игнорируется);
- **bootstrap-ключ**: `только переменная окружения`.
То есть единственный источник истины для настраиваемых параметров — база данных
(веб-админка / `aihummer settings`), а окружение несёт лишь то, без чего процесс
не стартует.
Файл конфигурации для host-native установки находится по пути:
```ini
# /home/.aihummer/etc/gateway.env
AIHUMMER_DATABASE_URL=postgres://...
AIHUMMER_MASTER_KEY=base64-32-bytes
```
> [!TIP]
> Не вписывайте параметры Каталога настроек в `gateway.env` — это не даст
> эффекта. Меняйте их в веб-админке (Управление → Настройки, есть поиск) или
> через `aihummer settings set`. Часть изменений (переключатели инструментов,
> глубина суб-агентов) применяются «на горячую», другие требуют перезапуска
> сервиса.
## Bootstrap (gateway.env)
Единственные ключи, которые gateway действительно читает из окружения.
### Ядро и база данных
| Переменная | Назначение |
|---|---|
| `AIHUMMER_DATABASE_URL` | **Обязательно.** DSN Postgres. Без неё gateway работает только в режиме health-only. |
| `AIHUMMER_DB_APP_URL` | DSN ограниченной роли, активирующий Row-Level Security (для локальных установок ставится автоматически). |
| `AIHUMMER_GATEWAY_ADDR` | Публичный адрес прослушивания (по умолчанию `:8780`) — весь внешний трафик: API (`/v1/*`), пейринг, WS/SSE, входящие вебхуки, прокси приложения/pocket и health-пробы. |
| `AIHUMMER_WEBUI_ADDR` | Приватный адрес прослушивания админ-Web UI (по умолчанию `:8781`), раздаётся по корневому пути `/`; в идеале привязан к внутреннему интерфейсу. Установите `0`, чтобы отключить. |
| `AIHUMMER_DEFAULT_WORKSPACE_ID` | Включает диспетчер входящих и workspace по умолчанию для виджета. |
| `AIHUMMER_HOME_ROOT` | Корень установки (обычно выводится из пути бинарника); привязывает каталоги admin-ui/blob/установщика и файлы ключей. |
| `AIHUMMER_BLOB_DIR` | Включает сервис медиа/файлов (каталог blob-хранилища). Здесь же хранятся **приватные (side-loaded) артефакты плагинов** под ссылками `blob:`, которые резолвит deployer. |
| `AIHUMMER_ADMIN_UI_DIR` | Отдаёт админ-SPA по `/admin/`. |
| `AIHUMMER_WIDGET_DIR` | Отдаёт веб-виджет по `/widget/`. |
### Секреты и инфраструктура
| Переменная | Назначение |
|---|---|
| `AIHUMMER_MASTER_KEY` | 32 байта в base64; включает шифрование секретов, vault и BYOK. |
| `AIHUMMER_MEDIA_TOKEN_SECRET` | Сохраняет валидность подписанных URL для скачивания между перезапусками. |
| `AIHUMMER_NATS_URL` | Опциональная шина NATS для доставки. |
| `AIHUMMER_OTEL_ENDPOINT` | OTLP-эндпоинт для push трейсов/метрик. |
| `AIHUMMER_DOWNLOAD_BASE_URL` | Базовый URL артефактов релизов (источник самообновления). |
> [!WARNING]
> Наблюдаемость работает **только по push-модели OTLP**. AiHummer **не**
> предоставляет эндпоинт Prometheus `/metrics` или `/debug/pprof`. Направьте
> `AIHUMMER_OTEL_ENDPOINT` на ваш коллектор.
Key-gated каналы установки (alfa/beta/dev) дополнительно читают
`AIHUMMER_CHANNEL_KEY` / `AIHUMMER_RELEASE_TOKEN` **на этапе установки**.
## Каталог настроек (БД — веб-админка или `aihummer settings`)
Все ключи ниже живут в базе. Задавайте их в веб-админке
(**Управление → Настройки**) или так:
```bash
aihummer settings set AIHUMMER_LLM_PROVIDER openai
```
Значение такого ключа в `gateway.env` **игнорируется**.
### Безопасность
| Ключ | Назначение |
|---|---|
| `AIHUMMER_APPROVAL_TOOLS` | Инструменты, требующие одобрения человеком перед выполнением. |
| `AIHUMMER_AIRGAPPED` | `1` блокирует управляемый моделью публичный egress (air-gapped режим). |
| `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 и pairing](/v1.0/api/webhooks-scim-pairing).
### LLM и модели
| Ключ | Назначение |
|---|---|
| `AIHUMMER_LLM_PROVIDER` | Используемый провайдер модели. |
| `AIHUMMER_LLM_MODEL` | Имя модели. |
| `AIHUMMER_LLM_GATEWAY_URL` | Эндпоинт OpenAI-совместимого LLM-шлюза. |
| `AIHUMMER_OPENAI_API_KEY` | Ключ для OpenAI-совместимого провайдера. |
| `AIHUMMER_SUBAGENT_MAX_DEPTH` | Максимальная глубина порождаемых суб-агентов. |
> [!NOTE]
> Если модель не подключена, gateway переходит на **детерминированный mock**,
> чтобы система всё равно работала. Платный API модели никогда не обязателен —
> свободные/локальные модели и транспорт через подписку Codex/ChatGPT
> полноценно поддерживаются.
### Инструменты
| Ключ | Назначение |
|---|---|
| `SEARXNG_URL` | Включает инструмент `web_search` (URL инстанса SearXNG). |
| `CLOAKBROWSER_CDP_URL` | Включает инструменты `browser`/`computer` (URL Chrome DevTools Protocol). |
| `AIHUMMER_FS_ROOT` | Включает `filesystem_read`, в песочнице под этим корнем. |
| `AIHUMMER_DB_QUERY_DSN` | Включает `db_query` (только чтение) к этому DSN. |
| `AIHUMMER_CODE_EXEC` | Переключает инструмент `code_exec` (по умолчанию выключен на общих хостах). |
Полный [Каталог инструментов](/v1.0/reference/tools-catalog) описывает, что
делает каждый инструмент.
### Голос и сайдкары
| Ключ | Назначение |
|---|---|
| `AIHUMMER_STT_URL` | URL сайдкара speech-to-text (заполняется установщиком). |
| `AIHUMMER_TTS_URL` | URL сайдкара text-to-speech (заполняется установщиком). |
| `AIHUMMER_VIDEO_URL` | URL сайдкара понимания видео. |
Сайдкары — это отдельные HTTP-сервисы; gateway обращается к ним по URL.
### Векторы и эмбеддинги
| Ключ | Назначение |
|---|---|
| `AIHUMMER_QDRANT_URL` | Реальное векторное хранилище (Qdrant). Отсутствует → in-memory хранилище. |
| `AIHUMMER_EMBEDDER_URL` | Реальный сервис эмбеддингов. Отсутствует → hash-эмбеддер. |
### Обновления
| Ключ | Назначение |
|---|---|
| `AIHUMMER_UPDATE_CHANNEL` | Канал релизов для отслеживания. |
| `AIHUMMER_AUTO_UPDATE` | Режим обновления: `off`, `check` или `apply`. |
### Протокольные поверхности (опционально)
| Ключ | Назначение |
|---|---|
| `AIHUMMER_MCP_PUBLISH` | `1` включает внешний MCP-сервер по `POST /v1/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, неподписанные →
блок) описана в [Установке и обновлениях](/v1.0/marketplace/install-updates#модель-доверия-и-запиненный-ключ).
## Куда дальше
- Какие инструменты включает каждый ключ: [Каталог инструментов](/v1.0/reference/tools-catalog).
- Ежедневное управление инстансом: [Справочник CLI](/v1.0/reference/cli).
