Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Opérations : Vue d’ensemble

Comment exécuter ZeroClaw en production. L’empreinte est volontairement réduite : un binaire, un fichier de configuration et une racine d’installation avec quelques dépôts d’exécution. La plupart des « opérations » se résument à « systemd et journald ».

Cette section couvre :

La forme d’un déploiement

Une installation typique de ZeroClaw en mode toujours actif est :

zeroclaw service                          — systemd / launchctl / Windows Service
└── zeroclaw daemon                       — the single long-running process
    ├── gateway listener  :42617          — REST / WebSocket / webhook intake
    ├── channel pollers                   — Telegram, IMAP, Nostr relays (outbound poll)
    ├── channel listeners                 — Discord / Slack / Matrix / WebSocket (inbound stream)
    ├── cron scheduler                    — scheduled SOPs and jobs
    └── agent loop  (one per session)     — provider call + tool execution
                                            ▲ driven by any listener, poller,
                                              gateway request, or cron fire

on disk (everything but the binary can move)
├── ~/.zeroclaw/config.toml               — configuration
├── ~/.zeroclaw/.secret_key               — master key for the encrypted secrets store
└── ~/.zeroclaw/data/                     — runtime state
    ├── memory/                           — agent memory backend
    ├── sessions/                         — per-session conversation stores
    └── state/                            — scheduler, cost, health, misc runtime state

logs                                      — journald / launchctl / Windows Event Log (platform-native)

Tout, à l’exception du binaire, peut être déplacé. Le répertoire de données par défaut est ~/.zeroclaw/data/ (l’ancien nom ~/.zeroclaw/workspace/ est toujours accepté) ; les chemins de configuration sont résolus en fonction de l’environnement (Homebrew vs. bootstrap vs. XDG), et les destinations de journaux sont spécifiques à la plateforme par défaut. Pour la liste complète des magasins, consultez État et persistance de l’exécution.

Quoi surveiller

Quatre signaux sont importants :

1. Liveness du service

Le processus est-il en cours d’exécution ?

Linux

systemctl --user is-active zeroclaw

macOS

launchctl list | grep -c com.zeroclaw.daemon

Windows

schtasks /Query /TN "ZeroClaw Daemon" /FO LIST | findstr Status

S’il redémarre de manière répétée, consultez Dépannage → Le daemon redémarre continuellement.

2. Santé des canaux et des composants

La passerelle expose un instantané de l’état de santé des composants à /health (public, sans secrets) et /api/health (authentifié). Les canaux, les fournisseurs et les autres composants à exécution longue s’enregistrent dans la map components au moment de leur démarrage, lorsqu’ils signalent un état OK ou une erreur.

sh

curl -s http://localhost:42617/health | jq

{
  "statut": "ok",
  "paired": true,
  "require_pairing": true,
  runtime: {
    "pid": 4821,
    "updated_at": "2026-06-08T09:00:00+00:00",
    "uptime_seconds": 3600,
    composants: {
      "channel:telegram": {"statut": "ok", "updated_at": "…", "last_ok": "…", "last_error": null, "restart_count": 0},
      "channel:matrix":   {"statut": "erreur", "updated_at": "…", "last_ok": "…", "last_error": "401 Non autorisé", "restart_count": 3}
    }
  }
}

Chaque composant comporte status (starting / ok / error), last_ok, last_error et restart_count. Surveillez status: "error" et un restart_count qui augmente.

Un canal lit starting avec un last_ok à null jusqu’à ce qu’il confirme qu’il peut réellement atteindre son service, et non simplement jusqu’au démarrage de son écouteur. Certains canaux signalent ce qu’ils ont observé en communiquant avec le service ; ainsi, un écouteur qui fonctionne mais n’a jamais terminé d’échange reste starting plutôt que ok, et celui dont les appels échouent lit error. Un canal qui redémarre sous un alias ayant précédemment signalé ok revient à starting jusqu’à produire son propre échange réussi. Les canaux qui n’offrent aucun signal de ce type sont marqués ok aussi longtemps que leur écouteur fonctionne.

3. Fiabilité du fournisseur

Les fournisseurs apparaissent comme des composants dans le même instantané /health. Pour les signaux au niveau des requêtes (latence, taux de réussite, nombre de tokens), collectez /metrics (voir ci-dessous) et lisez zeroclaw_llm_requests_total et zeroclaw_request_latency_seconds.

4. Volume d’appels d’outils et métriques

/metrics renvoie le format d’exposition texte Prometheus. Il nécessite [observability] backend = "prometheus" dans la configuration ; sans cela, le point de terminaison renvoie une indication d’une seule ligne « backend not enabled ».

sh

curl -s http://localhost:42617/metrics

zeroclaw_tool_calls_total{success="true",tool="shell"} 342
zeroclaw_tool_calls_total{success="false",tool="shell"} 6
zeroclaw_tool_calls_total{success="true",tool="file_write"} 89

Le compteur zeroclaw_tool_calls_total est étiqueté par tool et success ("true"/"false"). Une augmentation du nombre de success="false" pour un outil mérite attention : il peut s’agir d’un blocage de politique, d’un agent défaillant ou d’un outil instable. D’autres séries utiles incluent zeroclaw_llm_requests_total, zeroclaw_errors_total, zeroclaw_active_sessions et zeroclaw_tokens_input_total / zeroclaw_tokens_output_total.

Capacité

Une seule instance de ZeroClaw peut gérer :

  • Plusieurs conversations simultanées sur tous les canaux
  • Appels d’outils à la vitesse que le fournisseur et le bac à sable le permettent
  • Boucles d’agent à longue durée d’exécution (chaînes d’outils de 20+ appels)

Mettez à l’échelle latéralement en exécutant une instance par espace de travail. N’essayez pas d’exécuter deux daemons sur le même espace de travail : le modèle à écrivain unique de SQLite produira une contention de verrous et, à terme, une corruption.

Pour l’hébergement multi-locataire, consultez la proposition dans #2765 (fermée, historique, l’architecture pour le routage multi-espaces de travail en cours de processus).

Sauvegardes

Quoi sauvegarder :

  • ~/.zeroclaw/data/memory/*.db : mémoire de conversation SQLite (brain.db, plus audit.db)
  • ~/.zeroclaw/data/sessions/ : état de session persisté
  • ~/.zeroclaw/.secret_key : clé maîtresse du magasin de secrets chiffrés (si utilisé). Sans elle, les secrets chiffrés de la configuration sont irrécupérables.

Une simple commande tar czf zeroclaw-$(date +%F).tar.gz ~/.zeroclaw couvre l’ensemble. Restic, borg ou Duplicacy fonctionnent parfaitement pour les sauvegardes incrémentales.

~/.zeroclaw/data/memory/response_cache.db est un cache de réponses LLM régénérable ; il peut être inclus sans risque dans une sauvegarde complète du répertoire ou exclu pour économiser de l’espace. Les reçus d’outils sont des jetons HMAC intégrés dans l’historique de conversation (voir Tool receipts), et non un journal sur disque, il n’y a donc rien de distinct à sauvegarder pour eux.

Mises à jour

Le service ne se met pas à jour automatiquement. Abonnez-vous au flux de versions (versions GitHub ou le canal Discord #releases : voir Contributing → Communication). Cadence de mise à jour typique :

  1. Lire les notes de version
  2. Sauvegardez ~/.zeroclaw/
  3. Mettez à jour le binaire (brew upgrade, relance du bootstrap ou cargo install --force)
  4. zeroclaw service restart
  5. Vérifiez que le point de terminaison /health signale status: "ok" sans aucun composant en error

Si la nouvelle version nécessite des migrations de configuration, le journal de démarrage émet un avertissement et le binaire effectue généralement la migration automatiquement. Vérifiez zeroclaw config list pour contrôler les valeurs après la mise à jour, et zeroclaw config migrate pour appliquer manuellement les migrations de schéma en attente.

Voir aussi