Variables de entorno

La configuración de AiHummer se divide en dos grupos estrictamente diferentes:

Bootstrap (gateway.env) — lo que la puerta debe saber antes puede leer la base de datos: el DSN de la base de datos, direcciones de escucha, directorios estáticos, la llave maestra. Solo estas llaves se leen desde el entorno.
Catálogo de configuraciones (base de datos) — cada otro botón. Estos se almacenan en el base de datos y configurar en la interfaz de administración web (Gestión → Configuración) o con aihummer settings set <KEY> <VALUE>. Para estos teclas a gateway.env el valor es ignorado deliberadamente — incluso si está configurado, tiene sin efecto.

Modelo de configuración

gateway.env es solo bootstrap. Orden de resolución:

Clave del catálogo de ajustes: database value → built-in default (el entorno es ignorado);
clave de arranque: environment variable only.

Entonces, la única fuente de verdad para las perillas ajustables es la base de datos (interfaz de administración web / aihummer settings); el entorno lleva solo lo que el proceso necesita para comenzar.

El archivo de configuración para una instalación nativa en el host se encuentra en:

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

[!TIP] No coloque los mandos del catálogo de Configuración gateway.env — no tiene efecto. Cambiar ellos en la interfaz de administración web (Gestión → Configuración, tiene búsqueda) o vía aihummer settings set. Algunos cambios (como los interruptores de herramientas y subagentes profundidad) aplicar caliente; otros requieren un reinicio del servicio.

Bootstrap (gateway.env)

Las únicas llaves que la pasarela realmente lee del entorno.

Núcleo y base de datos

Variable	Propósito
`AIHUMMER_DATABASE_URL`	Requerido. DSN de Postgres. Sin él, la pasarela funciona solo en modo de salud.
`AIHUMMER_DB_APP_URL`	DSN de rol restringido que activa la Seguridad a Nivel de Fila (configurado automáticamente para instalaciones locales).
`AIHUMMER_GATEWAY_ADDR`	Dirección pública de escucha (predeterminado `:8780`) — todo el tráfico externo: API (`/v1/*`), emparejamiento, WS/SSE, webhooks entrantes, el proxy de la aplicación/bolsillo y sondas de estado.
`AIHUMMER_WEBUI_ADDR`	Dirección de escucha de la interfaz web de administración privada (predeterminada `:8781`), servido en la ruta raíz `/`; idealmente vinculado a una interfaz solo interna. Configurado para `0` desactivar.
`AIHUMMER_DEFAULT_WORKSPACE_ID`	Selecciona el espacio de trabajo predeterminado para las integraciones entrantes configuradas.
`AIHUMMER_HOME_ROOT`	Instale la raíz (normalmente derivada de la ruta binaria); ancla los directorios admin-ui/blob/installer y los archivos clave.
`AIHUMMER_BLOB_DIR`	Habilita el servicio de medios/archivos (directorio de almacenamiento de blobs). También almacena artefactos de plugin privados (cargados lateralmente) debajo `blob:` referencias que el implementador resuelve.
`AIHUMMER_ADMIN_UI_DIR`	Sirve la SPA de administración en `/admin/`.

Secretos e infraestructura

Variable	Propósito
`AIHUMMER_MASTER_KEY`	32 bytes codificados en base64; habilita secretos en reposo, la bóveda y BYOK.
`AIHUMMER_MEDIA_TOKEN_SECRET`	Mantiene válidas las URL de descarga firmadas incluso después de reinicios.
`AIHUMMER_OTEL_ENDPOINT`	Punto de enlace OTLP para el envío de rastros/métricas.
`AIHUMMER_DOWNLOAD_BASE_URL`	URL base para los artefactos de la versión (fuente de autoactualización).

[!WARNING] La observabilidad es Solo push OTLP. AiHummer lo hace no exponer un Prometeo /metrics punto final o /debug/pprof. Punto AIHUMMER_OTEL_ENDPOINT en tu colector en su lugar.

Catálogo de configuraciones (base de datos — interfaz de administración web o `aihummer settings`)

Cada clave a continuación está en la base de datos. Configúrela en la interfaz de administración web (Gestión → Configuración) o así:

aihummer settings set AIHUMMER_LLM_PROVIDER openai

A gateway.env valor para tal clave es ignorado.

Seguridad

Llave	Propósito
`AIHUMMER_APPROVAL_TOOLS`	Herramientas que requieren la aprobación de un humano en el bucle antes de ejecutarse.
`AIHUMMER_AIRGAPPED`	`1` bloquea la salida pública controlada por el modelo (modo air-gapped).
`AIHUMMER_AUDIT_RETENTION_DAYS`	Ventana de retención para el registro de auditoría de administración.
`AIHUMMER_INBOUND_SECRET`	Secreto compartido HMAC para conector → puerta de enlace `/v1/inbound/*` llamadas.

Autenticación y SSO

Llave	Propósito
`AIHUMMER_OIDC_ISSUER`	Protege `/v1/admin/*`. Sin ello (y sin LDAP/SAML) el administrador confía en los encabezados de desarrollo: nunca expongas una instancia así.

LDAP/AD y SAML están configurados junto con OIDC para el inicio de sesión empresarial; SCIM proporciona aprovisionamiento automático de usuarios. Ver Webhooks, SCIM y emparejamiento.

LLM y modelos

Llave	Propósito
`AIHUMMER_LLM_PROVIDER`	Proveedor de modelo a utilizar.
`AIHUMMER_LLM_MODEL`	Nombre del modelo.
`AIHUMMER_LLM_GATEWAY_URL`	URL base de un gateway/punto de acceso compatible con OpenAI (el `AIHUMMER_LLM_*` camino; distinto del nativo `AIHUMMER_OPENAI_BASE_URL`). Ver BYOK y proveedores.
`AIHUMMER_OPENAI_API_KEY`	Clave de API para un proveedor compatible con OpenAI.
`AIHUMMER_SUBAGENT_MAX_DEPTH`	Profundidad máxima de los subagentes generados.

[!NOTE] Si ningún modelo está conectado, la puerta de enlace vuelve a simulación determinista así que el el sistema sigue funcionando. Nunca se requiere una API de modelo de pago: modelos gratuitos/locales y un El transporte de suscripción Codex/ChatGPT es de primera clase.

Herramientas

Llave	Propósito
`AIHUMMER_FS_ROOT`	Habilita `filesystem_read`, aislado bajo esta raíz.
`AIHUMMER_DB_QUERY_DSN`	Habilita `db_query` (solo lectura) contra este DSN.
`AIHUMMER_CODE_EXEC`	Alterna el `code_exec` herramienta (desactivada por defecto en alojamientos compartidos).

La búsqueda web y el navegador los gestiona el instalador: se instalan de fábrica, se desactivan con --no-search / --no-browser y se apuntan a una instancia existente con --external-search=URL / --external-browser=URL — no hay ajustes de operador para ellos.

Ver el completo Catálogo de herramientas para lo que hace cada herramienta.

Voz y sidecars

Llave	Propósito
`AIHUMMER_STT_URL`	URL de transcripción de voz a texto (provista por el instalador).
`AIHUMMER_TTS_URL`	URL del asistente de texto a voz (inicializado por el instalador).
`AIHUMMER_VIDEO_URL`	URL del accesorio lateral de comprensión de video.

Los sidecars son servicios HTTP separados; la puerta de enlace los alcanza mediante URL.

Vectores y representaciones incrustadas

Llave	Propósito
`AIHUMMER_QDRANT_URL`	Almacén de vectores real (Qdrant). Ausente → almacén en memoria.
`AIHUMMER_EMBEDDER_URL`	Servicio de incrustación real. Ausente → incrustador de hash.

Superficies del protocolo (opción de suscripción)

Llave	Propósito
`AIHUMMER_MCP_PUBLISH`	Exactamente `1` abre el servidor MCP externo en `POST /v1/mcp`. Por sí solo no exporta ninguna herramienta.
`AIHUMMER_MCP_EXPORT_TOOLS`	Nombres exactos de herramientas separados por comas que verá el cliente MCP. Vacío (valor por defecto) = CERO herramientas exportadas.
`AIHUMMER_A2A_PUBLISH`	`1` habilita la superficie A2A (`/.well-known/agent.json`, `/a2a/message`).

Solo construcciones de desarrollo

Variable	Propósito
`AIHUMMER_PLUGIN_PUBKEY`	Una clave pública adicional de confianza (ed25519 en base64) para verificar firmas de complementos. Solo compilaciones de desarrollo — ignorado en compilaciones de lanzamiento (la clave del registro está fijada en el binario).
`AIHUMMER_PLUGIN_DEV_UNSIGNED`	`1` permite instalar sin signo complementos. Solo para compilaciones de desarrollo: se ignora en compilaciones de lanzamiento. Nunca en una instancia accesible externamente.

[!WARNING] En las compilaciones de lanzamiento, la raíz de confianza del complemento es integrado en el binario y no puede ser anulado por el entorno o la configuración: esto es una protección contra manipulaciones garantía.

El modelo de confianza (oficial → clave fijada, privada → almacén de confianza, no firmada → bloqueada) se describe en Instalar y actualizar.

¿A dónde vamos ahora?

Vea qué herramientas desbloquea cada llave: Catálogo de herramientas.
Operar la instancia día a día: Referencia de CLI.