Windows

Instalar, actualizar, ejecutar como una tarea programada de Windows y desinstalar en Windows 10 / 11.

Si estás usando WSL2, puedes seguir la configuración de Linux en su lugar; install.sh se ejecuta sin cambios en WSL.

Nota sobre setup.bat. Los errores de detención abrupta #6118 (el desbordamiento de espacio en disco de set /a de 32 bits y el error de análisis if/else con paréntesis sin escapar) se corrigieron en #6137 y se incluyen en v0.7.4 y posteriores. Las versiones actuales se completan con normalidad. Queda una salvedad: setup.bat --prebuilt todavía comprueba cargo antes de llegar a la rama precompilada, así que la ruta de precompilado manual (Opción 1 abajo) es la verdadera instalación sin Rust. Compilar desde el código fuente (Opción 3) también funciona.

Instalar

Opción 1: Binario precompilado (recomendado)

Descarga el zip de la última versión para Windows, extrae zeroclaw.exe y colócalo en tu PATH.

Desde un símbolo del sistema de PowerShell:

# La instalación y la configuración de PATH son idempotentes. Si zeroclaw ya está en la
# versión más reciente y en el PATH del usuario, esos pasos se omiten; Quickstart
# se ejecuta igualmente al final.
$ver = (Invoke-RestMethod 'https://api.github.com/repos/zeroclaw-labs/zeroclaw/releases/latest').tag_name.TrimStart('v')
$dst = "$env:USERPROFILE\.zeroclaw\bin"
$exe = "$dst\zeroclaw.exe"

$current = if (Test-Path $exe) {
    ((& $exe --version 2>$null) | Select-String -Pattern '\d+\.\d+\.\d+').Matches.Value
} else { '' }

if ($current -ne $ver) {
    $url = "https://github.com/zeroclaw-labs/zeroclaw/releases/download/v$ver/zeroclaw-x86_64-pc-windows-msvc.zip"
    New-Item -ItemType Directory -Force -Path $dst | Out-Null
    Invoke-WebRequest -Uri $url -OutFile "$env:TEMP\zeroclaw.zip" -UseBasicParsing
    Expand-Archive -Force -Path "$env:TEMP\zeroclaw.zip" -DestinationPath $dst
}

$environment = [Environment]
$userPath = $environment::GetEnvironmentVariable('Path', 'User')
if (($userPath -split ';') -notcontains $dst) {
    $environment::SetEnvironmentVariable('Path', "$dst;$userPath", 'User')
}
if (($env:Path -split ';') -notcontains $dst) {
    $env:Path = "$dst;$env:Path"
}

& $exe quickstart

Para el comportamiento estable común a las rutas de Windows de binarios precompilados y de código fuente, consulta las rutas de instalación canónicas. La disponibilidad de las versiones y el bloque de descarga de PowerShell siguen documentándose aquí porque dependen de los recursos activos de GitHub.

El archivo zip precompilado es autosuficiente; Visual Studio Build Tools solo son necesarios para compilar desde el código fuente.

Después de la instalación, verifica:

zeroclaw --version    # matches the latest release

Opción 2: setup.bat (de una versión de lanzamiento)

setup.bat --prebuilt

Flags:

⚠️ Problema conocido (actual). setup.bat --prebuilt todavía comprueba cargo antes de llegar a la rama precompilada, así que la Opción 2 no cumple una promesa de no usar Rust. Si no tienes una cadena de herramientas de Rust, usa la Opción 1 de arriba.

Histórico (pre-v0.7.4). Las versiones anteriores tenían dos fallos críticos y una discrepancia en el comando de onboarding reportados en #6118: un desbordamiento de espacio en disco en set /a de 32 bits (Invalid number. Numbers are limited to 32-bits of precision.), un error de análisis if/else con paréntesis sin escapar (.[0m was unexpected at this time.), y un aviso final de zeroclaw init. Todo se corrigió en #6137 (v0.7.4 / 0.7.5 / 0.8.0); las versiones actuales imprimen zeroclaw quickstart y finalizan normalmente.

Opción 3: Desde el origen

Requiere Rust (rustup) y las herramientas de compilación de Visual Studio:

git clone https://github.com/zeroclaw-labs/zeroclaw
cd zeroclaw
cargo install --locked --path .
zeroclaw quickstart

Opción 4: Scoop

scoop bucket add zeroclaw https://github.com/zeroclaw-labs/scoop-zeroclaw
scoop install zeroclaw
zeroclaw quickstart

Opción 5: Docker

ZeroClaw publica una imagen de contenedor de Linux en ghcr.io/zeroclaw-labs/zeroclaw:latest (y :vX.Y.Z para versiones etiquetadas). En Windows, ejecútala mediante Docker Desktop o mediante sudo apt install docker.io dentro de una distribución WSL; ambos funcionan, y el comportamiento del contenedor es idéntico.

Inicio rápido:

# Volumen persistente para la configuración + espacio de trabajo; el directorio de datos de ZeroClaw dentro del contenedor es /zeroclaw-data
docker run -d --name zeroclaw `
  --restart=unless-stopped `
  -p 42617:42617 `
  -v zeroclaw-data:/zeroclaw-data `
  ghcr.io/zeroclaw-labs/zeroclaw:latest

# Vigila los registros del primer inicio
docker logs -f zeroclaw

# Comprobación de estado (no requiere autenticación)
curl http://localhost:42617/health

# (Opcional) empareja un cliente. NOTA: la imagen publicada usa por defecto
# `require_pairing = false`, así que por defecto no se emite código de emparejamiento
# y `/api/*` acepta solicitudes sin autenticación. Para habilitar el emparejamiento,
# sobrescribe la configuración (establece `require_pairing = true` en
# /zeroclaw-data/.zeroclaw/config.toml dentro del contenedor) y reinicia;
# entonces se imprime un código de un solo uso en stdout en el primer inicio, tras lo cual
# los clientes lo envían por POST a `/pair`:
curl -X POST http://localhost:42617/pair -H 'X-Pairing-Code: <code-from-logs>'

Datos de la imagen (verificados contra ghcr.io/zeroclaw-labs/zeroclaw:latest):

• Base: gcr.io/distroless/cc-debian13:nonroot (etapa de release; la etapa dev es debian:trixie-slim)
• ENTRYPOINT ["zeroclaw"], CMD ["daemon"]: ejecutar sin argumentos inicia el daemon y la pasarela
• EXPOSE 42617: tanto el daemon como el gateway escuchan en este puerto
• Directorio de datos: /zeroclaw-data (config: /zeroclaw-data/.zeroclaw/config.toml, espacio de trabajo: /zeroclaw-data/workspace). Monte un volumen con nombre o un enlace aquí para persistencia; tenga en cuenta que esto no es /root/.zeroclaw.
• Emparejamiento: la imagen publicada tiene por defecto require_pairing = false, así que /api/* acepta solicitudes sin autenticación desde el principio. Cuando el emparejamiento está habilitado (establece require_pairing = true en /zeroclaw-data/.zeroclaw/config.toml y reinicia), el daemon imprime un código de un solo uso en stdout al iniciarse por primera vez, y luego los clientes lo envían por POST a /pair con el encabezado X-Pairing-Code antes de que cualquier endpoint autenticado responda.
• Panel web: incluido y servido por defecto en la imagen publicada. La imagen establece gateway.web_dist_dir = "/usr/share/zeroclawlabs/web/dist" e incluye allí el frontend compilado, por lo que el gateway sirve el fallback de SPA listo para usar. Los recursos viven fuera del punto de montaje /zeroclaw-data, así que un montaje de volumen -v …:/zeroclaw-data no puede ocultarlos (ref #6400).

Compila desde el código fuente usando el Dockerfile incluido:

git clone https://github.com/zeroclaw-labs/zeroclaw
cd zeroclaw
docker build -t zeroclaw:local -f Dockerfile.debian .

Verificado en Windows + Docker:

• El comportamiento del contenedor coincide con Linux. Se descargó y ejecutó ghcr.io/zeroclaw-labs/zeroclaw:latest en WSL Debian en Windows 11 build 26200.8313. La imagen arranca correctamente, el gateway escucha en :42617, /health devuelve JSON válido. Con require_pairing = true configurado en la configuración y el contenedor reiniciado, el flujo del código de emparejamiento en /pair también funciona según la documentación.
• Docker sin Docker Desktop. wsl --install para habilitar WSL2, luego sudo apt install docker.io dentro de la distro WSL, te da el daemon directamente; verificado para descargar y ejecutar la imagen publicada sin modificación.

Mejores prácticas del lado del host: orientación general sobre Docker + WSL2, no afirmaciones de tiempo de ejecución específicas de zeroclaw. Procede de Microsoft Learn y de la propia documentación de Docker cuando corresponde:

• Puntos de montaje de volúmenes. El montaje enlazado de rutas del lado de Windows (-v C:/Users/...:/zeroclaw-data) en un contenedor Linux cruza el límite del sistema de archivos entre WSL2 y Windows; Microsoft documenta la disposición y las implicaciones de rutas entre sistemas operativos en la referencia de sistemas de archivos de WSL. Prefiere volúmenes con nombre de Docker (-v zeroclaw-data:/zeroclaw-data) o almacena el espacio de trabajo dentro del sistema de archivos de WSL (\\wsl$\Debian\home\...) para obtener un rendimiento casi nativo.

• Redes. La red predeterminada de WSL2 usa NAT, así que los servicios en el contenedor son accesibles desde Windows mediante localhost:<port> después del reenvío -p (verificado en Windows 11 + WSL2). Si necesitas llegar al contenedor desde otro equipo en la LAN, o ejecutar configuraciones de varios contenedores donde el DNS entre contenedores importa, cambia al modo reflejado según la referencia de Microsoft sobre Mirrored mode networking, añadiendo a %USERPROFILE%\.wslconfig:

  [wsl2]
  networkingMode=mirrored
  

• Daemon bajo Docker, no Task Scheduler. Dentro del contenedor no hay Windows Task Scheduler. Usa la política de reinicio de Docker, --restart=unless-stopped, como en el ejemplo anterior, para el arranque en modo daemon. La imagen publicada se ejecuta como PID 1 / usuario no root; el contenedor es el servicio; no ejecutes zeroclaw service install dentro de él.

• Sandbox de habilidades mediante el socket Docker del host. El sandbox de ejecución de habilidades de ZeroClaw puede invocar Docker. Si ejecutas ZeroClaw en un contenedor y quieres que el sandbox de habilidades también use Docker, monta el socket Docker del host para que los contenedores hijos se ejecuten en el daemon del host en lugar de anidar Docker dentro de Docker:

  # PowerShell / cmd.exe: use a single leading slash.
  # Git Bash / MINGW: use //var/run/docker.sock to bypass MSYS path rewriting.
  -v /var/run/docker.sock:/var/run/docker.sock
  

  Ten en cuenta que montar el socket de Docker concede acceso al host equivalente a root a todo lo que esté dentro del contenedor; la página de Docker Protect the Docker daemon socket cubre la compensación. En Docker Desktop para Windows, el socket del host es \\.\pipe\docker_engine; la sintaxis de bind-mount anterior se traduce correctamente. El patrón es general; no se ha evaluado específicamente frente al sandbox de habilidades de zeroclaw en esta documentación.

• Límites de recursos. Docker Desktop en Windows asigna RAM/CPU mediante %USERPROFILE%\.wslconfig, que por defecto usa la mitad de la RAM del host. La superficie de configuración completa está documentada en la referencia de Microsoft Configuración avanzada en WSL. Un margen inicial razonable para una implementación de ZeroClaw de un solo usuario es:

  [wsl2]
  memory=8GB
  processors=4
  

  Auméntalo si estás ejecutando cargas de trabajo pesadas de habilidades o inferencia local de LLM dentro de la misma distro de WSL; esta es una guía de dimensionamiento, no un requisito estricto de la imagen.

Dependencias del sistema

Las compilaciones de Windows usan la cadena de herramientas MSVC. Para compilar desde el código fuente necesitas:

• Herramientas de compilación de Visual Studio (o Visual Studio completo) con la carga de trabajo “Desarrollo de escritorio con C++”
• Rust estable (vía rustup)

Si usas Opción 1, no necesitas la cadena de herramientas de Rust; el binario es autónomo. La Opción 2 (setup.bat --prebuilt) está pensada para usar la misma ruta del binario, pero el script actual sigue comprobando cargo antes de llegar a la rama precompilada; consulta el problema conocido de arriba.

Ejecutándose como un servicio

En Windows, ZeroClaw se instala como una tarea programada con ámbito de usuario llamada ZeroClaw Daemon. No hay opción de Servicio de Windows / LocalSystem en la versión actual; la ruta de código subyacente siempre instala una tarea programada, independientemente de si zeroclaw service install se ejecuta desde una shell con privilegios elevados o no.

zeroclaw service install
zeroclaw service start

Esto crea una tarea en el Programador de tareas (taskschd.msc) bajo tu cuenta de usuario que se inicia al iniciar sesión. Administrarla mediante:

zeroclaw service status
zeroclaw service restart
zeroclaw service stop
zeroclaw service logs

Acerca de --service-init. La CLI expone una bandera --service-init [auto|systemd|openrc] para mantener la coherencia entre plataformas, pero en Windows no tiene efecto; siempre se usa la ruta de tarea programada.

Los registros van a %USERPROFILE%\.zeroclaw\logs\ (en concreto, <config_dir>/logs/, donde <config_dir> por defecto es %USERPROFILE%\.zeroclaw\). Sin embargo, el propio contenedor de la tarea programada reside junto al archivo de configuración en %USERPROFILE%\.zeroclaw\zeroclaw-daemon.cmd. Solo los archivos de salida del daemon (daemon.stdout.log / daemon.stderr.log) se escriben en logs\.

Instalaciones de servidor / multiusuario. El soporte nativo para Windows Service / LocalSystem está en la hoja de ruta, pero aún no está implementado. Por ahora, en un servidor, instala ZeroClaw bajo la cuenta con la que debe ejecutarse el agente; la ruta de tarea programada lo iniciará al iniciar sesión ese usuario. Si necesitas que se inicie antes de que cualquier usuario inicie sesión, usa Task Scheduler → ZeroClaw Daemon → Properties → General → “Run whether user is logged on or not.”

Actualizar

Manual (ruta de la opción 1)

Vuelva a ejecutar el bloque de instalación de PowerShell de Opción 1 con el nuevo $ver. El nuevo zip sobrescribe zeroclaw.exe existente en su lugar. Luego:

zeroclaw service restart

setup.bat

Vuelve a descargar la última versión y vuelve a ejecutar setup.bat --prebuilt (o la bandera que usaste originalmente). Luego:

zeroclaw service restart

Scoop

scoop update zeroclaw
zeroclaw service restart

Desde la fuente

cd C:\path\to\zeroclaw
git pull
cargo install --locked --path . --force
zeroclaw service restart

Desinstalar

Detén y elimina la tarea programada:

zeroclaw service stop
zeroclaw service uninstall

Eliminar el binario:

:: Opción 1 (precompilado manual) o setup.bat
rmdir /s /q "%USERPROFILE%\.zeroclaw\bin"

:: Option 3 (cargo install)
del "%USERPROFILE%\.cargo\bin\zeroclaw.exe"

:: Option 4 (Scoop)
scoop uninstall zeroclaw

Elimina config, workspace y logs (opcional; esto elimina el historial de conversaciones):

rmdir /s /q "%USERPROFILE%\.zeroclaw"

La versión anterior de este documento hacía referencia a %LOCALAPPDATA%\ZeroClaw\; esa ruta no la usa la versión actual; solo se usa %USERPROFILE%\.zeroclaw\.

Cosas a tener en cuenta

• Rutas largas. Algunos sistemas de archivos de Windows aún limitan la longitud de las rutas a 260 caracteres. Habilita la compatibilidad con rutas largas si encuentras errores de path too long durante una compilación desde el código fuente:

  reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f
  

• SmartScreen. El binario no firmado puede activar SmartScreen en el primer inicio desde Explorer (doble clic). Clic derecho → Propiedades → “Desbloquear” es la solución habitual hasta que agreguemos un MSI firmado. Iniciarlo desde PowerShell o cmd.exe normalmente no activa SmartScreen.

• Programador de tareas detener en inactividad / batería. De forma predeterminada, Windows puede finalizar las tareas programadas cuando hay inactividad o batería. La tarea instalada ZeroClaw Daemon deshabilita estas condiciones, pero si lo has instalado mediante una versión anterior, puedes verificarlo en Task Scheduler → ZeroClaw Daemon → Properties → Conditions:

  • “Iniciar la tarea solo si el ordenador está conectado a la corriente”: unchecked
  • “Detener si el equipo cambia a alimentación por batería”: desmarcado
  • “Iniciar la tarea solo si el ordenador está inactivo durante…”: unchecked

• Autenticación por contraseña de OpenSSH. Si estás administrando Windows por SSH y la clave pública no se acepta, coloca tu clave en C:\Users\<user>\.ssh\authorized_keys (usuario normal) o C:\ProgramData\ssh\administrators_authorized_keys (cuando hayas iniciado sesión como miembro de Administrators).

Siguiente

• Gestión de servicios
• Inicio rápido
• Operaciones → Resumen