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

The gateway exposes a public component liveness snapshot at /health; detailed component errors remain available through the authenticated diagnostic routes /api/health and /api/status. Channels, providers, and other long-running components register themselves in the components map as they start, report OK, or error.

Wait, I need to correct my previous reply: the text above is the source string returned unchanged, which is wrong for a translation task. Here is the French translation:

La passerelle expose un instantané public de vivacité des composants à l’adresse /health ; les erreurs détaillées des composants restent accessibles via les routes de diagnostic authentifiées /api/health et /api/status. Les canaux, les fournisseurs et les autres composants de longue durée s’enregistrent eux-mêmes dans la table components au démarrage, signalent OK ou signalent 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": "…", "restart_count": 0},
      "channel:matrix":   {"statut": "erreur", "updated_at": "…", "last_ok": "…", "restart_count": 3}
    }
  }
}

Chaque composant de la réponse publique /health contient status (starting / ok / error), updated_at, last_ok et restart_count. Surveillez status: "error" et une valeur de restart_count qui augmente. La réponse publique omet last_error ; utilisez /api/health ou /api/status avec l’authentification API configurée pour inspecter les erreurs détaillées des composants.

Un canal affiche starting avec un last_ok nul jusqu’à ce qu’il confirme pouvoir réellement joindre son service, et non simplement jusqu’au démarrage de son écouteur. Certains canaux rapportent ce qu’ils ont observé lors de leurs échanges avec le service : un écouteur en cours d’exécution qui n’a jamais réalisé d’échange complet reste donc à starting au lieu de passer à ok, et un canal dont les appels échouent affiche error. Un canal redémarré sous un alias ayant précédemment signalé ok repasse à starting jusqu’à ce qu’il produise son propre échange réussi. Un canal de plugin (channel:plugin.<alias>) affiche error lorsque l’interrogation du plugin échoue et, si le plugin implémente une vérification de santé, suit le résultat de cette vérification, que l’hôte demande environ toutes les 30 secondes ; le périmètre de la vérification relève du plugin. Les canaux qui n’offrent pas un tel signal sont marqués ok tant que leur écouteur est en cours d’exécution.

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