Windows

Installer, mettre à jour, exécuter en tant que tâche planifiée Windows et désinstaller sur Windows 10 / 11.

Si vous utilisez WSL2, vous pouvez plutôt suivre la configuration Linux ; install.sh s’exécute tel quel sous WSL.

Remarque sur setup.bat. Les erreurs bloquantes #6118 (dépassement d’espace disque 32 bits avec set /a et erreur d’analyse if/else liée aux parenthèses non échappées) ont été corrigées dans #6137 et sont incluses dans v0.7.4 et versions ultérieures. Les versions actuelles s’exécutent normalement. Une réserve subsiste : setup.bat --prebuilt vérifie toujours la présence de cargo avant d’atteindre la branche préconstruite, de sorte que le chemin préconstruit manuel (Option 1 ci-dessous) correspond à la véritable installation sans Rust. La compilation depuis les sources (Option 3) fonctionne également.

Installer

Option 1 : Binaire précompilé (recommandé)

Téléchargez le dernier fichier zip de la version Windows, extrayez zeroclaw.exe, et ajoutez-le à votre PATH.

Depuis une invite de commandes PowerShell :

# L’installation et la configuration de PATH sont idempotentes. Si zeroclaw est déjà à la
# dernière version et présent dans le PATH de l’utilisateur, ces étapes sont ignorées ;
# Quickstart s’exécute quand même à la fin.
$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

Pour le comportement stable commun aux méthodes Windows précompilées et depuis les sources, consultez les parcours d’installation de référence. La disponibilité des versions et le bloc de téléchargement PowerShell restent documentés ici, car ils dépendent de ressources GitHub en temps réel.

L’archive zip précompilée est autonome ; Visual Studio Build Tools est requis uniquement pour compiler à partir des sources.

Après l’installation, vérifiez :

zeroclaw --version    # matches the latest release

Option 2 : setup.bat (à partir d’une version)

setup.bat --prebuilt

Options :

⚠️ Problème connu (actuel). setup.bat --prebuilt vérifie toujours la présence de cargo avant d’atteindre la branche prebuilt, donc l’Option 2 ne respecte pas la promesse sans Rust. Si vous n’avez pas de chaîne d’outils Rust, utilisez l’Option 1 ci-dessus.

Historique (pré-v0.7.4). Les versions antérieures présentaient deux échecs bloquants et une discordance de commande d’onboarding signalés dans #6118 : un débordement d’espace disque set /a 32 bits (Invalid number. Numbers are limited to 32-bits of precision.), une erreur d’analyse if/else due à des parenthèses non échappées (.[0m was unexpected at this time.), et une invite finale zeroclaw init. Tous ont été corrigés dans #6137 (v0.7.4 / 0.7.5 / 0.8.0) ; les versions actuelles affichent zeroclaw quickstart et se terminent normalement.

Option 3 : À partir des sources

Requiert Rust (rustup) et les Outils de génération Visual Studio :

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

Option 4: Scoop

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

Option 5 : Docker

ZeroClaw publie une image de conteneur Linux à ghcr.io/zeroclaw-labs/zeroclaw:latest (et :vX.Y.Z pour les versions taguées). Sous Windows, exécutez-la via Docker Desktop ou via sudo apt install docker.io dans une distribution WSL ; les deux fonctionnent, et le comportement du conteneur est identique.

Démarrage rapide :

# Volume persistant pour la configuration et l'espace de travail ; le répertoire de données de ZeroClaw à l'intérieur du conteneur est /zeroclaw-data
docker run -d --name zeroclaw `
  --restart=unless-stopped `
  -p 42617:42617 `
  -v zeroclaw-data:/zeroclaw-data `
  ghcr.io/zeroclaw-labs/zeroclaw:latest

# Surveiller les logs du premier démarrage
docker logs -f zeroclaw

# Vérification de l'état de santé (aucune authentification requise)
curl http://localhost:42617/health

# (Facultatif) appairer un client. REMARQUE : l'image publiée utilise par défaut
# `require_pairing = false`, donc par défaut aucun code d'appairage n'est émis
# et `/api/*` accepte les requêtes sans authentification. Pour activer l'appairage,
# remplacez la configuration (définissez `require_pairing = true` dans
# /zeroclaw-data/.zeroclaw/config.toml à l'intérieur du conteneur) et redémarrez ;
# un code à usage unique est alors imprimé sur stdout au premier démarrage, après quoi
# les clients le POST à `/pair` :
curl -X POST http://localhost:42617/pair -H 'X-Pairing-Code: <code-from-logs>'

Informations sur l’image (vérifiées par rapport à ghcr.io/zeroclaw-labs/zeroclaw:latest):

• Base : gcr.io/distroless/cc-debian13:nonroot (phase de version ; la phase dev est debian:trixie-slim))
• `ENTRYPOINT [“zeroclaw”]`, `CMD [“daemon”]`: l’exécution sans argument démarre le daemon et la passerelle
• EXPOSE 42617 : le daemon et la passerelle écoutent sur ce port
• Répertoire de données : /zeroclaw-data (configuration : /zeroclaw-data/.zeroclaw/config.toml, espace de travail : /zeroclaw-data/workspace). Montez un volume nommé ou liez-y un répertoire pour la persistance ; notez qu’il ne s’agit pas de /root/.zeroclaw.
• Appairage : l’image publiée utilise par défaut require_pairing = false, de sorte que /api/* accepte les requêtes sans authentification sans configuration préalable. Lorsque l’appairage est activé (définissez require_pairing = true dans /zeroclaw-data/.zeroclaw/config.toml et redémarrez), le daemon affiche un code à usage unique sur stdout lors du premier démarrage, puis les clients doivent le poster sur /pair avec l’en-tête X-Pairing-Code avant qu’un point de terminaison authentifié ne réponde.
• Tableau de bord Web : empaqueté et servi par défaut dans l’image publiée. L’image définit gateway.web_dist_dir = "/usr/share/zeroclawlabs/web/dist" et y inclut le frontend compilé, afin que la passerelle serve le fallback SPA directement. Les fichiers se trouvent en dehors du point de montage /zeroclaw-data afin qu’un montage de volume -v …:/zeroclaw-data ne les masque pas (réf. #6400).

Compiler à partir des sources avec le Dockerfile inclus :

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

Vérifié sur Windows + Docker :

• Le comportement du conteneur correspond à celui de Linux. Téléchargé et exécuté ghcr.io/zeroclaw-labs/zeroclaw:latest dans WSL Debian sur Windows 11 build 26200.8313. L’image démarre correctement, la passerelle écoute sur :42617, /health retourne du JSON valide. Avec require_pairing = true défini dans la configuration et le conteneur redémarré, le flux de code d’appairage sur /pair fonctionne également comme documenté.
• Docker sans Docker Desktop. wsl --install pour activer WSL2, puis sudo apt install docker.io dans la distribution WSL, vous donne le daemon directement ; vérifié pour récupérer et exécuter l’image publiée sans modification.

Bonnes pratiques côté hôte : conseils généraux pour Docker + WSL2, sans affirmations spécifiques au runtime zeroclaw. Issu de Microsoft Learn et de la documentation officielle de Docker, le cas échéant :

• Montages de volumes. Le montage par liaison de chemins côté Windows (-v C:/Users/...:/zeroclaw-data) dans un conteneur Linux traverse la frontière entre les systèmes de fichiers WSL2 et Windows ; Microsoft documente la disposition et les implications des chemins d’accès inter-systèmes d’exploitation dans la référence WSL file systems. Privilégiez les volumes nommés Docker (-v zeroclaw-data:/zeroclaw-data) ou placez l’espace de travail dans le système de fichiers WSL (\\wsl$\Debian\home\...) pour des performances quasi-natives.

• Réseau. Le réseau WSL2 par défaut est NATé, donc les services du conteneur sont accessibles depuis Windows via localhost:<port> après la redirection -p (vérifié sur Windows 11 + WSL2). Si vous devez accéder au conteneur depuis un autre poste sur le LAN, ou exécuter des configurations multi-conteneurs où le DNS intra-conteneur est important, passez en mode mirroir conformément à la référence de Microsoft Mode réseau en miroir, en ajoutant à %USERPROFILE%\.wslconfig :

  [wsl2]
  networkingMode=mirrored
  

• Daemon sous Docker, et non le Planificateur de tâches. À l’intérieur du conteneur, il n’y a pas de Planificateur de tâches Windows. Utilisez la stratégie de redémarrage de Docker, --restart=unless-stopped comme dans l’exemple ci-dessus, pour un démarrage en mode daemon. L’image publiée s’exécute en tant que PID 1 / utilisateur nonroot ; le conteneur est le service ; n’exécutez pas zeroclaw service install à l’intérieur de celui-ci.

• Bac à sable pour les compétences via le socket Docker de l’hôte. Le bac à sable d’exécution des compétences de ZeroClaw peut invoquer Docker. Si vous exécutez ZeroClaw lui-même dans un conteneur et souhaitez que le bac à sable des compétences utilise également Docker, montez le socket Docker de l’hôte afin que les conteneurs enfants s’exécutent sur le daemon de l’hôte plutôt que d’imbriquer Docker-in-Docker :

  # PowerShell / cmd.exe : utilisez une seule barre oblique en tête.
  # Git Bash / MINGW : utilisez //var/run/docker.sock pour contourner la réécriture de chemin MSYS.
  -v /var/run/docker.sock:/var/run/docker.sock
  

  Soyez conscient que le montage de la socket Docker accorde un accès à l’hôte équivalent à root à tout ce qui se trouve dans le conteneur ; la page Protéger la socket du daemon Docker de Docker couvre les compromis. Sur Docker Desktop pour Windows, la socket hôte est \\.\pipe\docker_engine ; la syntaxe de bind-mount ci-dessus se traduit correctement. Le modèle est général ; il n’a pas été spécifiquement benchmarké contre le sandbox de compétences de zeroclaw dans ce document.

• Limites de ressources. Docker Desktop sur Windows alloue la RAM/CPU via %USERPROFILE%\.wslconfig, par défaut à la moitié de la RAM de l’hôte. La surface de configuration complète est documentée dans la référence de Microsoft Configuration des paramètres avancés dans WSL. Une allocation de ressources de départ raisonnable pour un déploiement ZeroClaw mono-utilisateur est :

  [wsl2]
  memory=8GB
  processors=4
  

  Augmentez-le si vous exécutez des charges de travail de compétences intensives ou une inférence de LLM local dans la même distribution WSL ; il s’agit de recommandations de dimensionnement, et non d’une exigence stricte pour l’image.

Dépendances système

Les builds Windows utilisent la chaîne d’outils MSVC. Pour compiler à partir des sources, vous avez besoin de :

• Outils de build Visual Studio (ou Visual Studio complet) avec la charge de travail « Développement de bureau avec C++ »
• Rust stable (via rustup)

Si vous utilisez Option 1, vous n’avez pas besoin de la toolchain Rust ; le binaire est autonome. L’option 2 (setup.bat --prebuilt) est destinée à utiliser le même chemin du binaire, mais le script actuel vérifie toujours la présence de cargo avant d’atteindre la branche prebuilt ; consultez le problème connu ci-dessus.

Exécution en tant que service

Sous Windows, ZeroClaw s’installe en tant que tâche planifiée au niveau utilisateur nommée ZeroClaw Daemon. Il n’existe pas d’option Windows Service / LocalSystem dans la version actuelle ; le chemin de code sous-jacent installe toujours une tâche planifiée, que zeroclaw service install soit exécuté depuis un shell élevé ou non élevé.

zeroclaw service install
zeroclaw service start

Ceci crée une tâche dans le Planificateur de tâches (taskschd.msc) sous votre compte utilisateur qui démarre à la connexion. Gérez-la via :

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

À propos de --service-init. L’interface en ligne de commande expose le drapeau --service-init [auto|systemd|openrc] pour assurer la cohérence multiplateforme, mais sous Windows il est sans effet ; le chemin des tâches planifiées est toujours utilisé.

Les journaux sont enregistrés dans %USERPROFILE%\.zeroclaw\logs\ (plus précisément, <config_dir>/logs/ où <config_dir> est par défaut %USERPROFILE%\.zeroclaw\). Le wrapper de tâche planifiée lui-même se trouve toutefois à côté du fichier de configuration, à %USERPROFILE%\.zeroclaw\zeroclaw-daemon.cmd. Seuls les fichiers de sortie du daemon (daemon.stdout.log / daemon.stderr.log) sont écrits dans logs\.

Installations serveur / multi-utilisateurs. Le support natif des services Windows / LocalSystem est prévu sur la feuille de route mais n’est pas encore implémenté. Pour l’instant, sur un serveur, installez ZeroClaw sous le compte sous lequel l’agent doit s’exécuter ; le chemin de la tâche planifiée le démarrera lors de la connexion de cet utilisateur. Si vous avez besoin qu’il démarre avant qu’un utilisateur ne se connecte, utilisez Planificateur de tâches → ZeroClaw Daemon → Propriétés → Général → “Exécuter que l’utilisateur soit connecté ou non.”

Mettre à jour

Manuel (chemin Option 1)

Réexécutez le bloc d’installation PowerShell de l’Option 1 avec le nouveau $ver. Le nouveau zip écrase le zeroclaw.exe existant en place. Ensuite :

zeroclaw service restart

setup.bat

Téléchargez à nouveau la dernière version et relancez setup.bat --prebuilt (ou le drapeau que vous avez utilisé initialement). Ensuite :

zeroclaw service restart

Scoop

scoop update zeroclaw
zeroclaw service restart

Depuis la source

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

Désinstaller

Arrêter et supprimer la tâche planifiée :

zeroclaw service stop
zeroclaw service uninstall

Supprimer le binaire :

:: Option 1 (précompilé manuel) ou setup.bat
rmdir /s /q "%USERPROFILE%\.zeroclaw\bin"

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

:: Option 4 (Scoop)
scoop uninstall zeroclaw

Supprimer la configuration, l’espace de travail et les journaux (facultatif ; cela supprime l’historique des conversations) :

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

La version précédente de cette documentation faisait référence à %LOCALAPPDATA%\ZeroClaw\ ; ce chemin n’est pas utilisé par la version actuelle ; seul %USERPROFILE%\.zeroclaw\ l’est.

Pièges

• Chemins d’accès longs. Certains systèmes de fichiers Windows limitent encore la longueur des chemins à 260 caractères. Activez le support des chemins longs si vous rencontrez des erreurs path too long lors de la compilation des sources :

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

• SmartScreen. Le binaire non signé peut déclencher SmartScreen lors du premier lancement depuis l’Explorateur (double-clic). Clic droit → Propriétés → “Débloquer” est la solution de contournement standard jusqu’à ce que nous ajoutions un MSI signé. Le lancement depuis PowerShell ou cmd.exe ne déclenche généralement pas SmartScreen.

• Arrêt du Planificateur de tâches en cas d’inactivité / sur batterie. Par défaut, Windows peut mettre fin aux tâches planifiées lors de l’inactivité ou sur batterie. La tâche ZeroClaw Daemon installée désactive ces conditions, mais si vous avez installé via une ancienne version, vous pouvez vérifier sous Planificateur de tâches → ZeroClaw Daemon → Propriétés → Conditions :

  • “Démarrer la tâche uniquement si l’ordinateur est sur secteur”: non coché
  • “Arrêter si l’ordinateur passe sur batterie”: non coché
  • “Lancer la tâche uniquement si l’ordinateur est inactif pendant…”: non coché

• Authentification par mot de passe OpenSSH. Si vous utilisez Windows via SSH et que l’authentification par clé publique n’est pas acceptée, placez votre clé dans C:\Users\<user>\.ssh\authorized_keys (utilisateur standard) ou C:\ProgramData\ssh\administrators_authorized_keys (lorsque vous êtes connecté en tant que membre de Administrators).

Suivant

• Gestion des services
• Démarrage rapide
• Opérations → Vue d’ensemble