Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Panel web (gateway.web_dist_dir)

El daemon del gateway incluye su API HTTP en el binario, pero el HTML/JS/CSS del panel web reside 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 reflejada en el esquema ZEROCLAW_gateway__web_dist_dir) le indica al daemon dónde está ese directorio. Cuando ni el ajuste ni una ubicación de respaldo conocida contienen un index.html compilado, el gateway arranca 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 from /absolute/path/to/zeroclaw/web/dist

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:

  1. Lee el valor configurado (o la anulación de la variable de entorno).
  2. Verifica que el directorio existe Y contiene index.html en esta máquina.
  3. Si es así, sirve el panel desde esa ruta.
  4. Si no, registra un WARN (“path doesn’t contain index.html on this machine; falling back to auto-detect”) e intenta los candidatos de detección automática que se indican a continuación.
  5. 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 se establece en una ruta sin index.html), el daemon explora estas ubicaciones en orden y sirve desde la primera que contenga index.html:

#CandidatoCuando coincide
1./web/dist (relativo al CWD)Ejecutar cargo run desde la raíz del repositorio en dev
2<dir-of-binary>/web/distEl binario empaquetado incluye web/dist junto a sí mismo
3/zeroclaw-data/web/distEstructura estándar de Docker / volumen empaquetado
4/usr/share/zeroclawlabs/web/distInstalación de paquetes AUR / del sistema
5${XDG_DATA_HOME:-~/.local/share}/zeroclaw/web/distInstalador 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:

  1. ZEROCLAW_gateway__web_dist_dir (variable de entorno que refleja el esquema, consulta Variables de entorno)
  2. El directorio gateway.web_dist_dir configurado
  3. 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 that doesn't contain 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 el archivo aún no está ahí. 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