Configuración — AiHummer Documentos

AiHummer se configura a través de un catálogo de configuraciones, no un montón de variables de entorno. gateway.env es solo bootstrap: el DSN de la base de datos, direcciones/puertos de escucha, la clave maestra y cosas por el estilo. Todas las demás claves viven en la base de datos y se cambian desde la interfaz de administración web en tiempo de ejecución o con el aihummer settings CLI. La regla guía es simple: todo lo que se puede ajustar es configurable en la interfaz web — no solo de entorno, y no codificado de forma rígida.

El orden de resolución

Cada configuración del catálogo se resuelve de la misma manera, la primera coincidencia gana:

Base de datos — un valor establecido a través de la interfaz de administración o aihummer settings set.
predeterminada — el predeterminado incorporado que se envía con la versión.

El medio ambiente es deliberadamente no forma parte de esta cadena: para claves de catálogo y AIHUMMER_* variable en gateway.env es ignorado, incluso si está configurado. Eso da a cada ajuste exactamente una fuente de verdad: la base de datos, de modo que un valor de la interfaz de usuario nunca puede ser silenciosamente eclipsado por una línea olvidada en un archivo env.

[!NOTE] Para cambiar el comportamiento en producción no se editan los archivos de configuración — se cambia el configuración en la interfaz de administración (Gestión → Configuración, una página buscable) o ejecutar aihummer settings set <KEY> <VALUE> (get / list leer), y toma efecto para ese espacio de trabajo. El instalador en sí mismo siembra valores iniciales del catálogo en la base de datos a través de aihummer settings set.

Caliente vs reinicio requerido

Cómo afecta un cambio de configuración depende de la tecla:

Comportamiento	Ejemplos	Cuando se aplica
Caliente	habilitación de herramientas, profundidad máxima del subagente	Releer en tiempo de ejecución, sin reiniciar
Reinicio requerido	dirección de escucha, cableado de ciertos servicios	Aplicado en el próximo reinicio de la puerta de enlace

Las teclas rápidas se vuelven a leer en vivo, por lo que cambiar una herramienta o ajustar subagent-depth entra en vigor en el siguiente turno. Algunas claves estructurales sólo entran en vigor después de un reinicio; la interfaz de administrador indica cuál es cuál.

Las variables de Bootstrap permanecen solo en el entorno

Algunas variables deben estar presentes en el entorno porque se necesitan antes de que exista el catálogo de configuraciones (y la base de datos de la que se lee). Estas arranque las variables son solo del entorno y no se muestran en la interfaz de administración:

Variable	Por qué es bootstrap
`AIHUMMER_DATABASE_URL`	La base de datos debe existir antes de que se pueda leer cualquier configuración respaldada por la base de datos.
`AIHUMMER_DB_APP_URL`	DSN restringido que activa RLS.
`AIHUMMER_MASTER_KEY`	base64-32 bytes; desbloquea secretos en reposo / bóveda / BYOK.
`AIHUMMER_GATEWAY_ADDR`	Dirección pública de escucha (predeterminado `:8780`) — API, emparejamiento, WS/SSE, entrante y el proxy de la aplicación/bolsillo.
`AIHUMMER_WEBUI_ADDR`	Dirección de escucha de la interfaz web de administración privada (predeterminada `:8781`), servido en la raíz `/`; configurado en `0` desactivar.
`AIHUMMER_BLOB_DIR`	Ruta del sistema de archivos del directorio blob/media — necesaria al iniciar.
`AIHUMMER_OIDC_ISSUER`	Protege `/v1/admin/*` antes de que se confíe en la interfaz de usuario.

El cableado de operaciones como el endpoint OTLP de telemetría entra en la misma categoría de arranque. Cualquier cosa que no esté en esta lista corta es una clave de catálogo: vive en la base de datos, y el env se ignora para ella.

[!WARNING] Mantener AIHUMMER_MASTER_KEY seguro y respaldado por separado desde tu base de datos respaldo. Descifra la bóveda de credenciales; si lo pierdes, los secretos encriptados no se puede recuperar.

El archivo de configuración

Para instalaciones nativas en el host, el entorno de arranque vive en un solo archivo que la unidad systemd carga:

~/.aihummer/etc/gateway.env

Edita este archivo solo para valores de bootstrap, luego reinicie el servicio de la puerta de enlace para aplicar los cambios:

# ~/.aihummer/etc/gateway.env (excerpt)
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

Todo lo que va más allá de estas claves de arranque — agentes, herramientas, modo de memoria, estrategias de razonamiento, presupuestos, guías y el resto — se gestiona desde la configuración de la interfaz de administración (o a través de aihummer settings), no de este archivo: env se ignora para esas claves.

Cableado de capacidades opcionales

Muchas funciones están desactivadas hasta que las apuntes a un servicio de respaldo. Todas estas claves son configuraciones del catálogo (viven en la base de datos): configúralas en la interfaz de administración (Gestión → Configuración) o con la CLI; colocándolos en gateway.env no hace nada: el env se ignora para ellos. Para los sidecars instalados desde el paquete (STT/TTS, etc.), el instalador inserta los valores en la base de datos por sí mismo.

# Wire a real model (unset → deterministic 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

# Enable tools by pointing at their backends

# Voice sidecars (STT/TTS auto-configured by the installer)
aihummer settings set AIHUMMER_STT_URL http://localhost:8001
aihummer settings set AIHUMMER_TTS_URL http://localhost:8002

# Real vector store + embedder (example URLs; the embedder is installed with
# --with-embedder, otherwise memory uses the lexical fallback)
aihummer settings set AIHUMMER_QDRANT_URL http://localhost:6333
aihummer settings set AIHUMMER_EMBEDDER_URL http://localhost:8080

[!TIP] Nunca se requiere un modelo real. Sin AIHUMMER_LLM_* conectado, llegan respuestas de un simulacro determinista; AiHummer también funciona en OpenAI compatible gratuito/local puntos finales y un transporte de suscripción Codex/ChatGPT, con BYOK opcional.

Notificaciones

La interfaz de administrador Notificaciones la página (bajo “Control”) es la bandeja de entrada de eventos de la instancia (inicio de sesión del administrador, actualización disponible/aplicada, caída o recuperación del sidecar, y así sucesivamente) con filtros por categoría, gravedad y no leídos. Junto a ella se encuentra una matriz de categoría × canal de entrega: para cada categoría de evento que habilites interfaz web, correo electrónico, telegrama y empujar canales. Los avisos de la interfaz web se entregan localmente; Telegram se vincula con el botón “Vincular Telegram” (enlace profundo), el correo electrónico se activa una vez que se verifica la dirección de soporte, y las notificaciones push llegan a la aplicación móvil. Los eventos críticos no se pueden silenciar en el canal de la interfaz web.

¿A dónde vamos ahora?

Restringir el acceso de administrador: Primer inicio de sesión.
Ver dónde viven los archivos: Instalación.
Verifica los requisitos previos: Requisitos.