Panel web (gateway.web_dist_dir)
Cuando ZeroClaw se compila con la función embedded-web, los recursos del panel integrados en el binario tienen prioridad sobre gateway.web_dist_dir y sobre las ubicaciones del sistema de archivos descritas a continuación. La resolución por sistema de archivos y el modo de solo API como alternativa se aplican cuando los recursos integrados no están disponibles.
El daemon de gateway incluye su API HTTP en el binario, pero el panel web (HTML/JS/CSS) se encuentra en disco, en un directorio web/dist/ generado por Vite. El ajuste gateway.web_dist_dir (y su anulación mediante la variable de entorno ZEROCLAW_gateway__web_dist_dir, que refleja el esquema) indica al daemon dónde está ese directorio. Si ni el ajuste ni una ubicación de respaldo conocida contienen un index.html compilado que se resuelva dentro de la raíz del panel, el gateway se inicia en modo solo API y la URL del panel devuelve un mensaje de “no disponible”.
TL;DR
sh
# Anulación equivalente de variable de entorno (solo en memoria, nunca persistida)
export ZEROCLAW_gateway__web_dist_dir=/absolute/path/to/zeroclaw/web/dist
Luego compila el bundle una vez:
sh
cargo web build
…y reinicie el daemon. El log de inicio cambia de
Web dashboard: not available — no web/dist found. Build with `cargo web build` …
a
Web dashboard: serving filesystem assets
El directorio resuelto se registra en el campo estructurado path de ese evento de registro.
Lo que hace la configuración
gateway.web_dist_dir es un Option<String> que apunta al directorio que contiene un index.html compilado. Al iniciar el gateway, el daemon:
- Lee el valor configurado (o la anulación de la variable de entorno).
- Verifica que el directorio exista y que su
index.htmlse resuelva dentro de la raíz del panel en esta máquina. - Si es así, sirve el panel desde esa ruta.
- Si no, registra una advertencia WARN (“path no tiene un
index.htmlutilizable en esta máquina; recurriendo a la detección automática”) e intenta los candidatos de detección automática indicados a continuación. - Si la detección automática tampoco encuentra nada, el gateway se ejecuta en modo solo API y
GET /devuelve un mensaje de “no disponible” que apunta de vuelta aquí.
El valor se trata como una sugerencia, no como un requisito estricto. Una ruta obsoleta (error tipográfico, ruta específica de un host copiada de otra máquina, compilación faltante) recurre a la detección automática en lugar de bloquear cada solicitud del panel.
Predeterminado: detectar orden automáticamente
Cuando gateway.web_dist_dir no está definido (o está configurado con una ruta que no contiene un index.html utilizable), el daemon busca en estas ubicaciones en orden y sirve desde la primera que contenga un index.html que se resuelva dentro de esa raíz candidata:
| # | Candidato | Cuando coincide |
|---|---|---|
| 1 | ./web/dist (relativo al CWD) | Ejecutar cargo run desde la raíz del repositorio en dev |
| 2 | <dir-of-binary>/web/dist | El binario empaquetado incluye web/dist junto a sí mismo |
| 3 | /zeroclaw-data/web/dist | Estructura estándar de Docker / volumen empaquetado |
| 4 | /usr/share/zeroclawlabs/web/dist | Instalación de paquetes AUR / del sistema |
| 5 | ${XDG_DATA_HOME:-~/.local/share}/zeroclaw/web/dist | Instalador de binarios precompilados (por usuario) |
Si estás en una de esas distribuciones y el panel de control “simplemente funciona”, no necesitas configurar gateway.web_dist_dir en absoluto, la detección automática lo encontró.
Cómo obtener un web/dist
Tienes tres opciones. Elige la que coincida con cómo instalaste ZeroClaw.
A) Obtención del código fuente (desarrolladores / empaquetadores)
sh
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo web build # alias para `cargo run -p xtask --bin web -- build`
# ejecuta automáticamente `npm install` en la primera ejecución
El paquete se genera en web/dist/. Apunta web_dist_dir a la ruta absoluta de ese directorio, o ejecuta el daemon desde la raíz del repositorio y deja que el candidato 1 de detección automática lo localice.
El conjunto completo de subcomandos de cargo web (dev, check, gen-api, etc.) está documentado en Building the web dashboard.
B) Artefacto de versión precompilado
Los archivos de versión en la página de Releases incluyen el daemon con web/dist/ ya poblado junto al binario. El candidato 2 de detección automática lo encuentra; no se necesita configurar gateway.web_dist_dir.
C) Imagen de Docker
La imagen oficial de Docker coloca el bundle en /zeroclaw-data/web/dist (candidato 3 de detección automática). Funciona sin configuración adicional; solo necesitas establecer web_dist_dir si montas tu propio volumen sobre esa ruta.
Prioridad de anulación
El valor se resuelve con el orden estándar de las capas de configuración:
ZEROCLAW_gateway__web_dist_dir(variable de entorno que refleja el esquema, consulta Variables de entorno)- El directorio
gateway.web_dist_dirconfigurado - Detección automática (los cinco candidatos anteriores)
Las anulaciones mediante variables de entorno se aplican solo a la Config en memoria; nunca se persisten.
Gramática de esquema-espejo: derivación de ZEROCLAW_gateway__web_dist_dir
La gramática general de anulación de operadores (consulta Variables de entorno) asigna la ruta TOML con puntos a un nombre de variable de entorno de forma mecánica:
TOML path: gateway.web_dist_dir
─────── ─────────────
section field-name (snake_case, kept as-is)
Env var: ZEROCLAW_gateway__web_dist_dir
───────── ── ────────────
prefix path-separator field-name
(`.` → `__`) (unchanged)
Los mismos tres pasos producen nombres de variables de entorno para cada otra opción de configuración del gateway, p. ej., gateway.request_timeout_secs se convierte en ZEROCLAW_gateway__request_timeout_secs.
Errores comunes
No uses ~ ni $HOME
Una tilde literal no es expandida por el gateway; use una ruta absoluta para gateway.web_dist_dir. Las variables de shell ($HOME, %USERPROFILE%) tampoco se expanden; expándalas previamente en la variable de entorno si establece el valor de esa manera:
sh
export ZEROCLAW_gateway__web_dist_dir="$HOME/zeroclaw/web/dist" # shell expande $HOME
El PR #6961 complementario añade la comprobación específica “parece un ~ / $VAR sin expandir, aplique shellexpand antes de escribir este valor” registrada en el issue #6079 tanto a zeroclaw doctor como a zeroclaw self-test como un diagnóstico de severidad Warn. Ninguno de los dos comandos lo muestra en el master actual; hasta que se integre #6961, expanda ~ / $VAR usted mismo antes de escribir gateway.web_dist_dir (por ejemplo, escriba /home/alice/zeroclaw/web/dist en lugar de ~/zeroclaw/web/dist).
Las rutas relativas se resuelven respecto al CWD, no respecto al archivo de configuración
web_dist_dir = "web/dist" se interpreta de forma relativa al directorio de trabajo del daemon en el momento del inicio, no de forma relativa a la ubicación de la configuración. Si distribuye una configuración a otro host o invoca el daemon desde un directorio diferente (p. ej., mediante systemd), la forma relativa buscará en el lugar incorrecto. Use rutas absolutas para web_dist_dir.
Advertencia de “Stale path” al inicio
WARN gateway.web_dist_dir points at a path without a usable index.html
on this machine; falling back to auto-detect. Update or remove the setting
to silence this warning.
Esto significa que la ruta es sintácticamente válida, pero su archivo de índice falta o no se puede servir desde la raíz de ese panel. Ejecuta cargo web build, corrige la ruta o elimina la configuración por completo y deja que la detección automática se encargue.
“Web dashboard: not available” al iniciar
INFO Web dashboard: not available — no web/dist found. Build with
`cargo web build` and point gateway.web_dist_dir at the resulting
web/dist directory.
Los endpoints de la API siguen funcionando, solo falta el bundle de HTML/JS. Constrúyelo (opción A/B/C anteriores) o configura la ruta.
Ver también
- Variables de entorno: gramática completa de espejo de esquema
- API HTTP de Gateway: con lo que se comunica el panel de control
- Compilar el panel web: subcomandos de
cargo weby qué se genera