Ciclo de vida de la configuración

La configuración es tanto una interfaz de operador como un contrato en tiempo de ejecución. Trátala como estado con un propietario claro, no como ajustes sueltos copiados en cualquier subsistema que los necesite.

La fuente canónica es zeroclaw_config::schema::Config, cargada desde config.toml. Las superficies de configuración visibles para el usuario, la referencia de configuración generada, el editor de configuración de la gateway, las sobrescrituras por variables de entorno, zeroclaw config set, zeroclaw config patch, Quickstart y los métodos RPC de configuración se enrutan todos a través de ese mismo esquema tipado.

Para el orden de compilación, las reglas de salida con seguimiento y las comprobaciones de deriva que convierten el esquema tipado en la referencia de configuración, consulta Canalización de documentación generada.

Qué posee qué

No edites manualmente la referencia de configuración generada. Si un campo, enum, sección de alias, marcador secreto o descripción está mal allí, corrige el esquema o el generador y vuelve a generar la referencia.

Orden de carga

La carga de la configuración tiene varias fases distintas:

1. Resuelve la raíz de instalación a partir de las variables de entorno de bootstrap. Esto ocurre antes de que exista cualquier Config, por lo que los nombres de bootstrap mantienen su forma en mayúsculas y no usan la gramática del espejo de esquema.
2. Lee config.toml, ejecuta la migración del esquema en memoria, descifra los secretos configurados y registra cualquier sección crítica de seguridad mal formada como seguridad degradada.
3. Aplica las anulaciones de schema-mirror a la configuración en memoria. En las variables de entorno, __ se asigna a ., así que ZEROCLAW_providers__models__openai__api_key apunta a providers.models.openai.api_key.
4. Validar y advertir sin bloquear al operador fuera del editor de la puerta de enlace.

En una instalación nueva, los valores predeterminados se guardan antes de que se apliquen las sustituciones de entorno. Esto mantiene los secretos inyectados por el entorno y los valores locales de CI fuera del archivo nuevo.

Las anulaciones de entorno no se guardan

Las variables de entorno de schema-mirror son inyecciones en tiempo de ejecución. Se aplican al Config en memoria al cargarse y se registran en env_overridden_paths para que la CLI, el panel de control y quickstart puedan mostrar el indicador de anulación.

Al guardar, debe enmascarar estas rutas para devolverlas a su valor de disco anterior al reemplazo o a su valor predeterminado antes del cifrado. Esto es especialmente importante para los secretos: si un operador tiene una clave de API cifrada en el disco y arranca temporalmente con una anulación de entorno para la misma ruta, un guardado de configuración no relacionado no debe reemplazar la credencial real con el valor del entorno ni con una cadena de visualización enmascarada.

Revisa los cambios de configuración con esta invariante en mente:

• ZEROCLAW_* los valores de schema-mirror afectan al proceso en ejecución después de la carga.
• No se convierten en configuración duradera.
• Las rutas guardadas deben preservar los secretos cifrados y las referencias externas a secretos, a menos que se haya editado intencionalmente la misma ruta.

Las entradas de credenciales permanecen tipadas

Los valores en tiempo de ejecución similares a credenciales siguen siendo valores de configuración. Las claves de API, los tokens de OAuth, las URL de los endpoints y otras credenciales de proveedores/canales deben pasar por el esquema de configuración tipado, la gestión de secretos de configuración o las sobrescrituras ZEROCLAW_* reflejadas por el esquema antes de que un constructor en tiempo de ejecución las reciba.

No agregue lecturas ad-hoc de std::env::var("PROVIDER_API_KEY") dentro de los constructores de provider, channel, tool, transcription, TTS, memory o gateway. Eso crea una segunda fuente de credenciales fuera de Config, omite la visibilidad de env-override y puede provocar que el comportamiento de CLI, gateway, RPC/TUI, quickstart y reload sea inconsistente.

Si ZeroClaw admite intencionadamente un puente nativo de variables de entorno para una familia de integraciones, documenta ese puente en el límite de integración y asígnalo al mismo valor de configuración tipado antes de la construcción. De lo contrario, los nombres de shell predeterminados del ecosistema, como ANTHROPIC_API_KEY, OPENROUTER_API_KEY o QDRANT_URL, deben transferirse mediante un puente a la variable ZEROCLAW_* correspondiente que refleja el esquema; consulta Variables de entorno.

Rutas sucias y escrituras incrementales

La mayoría de las superficies de edición usan Config::mark_dirty() más save_dirty(), no una reescritura completa. save_dirty() escribe solo las rutas punteadas cambiadas, conserva las entradas no marcadas como dirty y los comentarios cuando es posible, registra el schema_version actual y escribe mediante un reemplazo atómico de archivo temporal.

Esa ruta también es responsable de las secciones de clave de mapa. Crear un alias como un proveedor de modelos, un servidor MCP, un paquete de habilidades o un paquete de conocimientos debe modificar la sección correcta para que el alias sobreviva a un guardado y recarga. Una edición de configuración que solo actualiza el estado del panel en memoria no está completa.

Al revisar una escritura de configuración, verifica que:

• la ruta editada se marca como sucia antes de la persistencia;
• map-key crea, renombra y elimina ensucian la sección padre o la clave natural;
• las rutas secretas y las rutas anuladas por env conservan su comportamiento de enmascaramiento al guardar;
• schema_version permanece actual después de escrituras incrementales;
• el valor cambiado persiste tras save_dirty() seguido de una recarga.

Guardado vs aplicado

Un guardado exitoso significa que el archivo cambió. No siempre significa que todos los componentes en tiempo de ejecución hayan adoptado el cambio.

El daemon es el propietario del grafo del subsistema de larga duración: gateway, listeners de canal, scheduler, listener de MQTT, cableado de sesión, backend de memoria, fábricas de proveedores y cableado de costes. POST /admin/reload señala al bucle del daemon, que vuelve a leer config.toml y vuelve a instanciar esos subsistemas en el mismo proceso. El PID sigue siendo el mismo, pero los listeners se vuelven a vincular brevemente.

Las escrituras de la configuración de Gateway llaman a persist_and_swap(): guardan en disco y luego reemplazan la configuración en memoria visible para Gateway y establecen pending_reload. Esto hace que el editor de configuración refleje la escritura de inmediato, mientras que el banner de recarga le indica al operador que los canales, proveedores, el planificador u otros componentes propiedad del daemon aún pueden estar ejecutándose desde la instancia anterior del subsistema.

zeroclaw gateway start independiente no tiene supervisor de daemon. Su punto final de recarga devuelve una respuesta que requiere reinicio porque no hay un bucle externo de daemon al que señalar.

Recargar acceso

La recarga local está permitida desde loopback. La recarga remota requiere ambas cosas:

1. gateway.allow_remote_admin = true
2. emparejamiento habilitado y un token de portador emparejado válido

Optar por la administración remota mientras el emparejamiento está deshabilitado se rechaza en lugar de tratarse como acceso anónimo de recarga remota.

Las secciones de configuración mal formadas críticas para la seguridad solo pueden degradarse cuando el operador opta explícitamente por el servicio degradado. De lo contrario, el proceso se niega a servir porque la postura de seguridad restablecida a los valores predeterminados puede ser más débil de lo que pretendía el archivo.

Revertir y reparar

Las escrituras de configuración usan una sustitución atómica de archivo temporal y permisos solo para el propietario. Al reemplazar un archivo existente, el escritor crea config.toml.bak en el mismo directorio durante el reemplazo y lo elimina después de una escritura correcta. Las escrituras de Gateway también crean una instantánea del archivo previo a la escritura y lo restauran en la medida de lo posible si la persistencia falla antes de intercambiar el estado en memoria.

No existe una reversión transaccional general para un cambio de configuración válido pero no deseado una vez que se ha guardado y aplicado. Restaura el config.toml anterior desde la copia de seguridad, vuelve a editar el campo mediante la CLI o el panel de control, y luego recarga o reinicia según el límite de tiempo de ejecución indicado arriba.

Config-visible no siempre es compatible en tiempo de ejecución

Un campo puede ser visible en el esquema antes de que cada ruta en tiempo de ejecución lo consuma. Eso solo es aceptable cuando la documentación y las notas de revisión lo indican claramente.

Por ejemplo, knowledge_bundles es visible en el esquema y aparece en las APIs de las secciones de configuración. Un PR que añade o modifica una superficie así debe ser preciso sobre si solo almacena configuración, conecta el comportamiento en tiempo de ejecución o completa ambas cosas.

Al revisar una PR que toca un campo visible en el esquema pero aún no consumido en tiempo de ejecución, exige que la descripción de la PR indique si el cableado en tiempo de ejecución está diferido, fuera de alcance o completado por el mismo cambio.

Lista de verificación para revisores

Para cambios en config-schema, env-var, default o reload, pregunta:

• ¿Cuál es la fuente de verdad para el nuevo valor?
• ¿Esto está creando estado duplicado o resolviéndolo desde Config en el momento de uso?
• ¿La referencia generada proviene del código en lugar de prosa mantenida manualmente?
• ¿Las anulaciones de entorno solo se cargan en tiempo de carga y se enmascaran durante los guardados?
• ¿CLI, gateway, RPC/TUI y las superficies de inicio rápido coinciden en la ruta con puntos?
• ¿Se resuelven las credenciales a través de configuración tipada o puentes documentados que reflejan el esquema, en lugar de lecturas de variables de entorno específicas del proveedor y ad-hoc?
• ¿Una guardada persiste tras recargar el proceso, no solo en la renderización inmediata en memoria?
• ¿El PR dice si los usuarios necesitan recarga, reinicio, migración o reversión manual?
• Si el campo solo es visible en la configuración, ¿la PR evita afirmar compatibilidad en tiempo de ejecución?

Punteros de origen

• Esquema de configuración y persistencia: crates/zeroclaw-config/src/schema.rs
• Gramática de anulación de entorno: crates/zeroclaw-config/src/env_overrides.rs
• Comandos de CLI de Config: src/main.rs
• Métodos de configuración de RPC y TUI: crates/zeroclaw-runtime/src/rpc/dispatch.rs
• Ruta de inicio rápido compartida de apply: crates/zeroclaw-runtime/src/quickstart/mod.rs
• Señalización de recarga de Quickstart web: crates/zeroclaw-gateway/src/api_quickstart.rs
• API de configuración de Gateway y banner de recarga: crates/zeroclaw-gateway/src/api_config.rs
• Punto final de recarga y puerta de acceso: crates/zeroclaw-gateway/src/lib.rs
• Ayudante de autenticación bearer de Gateway: crates/zeroclaw-gateway/src/api.rs
• Pipeline de referencia generada: xtask/src/cmd/mdbook/refs.rs