Service & Démon

Cette page est le pendant côté exploitation de Configuration → Gestion du service ; cette dernière couvre l’installation et la désinstallation du service. Cette page couvre son exécution : réglage, limites de ressources, redémarrages progressifs et configurations multi-espaces de travail.

Choisir entre la portée utilisateur et la portée système

Sur Linux de bureau, activez la persistance des services utilisateur afin que le service utilisateur persiste après les déconnexions :

loginctl enable-linger $USER

Sans délai, un service systemd à portée d’utilisateur s’arrête lorsque la dernière session se ferme.

Comportement de redémarrage

L’unité utilisateur systemd installée (~/.config/systemd/user/zeroclaw.service) utilise :

Restart=always
RestartSec=3

systemd redémarre le démon à chaque arrêt avec un délai de 3 secondes. Il n’existe pas de liste d’autorisation des codes de sortie, donc un démon qui échoue rapidement à cause d’une configuration invalide redémarrera en boucle ; corrigez la configuration et exécutez systemctl --user restart zeroclaw plutôt que de compter sur l’abandon du service.

Sur macOS, le LaunchAgent (~/Library/LaunchAgents/com.zeroclaw.daemon.plist) définit RunAtLoad et KeepAlive à true, de sorte que launchd maintient le démon en cours d’exécution et le relance chaque fois qu’il se termine.

Sous Windows, zeroclaw service install enregistre une tâche du Planificateur de tâches déclenchée ONLOGON au niveau d’exécution LIMITED. Elle démarre le démon à l’ouverture de session ; elle n’ajoute pas de stratégie de redémarrage automatique en cas d’échec.

Arrêt gracieux

Sur Unix, le daemon intercepte SIGINT et SIGTERM ; sur Windows, il intercepte Ctrl+C (ctrl_c). Chacun de ces signaux déclenche un arrêt propre : le daemon arrête son serveur de canaux et l’écouteur de la passerelle, puis se termine.

SIGHUP est ignoré (le démon continue de s’exécuter). Un rechargement demandé via le point de terminaison /admin/reload redémarre la boucle du démon sur place plutôt que de quitter.

La mémoire de conversation et l’état de session sont écrits dans SQLite de manière incrémentale pendant le fonctionnement, et non mis en tampon jusqu’à l’arrêt, donc un arrêt propre ne dépend pas d’une étape de vidage (flush). Les reçus d’outils sont des jetons HMAC intégrés dans la conversation, et non un journal séparé sur disque. Un SIGKILL brutal ignore la fermeture propre du canal mais ne corrompt pas la mémoire déjà validée ; seul un tour d’agent en cours d’écriture est perdu.

Démarrage manuel pour le débogage

Ignorer le service et exécuter le démon directement :

zeroclaw service stop     # libérer le port de la passerelle si le service est en cours d'exécution
zeroclaw daemon

zeroclaw daemon s’exécute au premier plan, journalise sur stderr, et est le même processus que celui exécuté par le service, simplement sans l’enveloppe du service. Utile lorsque :

• Diagnostic des échecs de démarrage que le service avale
• Exécution sous gdb / lldb
• Tester une modification de configuration avant de la valider

Terminer avec Ctrl-C, mêmes sémantiques d’arrêt progressif que SIGTERM.

Limites de ressources

Linux : systemd

Ajouter à un drop-in :

systemctl --user edit zeroclaw.service

[Service]
MemoryMax=2G
CPUQuota=200%            # two cores
LimitNOFILE=16384        # if opening many channel sockets

Recharger et redémarrer :

systemctl --user daemon-reload
systemctl --user restart zeroclaw

macOS : launchd

Modifiez ~/Library/LaunchAgents/com.zeroclaw.daemon.plist :

<key>SoftResourceLimits</key>
<dict>
  <key>NumberOfFiles</key>
  <integer>16384</integer>
</dict>

Décharger + charger le plist pour appliquer :

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

Docker

Composer :

services:
  zeroclaw:
    image: ghcr.io/zeroclaw-labs/zeroclaw:latest
    limite_mémoire: 2g
    cpus: 2.0
    limites de ressources:
      pas de fichier: 16384

Exécution de plusieurs espaces de travail

Chaque démon ZeroClaw possède un répertoire de configuration (qui contient son répertoire data/). Pour en exécuter deux côte à côte, attribuez à chacun son propre répertoire de configuration via --config-dir (ou la variable d’environnement ZEROCLAW_CONFIG_DIR) :

zeroclaw --config-dir ~/.zeroclaw-home daemon
zeroclaw --config-dir ~/.zeroclaw-work daemon

Chaque instance lit sa propre configuration, son propre répertoire data/ (mémoire, sessions), son propre port de passerelle (défini par configuration) et ses propres liaisons de canaux. La mémoire reste séparée ; un bot Telegram dans un répertoire de configuration ne connaît pas l’autre.

zeroclaw service install installe toujours une seule unité pointant vers le répertoire de configuration par défaut ; il n’a aucun indicateur permettant de nommer ou de paramétrer les instances. Pour en exécuter plusieurs en tant que service persistant, rédigez manuellement un second fichier d’unité (copiez ~/.config/systemd/user/zeroclaw.service sous un nouveau nom) dont le ExecStart passe --config-dir <dir>, puis activez-le séparément.

Ne pointez pas deux démons vers le même répertoire de configuration. SQLite n’accepte qu’un seul écrivain ; le second échouera au démarrage.

Observer les redémarrages et les plantages

# Linux
journalctl --user -u zeroclaw --since Il y a 1 jour | grep -E 'Démarré|Arrêté|Échoué'

# macOS
log show --predicate 'process == "zeroclaw"' --last 1d | grep -E 'démarrer|arrêter|erreur'

Si vous constatez des redémarrages répétés, activez la journalisation de débogage (RUST_LOG=debug via le paramètre Environment= du fichier unit) et laissez un nouveau crash se produire pour capturer la trace complète.

Voir aussi

• Configuration → Gestion des services
• Journal et observabilité
• Dépannage