Variables de Entorno

Cada anulación de variable de entorno del operador utiliza una única gramática de réplica de esquema. El final de una variable de entorno ZEROCLAW_* es la ruta de propiedad con puntos que zeroclaw config set acepta, donde cada __ (doble guion bajo) separa los segmentos de la ruta y cada _ simple es o bien un conector snake-case dentro del nombre de un campo (api_key → api-key en set_prop) o un carácter literal dentro de una clave de alias.

ZEROCLAW_<dotted_path_with_double_underscores>=<value>

Ejemplos

# Inyectar una credencial de alias de familia tipada
ZEROCLAW_providers__models__anthropic__home__api_key=sk-ant-...

# Establecer un modelo en un alias de OpenRouter no predeterminado (un alias con guion bajo es válido)
ZEROCLAW_providers__models__openrouter__prod_v2__model=anthropic/claude-sonnet-4-6
ZEROCLAW_providers__models__openrouter__prod_v2__api_key=sk-or-...

# Activar/desactivar y configurar un canal
ZEROCLAW_channels__matrix__home__enabled=true
ZEROCLAW_channels__matrix__home__homeserver=https://matrix.example.org

# Anular parámetros de ejecución de la puerta de enlace
ZEROCLAW_gateway__request_timeout_secs=120
ZEROCLAW_gateway__long_running_request_timeout_secs=900

# Apuntar el gateway a un panel web compilado (ruta absoluta; sin ~ / $HOME)
ZEROCLAW_gateway__web_dist_dir=/srv/zeroclaw/web/dist

# Inyectar secretos de firma de webhook
ZEROCLAW_channels__whatsapp__home__app_secret=...
ZEROCLAW_channels__linq__home__signing_secret=...
ZEROCLAW_channels__nextcloud_talk__home__webhook_secret=...

# Inyectar conexión del backend de memoria Qdrant
ZEROCLAW_storage__qdrant__home__url=https://qdrant.example.com
ZEROCLAW_storage__qdrant__home__collection=zeroclaw
ZEROCLAW_storage__qdrant__home__api_key=...

El mapeo del nombre de la variable de entorno a la ruta TOML es mecánico:

Los segmentos <alias> anteriores (home, prod_v2) son elegidos por el operador; sustitúyalos por los nombres que realmente use su configuración.

Bootstrap (cola en mayúsculas)

Estas variables de entorno deciden dónde residen el archivo de configuración y los datos de la instancia, antes de que exista cualquier Config. Mantienen su forma en MAYÚSCULAS para que la regla de mayúsculas/minúsculas las distinga de la superficie espejo del esquema. Se resuelven en el orden ZEROCLAW_CONFIG_DIR > ZEROCLAW_DATA_DIR > ZEROCLAW_WORKSPACE (obsoleta):

ZEROCLAW_CONFIG_DIR=/etc/zeroclaw         # ubicación del archivo de configuración (tiene precedencia)
ZEROCLAW_DATA_DIR=/srv/zeroclaw           # directorio de datos de la instancia (canónico)
ZEROCLAW_WORKSPACE=/srv/zeroclaw          # OBSOLETO — alias de ZEROCLAW_DATA_DIR

La ubicación del panel web del gateway se configura mediante el formato estándar de espejo de esquema ZEROCLAW_gateway__web_dist_dir, consulte Panel web (web_dist_dir) para la referencia completa de la configuración.

Límite de persistencia

Los valores aplicados mediante variables de entorno ZEROCLAW_* se cargan en el Config en memoria en el momento de la carga y nunca se conservan en disco. zeroclaw config save enmascara las rutas sobrescritas por variables de entorno, restaurándolas a sus valores en disco o predeterminados antes del cifrado. Se emite una línea de registro WARN cada vez que una ruta de tipo secreto (por ejemplo, una clave de API) se sobrescribe mediante una variable de entorno, de modo que los registros de auditoría hagan visible la inyección.

Gramática de alias

Los alias (los segmentos <alias> en los ejemplos anteriores, home, prod_v2, mymatrixalias, etc.) siguen estas reglas:

1. Letras ASCII en minúscula, dígitos y guiones bajos simples.
2. Debe comenzar Y terminar con una letra o un dígito (sin guion bajo al inicio ni al final).
3. Ninguna subcadena __ (reservada como separador de rutas en la gramática de variables de entorno).
4. Sin guion (no permitido en identificadores de variables de entorno).
5. Sin mayúsculas (entraría en conflicto con los nombres de bootstrap).
6. 1–63 caracteres.

prod_v2 es un único token de alias; home__api_key se analiza como dos segmentos (alias home, campo api_key). Las configuraciones con alias no conformes producen un error en tiempo de carga que nombra el alias infractor.

Errores

Los nombres ZEROCLAW_<lowercase_*> que no se pueden resolver (errores tipográficos, rutas que no coinciden con ninguna prop en el esquema) cancelan el inicio con un error grave que nombra la variable de entorno problemática. Los nombres de variables de entorno sin el prefijo ZEROCLAW_ no son leídos por esta capa de sobrescritura.

Visibilidad

El estado de sobreescritura se muestra dondequiera que se renderice la configuración, con un indicador 💉 que marca los campos sobreescritos por variables de entorno:

1. zeroclaw config list: la leyenda 💉 env-overridden 🔒 secret se imprime una vez en la parte superior; las filas de los campos sobrescritos por variables de entorno llevan el prefijo 💉.
2. Editor de Web Config: cada ListEntry lleva un bool is_env_overridden. Las filas de campos sobrescritos por variables de entorno muestran la insignia 💉 y una advertencia persistente “Edits here won’t take effect, overridden by ZEROCLAW_…” para que los operadores vean la sobrescritura sin tener que intentar una edición.
3. Onboarding de CLI/TUI: prompt_field omite los campos sobrescritos por variables de entorno e imprime una nota 💉 de tres líneas (el nombre de la variable de entorno, la ruta TOML y un aviso de omisión) que se borra al navegar hacia adelante o hacia atrás. A los operadores no se les pide que escriban un valor que ya han inyectado.
4. Desfase de recarga: GET /api/config/drift, GET /api/config/list y el banner de recarga excluyen de la computación del desfase las rutas sobrescritas por variables de entorno. Como estos valores viven solo en memoria y nunca se escriben en disco, de otro modo se informarían como desfase permanente que ninguna edición del archivo de configuración podría reconciliar. Excluirlos mantiene la salida del desfase limitada a diferencias que un operador puede resolver realmente editando la configuración almacenada.
5. Programático: Config::prop_is_env_overridden(path) -> bool es una búsqueda O(1) en un HashSet. Punto de integración aquí para cualquier capa de renderizado personalizada.

Derivar nombres de variables de entorno a partir de tu configuración

Tres pasos mecánicos para derivar un nombre de variable de entorno a partir de cualquier clave TOML:

1. Anteponga ZEROCLAW_ a la ruta. La ruta de configuración con puntos es la fuente de verdad; encuentre el campo mediante zeroclaw config schema.
2. Reemplaza . con __ (doble guion bajo, el separador de rutas).
3. El nombre del campo permanece igual (snake_case). Los alias permanecen igual. Nada más se transforma.

Por ejemplo, [providers.models.anthropic.home] api_key = "sk-..." reside en la ruta con puntos providers.models.anthropic.home.api_key. Aplica las tres reglas y la variable de entorno será ZEROCLAW_providers__models__anthropic__home__api_key=sk-.... El mismo mapeo mecánico se aplica a cualquier campo en cualquier sección.

Puente de variables de entorno predeterminadas del ecosistema

La gramática schema-mirror es la forma canónica de inyectar valores, pero ANTHROPIC_API_KEY / OPENROUTER_API_KEY / QDRANT_URL / etc. siguen siendo nombres comunes en los archivos .env y las configuraciones de CI. Las expansiones de shell de una línea apuntan un nombre schema-mirror al valor predeterminado del ecosistema:

# POSIX (bash, zsh, sh) — añadir en ~/.bashrc / ~/.zshrc / .env / Dockerfile
export ZEROCLAW_providers__models__anthropic__home__api_key=$ANTHROPIC_API_KEY
export ZEROCLAW_providers__models__openai__home__api_key=$OPENAI_API_KEY
export ZEROCLAW_providers__models__openrouter__home__api_key="$OPENROUTER_API_KEY"
export ZEROCLAW_providers__models__nearai__tee__api_key="$NEARAI_API_KEY"
export ZEROCLAW_providers__models__zerorouter__gateway__api_key="$ZEROROUTER_API_KEY"
export ZEROCLAW_storage__qdrant__home__url="$QDRANT_URL"
export ZEROCLAW_storage__qdrant__home__api_key="$QDRANT_API_KEY"
export ZEROCLAW_gateway__request_timeout_secs=$GATEWAY_TIMEOUT_SECS

# PowerShell — drop into $PROFILE
$env:ZEROCLAW_providers__models__anthropic__home__api_key = $env:ANTHROPIC_API_KEY
$env:ZEROCLAW_providers__models__openai__home__api_key = $env:OPENAI_API_KEY
$env:ZEROCLAW_providers__models__nearai__tee__api_key = $env:NEARAI_API_KEY
$env:ZEROCLAW_storage__qdrant__home__url = $env:QDRANT_URL

Sustituye el nombre del alias en lugar de home para que coincida con tu configuración. Para múltiples alias en la misma familia, repite la línea con cada alias.

Estas líneas son puentes de shell hacia configuración tipada, no una regla general de que los constructores lean variables de entorno nativas del proveedor. El código en tiempo de ejecución debe recibir el valor resuelto de Config, a menos que la familia de integración documente explícitamente un puente de entorno nativo.

Campos de OAuth y ruta de CLI

Unos pocos campos viven como campos de esquema, accesibles a través del mapeo estándar:

1. Flujo de actualización OAuth de MiniMax: [providers.models.minimax.<alias>] oauth_refresh_token = "..." (con oauth_client_id opcional); la selección de región es el enum tipado endpoint (cn / intl). El runtime intercambia el token de actualización por un token de acceso de corta duración en el momento de la construcción del proveedor.
2. Flujo de actualización OAuth de Qwen: [providers.models.qwen.<alias>] oauth_refresh_token = "..." (con oauth_client_id y oauth_resource_url opcionales).
3. Gemini OAuth: [providers.models.gemini.<alias>] oauth_client_id y oauth_client_secret; el parámetro opcional oauth_project fija un ID de proyecto de GCP de Code Assist.
4. Configuración de procesos de KiloCLI / Gemini CLI / Grok Build CLI: [providers.models.kilocli.<alias>] binary_path, [providers.models.gemini_cli.<alias>] binary_path, y los campos de [providers.models.grok_cli.<alias>]: binary_path, working_directory absoluto obligatorio, extra_args opcional y max_acp_stdout_bytes. Los alias de Grok Build también pueden enumerar nombres de variables de entorno en env_passthrough (credenciales de la herramienta y el puente de autenticación opcional XAI_API_KEY); los valores se resuelven solo cuando se inicia el proceso hijo y no se almacenan en la configuración. La autenticación usa la caché de inicio de sesión de la CLI de forma predeterminada. El nombre exacto XAI_API_KEY es el puente nativo documentado para la autenticación mediante clave de API cuando se incluye explícitamente; se rechazan otros nombres XAI_* y todos los nombres GROK_*.
5. Claves de transcripción / TTS: [transcription].api_key, [providers.tts.openai.<alias>].api_key, [providers.tts.elevenlabs.<alias>].api_key, [providers.tts.google.<alias>].api_key.
6. Notion / WhatsApp: [notion].api_key, [channels.whatsapp.<alias>].ws_url (sustitución de WebSocket para pruebas/proxy).