Gestion des services

ZeroClaw est livré avec une intégration de services de premier plan pour systemd (Linux), launchctl (macOS) et le Planificateur de tâches (Windows). Les trois sont pilotés par une seule surface CLI :

sh

zeroclaw service install     # enregistrer le service
zeroclaw service start       # démarrez-le
zeroclaw service stop        # arrêtez
zeroclaw service restart     # arrêter + démarrer
zeroclaw service status      # en cours d'exécution / arrêté, dernier code de sortie
zeroclaw service uninstall   # supprimez-le

Les backends spécifiques à chaque plateforme sont implémentés dans crates/zeroclaw-runtime/src/service/. Vous n’avez pas besoin d’y penser, mais savoir ce qu’ils produisent est utile lors du débogage.

Linux : systemd

zeroclaw service install écrit une unité à portée d’utilisateur dans ~/.config/systemd/user/zeroclaw.service.

L’unité :

Type=simple avec le processus agent restant au premier plan
ExecStart={cargo-bin}/zeroclaw daemon
Restart=always avec RestartSec=3
Environment=HOME=%h et PassEnvironment=DISPLAY XDG_RUNTIME_DIR afin que les outils de navigateur headless puissent créer les répertoires de profil/cache et accéder à la session utilisateur
WantedBy=default.target

Contrôle manuel (systemd)

sh

systemctl --user start zeroclaw
systemctl --user stop zeroclaw
systemctl --user status zeroclaw
systemctl --user enable zeroclaw     # démarrer à la connexion

Journaux

sh

journalctl --user -u zeroclaw -f        # suivre
journalctl --user -u zeroclaw --since Il y a 1 heure

Surcharges de l’environnement (systemd)

Utilisez une substitution de service utilisateur lorsque le daemon a besoin de variables d’environnement qui ne sont pas présentes dans votre shell interactif :

sh

systemctl --user edit zeroclaw.service

Par exemple, un profil Bedrock qui utilise credential_process nécessite AWS_PROFILE dans l’environnement du service :

[Service]
Environment=AWS_PROFILE=zeroclaw-bedrock

Après avoir enregistré la surcharge, rechargez et redémarrez le service utilisateur :

sh

systemctl --user daemon-reload
systemctl --user restart zeroclaw
journalctl --user -u zeroclaw -f

Le service utilisateur généré définit HOME=%h, de sorte que le code du fournisseur qui lit des fichiers dans le répertoire personnel de l’utilisateur du service peut résoudre des chemins tels que ~/.aws/config. Si une substitution référence un exécutable, utilisez un chemin absolu ; les services systemd s’exécutent souvent avec un PATH plus restreint qu’un shell interactif.

Démarrage avant la connexion de l’utilisateur

La CLI n’écrit jamais qu’une unité au niveau utilisateur (systemctl --user), qui par défaut démarre à la connexion et s’arrête à la déconnexion. Pour que ZeroClaw continue de fonctionner sur une machine headless sans session active, activez le lingering pour l’utilisateur du service :

sh

sudo loginctl enable-linger $USER
systemctl --user enable --now zeroclaw

Si vous avez besoin d’une véritable unité de portée système (appartenant à root, /etc/systemd/system/, compte de service dédié, ou groupes matériels via SupplementaryGroups), la CLI n’en génère pas ; adaptez le modèle au niveau système scripts/zeroclaw.service et installez-le vous-même. Sur les hôtes OpenRC, sudo zeroclaw service install provisionne bien un utilisateur zeroclaw dédié et des chemins système (voir ci-dessous).

Linux : OpenRC

Détecté automatiquement lorsque /run/openrc existe (Alpine, certaines configurations Gentoo).

sh

zeroclaw service install   # écrit /etc/init.d/zeroclaw
rc-service zeroclaw start
rc-update add zeroclaw default    # démarrer au démarrage

OpenRC conserve la sortie du démon dans /var/log/zeroclaw/access.log et /var/log/zeroclaw/error.log. Chaque fichier conserve la sortie récente dans une limite de 8 Mio. Réinstallez et redémarrez le service après la mise à niveau afin que le script d’initialisation généré utilise des processus de journalisation à taille limitée.

macOS : LaunchAgent

zeroclaw service install écrit ~/Library/LaunchAgents/com.zeroclaw.daemon.plist et le charge.

sh

launchctl list | grep zeroclaw
launchctl unload ~/Library/LaunchAgents/com.zeroclaw.daemon.plist
launchctl load ~/Library/LaunchAgents/com.zeroclaw.daemon.plist

Les journaux sont écrits dans <config-dir>/logs/ sous les noms daemon.stdout.log et daemon.stderr.log (pour une installation par défaut, ~/.zeroclaw/logs/). Les installations Homebrew écrivent plutôt dans $HOMEBREW_PREFIX/var/zeroclaw/logs/. Chaque fichier de capture launchd conserve la sortie récente dans une limite de 8 Mio. Réinstallez et redémarrez le service après la mise à niveau afin que le LaunchAgent généré utilise une capture limitée.

Géré par Homebrew

Si installé via Homebrew, brew services est l’interface préférée :

sh

brew services start zeroclaw
brew services restart zeroclaw
brew services info zeroclaw

Ne mélangez pas les commandes CLI zeroclaw service avec brew services, choisissez l’un des deux. Les deux finissent par écrire un plist ; avoir les deux à la fois perturbe launchctl.

Windows : Planificateur de tâches

zeroclaw service install crée une tâche planifiée par utilisateur nommée ZeroClaw Daemon :

Déclencheur : à l’ouverture de session (/SC ONLOGON)
Niveau d’exécution : LIMITED (s’exécute en tant qu’utilisateur actuel, sans élévation de privilèges)
Action : exécute le wrapper d’installation zeroclaw-daemon.cmd, qui lance zeroclaw daemon

Vérifiez dans l’interface graphique du Planificateur de tâches (taskschd.msc) sous Bibliothèque du Planificateur de tâches → ZeroClaw Daemon.

Les journaux sont enregistrés dans <config-dir>\logs\ sous les noms daemon.stdout.log et daemon.stderr.log (pour une installation par défaut, %USERPROFILE%\.zeroclaw\logs\) :

cmd

type %USERPROFILE%\.zeroclaw\logs\daemon.stdout.log

Contrôle manuel (Planificateur de tâches)

La tâche est pilotée via zeroclaw service start|stop|status, qui encapsule schtasks /Run, /End et /Query pour la tâche ZeroClaw Daemon. Vous pouvez également la gérer directement :

cmd

schtasks /Run /TN "ZeroClaw Daemon"
schtasks /End /TN "ZeroClaw Daemon"
schtasks /Query /TN "ZeroClaw Daemon" /FO LIST

Le CLI installe uniquement une tâche ONLOGON par utilisateur ; il n’enregistre pas de service Windows LocalSystem. Pour un véritable service système, encapsulez vous-même le binaire avec un superviseur tiers (par ex. NSSM).

Résolution du chemin de configuration

Le service lit la configuration depuis le répertoire résolu au moment de l’installation. Ordre de priorité (la première correspondance l’emporte) :

$ZEROCLAW_CONFIG_DIR (la configuration se trouve directement sous $ZEROCLAW_CONFIG_DIR)
$ZEROCLAW_DATA_DIR
$ZEROCLAW_WORKSPACE (obsolète, préférez ZEROCLAW_DATA_DIR ; résout soit $ZEROCLAW_WORKSPACE, soit l’ancien répertoire frère .zeroclaw/)
Sur macOS uniquement, le répertoire de configuration Homebrew ($HOMEBREW_PREFIX/var/zeroclaw/) lors d’une installation via Homebrew
Par défaut ~/.zeroclaw/ (Linux/macOS) ou %USERPROFILE%\.zeroclaw\ (Windows)

ZEROCLAW_CONFIG_DIR est prioritaire sur tout le reste ; le définir en même temps que ZEROCLAW_DATA_DIR ou ZEROCLAW_WORKSPACE génère un avertissement dans les journaux et les autres sont ignorées.

Si votre service semble ignorer les modifications de configuration, vérifiez quel chemin le démon a résolu : zeroclaw status indique le fichier de configuration actif, et le runtime journalise une ligne de source de résolution au démarrage :

sh

zeroclaw status

La sortie inclut le chemin du fichier de configuration utilisé pour la résolution.

Mise à jour automatique

Le service ne se met pas à jour automatiquement. C’est délibéré ; vous choisissez quand adopter le nouveau code. Abonnez-vous au flux de versions GitHub ou au canal Discord #releases (voir Contributing → Communication).

ZeroClaw Docs