Dépannage

Modes de défaillance courants, dans l’ordre dans lequel vous êtes susceptible de les rencontrer.

Première étape pour résoudre un problème :

zeroclaw doctor

Exécute une série de vérifications et affiche un résumé. La plupart des éléments qui suivent constituent la version détaillée de ce que doctor signale.

Pendant l’installation

cargo non trouvé

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Ou passez --prebuilt à install.sh / setup.bat pour ignorer Rust entièrement.

Dépendances de construction manquantes (Linux)

Installez la chaîne d’outils de base pour votre distribution, puis relancez ./install.sh :

sudo apt install build-essential pkg-config

sudo dnf group install development-tools && sudo dnf install pkg-config

sudo pacman -S base-devel

Liste complète par distribution : Configuration → Linux.

Générer des OOM sur des hôtes à faible RAM

La compilation de ZeroClaw depuis les sources est gourmande en mémoire, principalement lors de l’édition de liens finale. install.sh s’adapte déjà automatiquement à cette contrainte lorsqu’il compile depuis les sources :

Lorsque install.sh compile à partir des sources sous Linux, il lit MemTotal depuis /proc/meminfo et, sur les hôtes disposant de moins de 12 GiB de RAM, exporte CARGO_PROFILE_RELEASE_LTO=thin avant la compilation. Le LTO complet (la valeur par défaut de [profile.release]) peut dépasser 7 GB de RSS au pic lors de la passe de typage inter-crates et provoquer un OOM sur une carte à faible RAM ; le LTO thin échange une légère augmentation de la taille du binaire contre un pic de mémoire de compilation bien plus faible.

L’option ne s’applique que si vous n’avez pas déjà épinglé la variable. Remplacez explicitement l’une ou l’autre direction :

# Forcer le LTO « fat » même sur un hôte avec peu de RAM (binaire plus petit, consommation de RAM accrue à la compilation)
export CARGO_PROFILE_RELEASE_LTO=fat

# Forcer le thin LTO sur un hôte à RAM élevée (réduit la RAM de compilation)
export CARGO_PROFILE_RELEASE_LTO=fin

Si vous manquez toujours de mémoire, ou si vous ne compilez pas via install.sh :

1. Utiliser une version précompilée : ./install.sh --prebuilt ignore la chaîne d’outils et télécharge depuis GitHub Releases.
2. Effectuez une compilation croisée sur une machine plus puissante et copiez le binaire.
3. Choisissez un profil de compilation plus léger : cargo build --profile release-fast (plus de parallélisme de génération de code, édition de liens plus légère) ou --profile ci (thin LTO, le plus rapide/la plus faible consommation mémoire).
4. Sérialisez la compilation : CARGO_BUILD_JOBS=1 cargo build --release --locked.
5. Ajouter du swap (fonctionne pour la RAM, consomme de l’espace disque, vérifiez que vous disposez des deux).

Pour les spécificités du Raspberry Pi, consultez Configuration du Raspberry Pi → build.

La construction est très lente.

La pile E2EE de Matrix (matrix-sdk, ruma, vodozemac) et les dépendances natives TLS/crypto (aws-lc-sys, ring) constituent le principal coût. Désactivez-les si vous n’en avez pas besoin :

cargo build --release --locked --no-default-features --features "défaut-lean"

Ou vérifiez ce qui se passe :

cargo check --timings
# rapport à target/cargo-timings/cargo-timing.html

zeroclaw : commande introuvable après l’installation

cargo install place les binaires dans ~/.cargo/bin/. Ajoutez-le au PATH :

export PATH="$HOME/.cargo/bin:$PATH"

Persistez dans votre profil de shell.

Démarrage rapide

Quickstart n’écrasera pas une configuration existante

zeroclaw quickstart ne possède pas de drapeau --force, il laisse intentionnellement une installation existante intacte. Pour exécuter un quickstart à neuf sur une installation obsolète, supprimez le répertoire et recommencez :

rm -rf ~/.zeroclaw
zeroclaw quickstart

Ou, pour modifier un seul champ obsolète sans tout effacer, utilisez zeroclaw config set <key> <value> directement.

Installation Homebrew : incohérence du chemin de configuration

Les installations Homebrew privilégient $HOMEBREW_PREFIX/var/zeroclaw/ (afin que brew services fonctionne) tandis que le répertoire de configuration par défaut est ~/.zeroclaw/. Définissez ZEROCLAW_WORKSPACE sur le chemin Homebrew avant d’exécuter quickstart afin que les deux chemins correspondent :

export ZEROCLAW_WORKSPACE="$HOMEBREW_PREFIX/var/zeroclaw"
zeroclaw quickstart

Ou créez un lien symbolique une fois manuellement :

ln -s "$HOMEBREW_PREFIX/var/zeroclaw" ~/.zeroclaw

Exécution

L’authentification de l’abonnement OpenAI Codex avertit à propos de la configuration ou du streaming

Symptômes :

• L’agent model_provider = "openai.<alias>" pointe vers une entrée Codex, mais les exécutions semblent toujours mal configurées
• Le chargement de la configuration avertit en cas de champs de premier niveau inconnus comme api_key / api_url (ceux-ci doivent figurer dans l’entrée du fournisseur, pas à la racine du fichier)
• L’agent journalise provider streaming failed, falling back to non-streaming chat

Vérifications (remplacez <alias> par l’alias d’agent configuré dans [agents.<alias>]) :

Pour un abonnement OpenAI Codex, définissez requires_openai_auth = true sur l’alias du fournisseur et laissez api_key non défini ; le runtime utilise la connexion Codex enregistrée. Obtenez les identifiants d’abonnement via le flux de connexion propre au fournisseur. Consultez Provider Configuration → OAuth and subscription auth pour le modèle complet d’identifiants. Puis testez :

zeroclaw agent -a <alias> -m "bonjour"

Notes :

• requires_openai_auth = true sur l’alias (avec api_key non défini) sélectionne le chemin d’abonnement ; entourez-le de l’agent canonique et du profil de risque issus de l’exemple minimal fonctionnel.
• api_key / uri dans l’entrée d’alias ne sont nécessaires que pour les passerelles personnalisées compatibles OpenAI ou pour d’autres substitutions explicites de point de terminaison.
• L’avertissement de streaming désactivé n’est pas en soi un échec d’authentification ; ZeroClaw réessaie la requête en mode non-streaming.

Le daemon démarre, puis se termine immédiatement.

Vérifiez journald / les journaux de la plateforme (voir Logs et observabilité) pour l’erreur réelle. Causes courantes :

• Configuration invalide : zeroclaw config list pour afficher les valeurs résolues, zeroclaw config schema pour voir la structure attendue
• Conflit de port : un autre processus sur 42617 ; modifiez [gateway] port ou libérez le port
• Secrets manquants : le magasin de secrets chiffrés ne peut pas déchiffrer car le fichier de clé a disparu ; restaurez depuis une sauvegarde ou relancez l’onboarding

Le daemon redémarre continuellement

systemctl --user status zeroclaw affiche le dernier code de sortie. S’il s’agit d’une erreur de configuration, le service a cessé de redémarrer (code de sortie 2) et vous devez corriger la configuration. S’il s’agit d’une panic, l’unité tente de redémarrer toutes les 10 secondes.

Activer la journalisation de débogage et capturer la prochaine erreur :

zeroclaw service stop
RUST_LOG=débogage zeroclaw daemon

Passerelle inaccessible

curl -sv http://localhost:42617/health

Si la connexion est refusée : le daemon n’est pas en cours d’exécution, ou il est lié à une interface différente. Vérifiez l’hôte et le port [gateway] dans la configuration.

Si 403 / 401 : l’appairage n’est pas terminé ou le jeton a expiré. Exécutez à nouveau le processus d’appairage.

Chaînes

Telegram : terminé par une autre requête getUpdates

Deux processus interrogent le même jeton bot. Telegram n’autorise qu’un seul interrogateur à la fois.

Correction : arrêter tous les processus zeroclaw daemon / zeroclaw channel start utilisant ce jeton, sauf un.

Échecs d’authentification Discord / Slack

Les jetons Discord expirent si vous les régénérez dans le portail développeur. Les jetons de bot Slack n’expirent pas mais peuvent être révoqués. Vérifiez que le bot est toujours installé dans l’espace de travail/guild cible.

Pour l’un ou l’autre :

zeroclaw channel doctor

Le fan-in SOP n’est pas couvert par channel doctor

zeroclaw channel doctor construit des adaptateurs de transport sans le moteur SOP actif du daemon ni ses handles d’audit. Il peut vérifier les transports de canal classiques, mais ne prouve pas que le routage SOP de MQTT, du système de fichiers ou d’AMQP puisse démarrer une exécution. Pour ces sources, démarrez zeroclaw daemon avec l’environnement d’exécution SOP activé (sop.sops_dir défini sur une valeur non vide ; non défini par défaut, ce qui le désactive ; la valeur documentée est shared/sops), puis examinez la connexion à la source et les événements du journal SOP ingress. Un canal AMQP utilisant dispatch = "sop" ou "sop_and_agent_loop" échoue en mode fermé au démarrage du daemon lorsque les handles SOP sont indisponibles ; il est intentionnellement omis de la liste de travail de doctor dans cet état.

Matrix : « périphérique inconnu »

Si vous vous êtes reconnecté sans conserver les clés de l’appareil, le serveur d’hébergement voit un nouvel appareil qui n’a pas été vérifié. Vérifiez-le à nouveau depuis un autre client connecté, ou réinitialisez le magasin de clés :

rm -rf ~/.zeroclaw/workspace/matrix-crypto
# relancer le processus d'appariement au prochain démarrage de la chaîne

Arrêt du sondage IMAP

Le plus souvent un échec d’authentification, le fournisseur a effectué une rotation du mot de passe ou le mot de passe d’application a expiré. Vérifiez :

journalctl --user -u zeroclaw -n 200 | grep -i imap

Fournisseurs

“La connexion a expiré” vers Ollama

• Le démon Ollama n’est pas en cours d’exécution : systemctl status ollama (Linux), brew services list (macOS)
• URL incorrecte dans la config : depuis l’intérieur d’un conteneur, localhost:11434 n’atteint pas l’hôte ; utilisez host.docker.internal ou l’adresse IP LAN de l’hôte
• Pare-feu bloquant le port 11434, rare en local, courant sur les LAN partagés

Anthropic / OpenAI 401

Clé API invalide ou expirée. Régénérez-la dans le tableau de bord du fournisseur, mettez-la à jour dans [providers.models.<name>] api_key, puis redémarrez le service.

Si vous utilisez OAuth (sk-ant-oat*), le jeton OAuth a peut-être expiré. Les jetons émis par OAuth ont une durée de vie plus longue, mais pas infinie. Réauthentifiez-vous.

Outils

Commandes shell « bloquées par la politique »

Comportement attendu en autonomie Supervised pour les commandes inconnues. Soit :

• Approuvez en ligne lorsque vous y êtes invité.
• Ajoutez la commande à [autonomy] allowed_commands
• Augmentez l’autonomie à Full si vous faites confiance au contexte.

Voir Sécurité → Niveaux d’autonomie.

Les appels d’outils échouent dans le bac à sable Docker

• L’image de conteneur n’est pas téléchargée, exécutez docker pull <image> pour l’image que vous avez configurée sous [security.sandbox].image (par défaut : alpine:latest)
• Démon Docker injoignable depuis l’utilisateur ZeroClaw, vérifiez docker info
• L’outil nécessite un périphérique qui n’est pas transmis, étendez allow_devices

L’outil du navigateur se bloque lors de la première utilisation.

Playwright télécharge Chromium (~150 Mo) lors du premier lancement. Laissez-le terminer. S’il reste bloqué, vérifiez l’espace disque et la configuration du proxy.

Mode service

Service installé mais affiche « inactif »

zeroclaw service start
zeroclaw service status

Utilisez zeroclaw service logs pour suivre les journaux du service installé. Ajoutez --follow pour diffuser les nouvelles entrées ou --lines <count> pour modifier la quantité d’historique affichée. Si le wrapper n’est pas disponible ou si vous devez inspecter directement la plateforme, utilisez :

• Linux : journalctl --user -u zeroclaw.service -f
• macOS : log stream --predicate 'process == "zeroclaw"'
• Si vous exécutez zeroclaw daemon directement dans un terminal, utilisez cette sortie au premier plan plutôt que les commandes de journalisation du service.

Si cela réussit en mode interactif mais que le service meurt en arrière-plan, c’est presque toujours un problème de configuration ou de permissions, consultez le journal :

journalctl --user -u zeroclaw --since Il y a 5 minutes

Le service ne peut pas trouver la configuration

Le service et l’interface CLI peuvent résoudre la configuration différemment s’ils s’exécutent en tant qu’utilisateurs différents ou avec des variables d’environnement distinctes. Affichez de manière forcée le chemin que le démon voit :

zeroclaw config list

Si les chemins diffèrent entre zeroclaw config list (en tant que vous) et le service (en tant qu’utilisateur), soit :

• Définissez ZEROCLAW_CONFIG_DIR dans Environment= de l’unité de service.
• Exécutez le service comme vous (service utilisateur activé pour la persistance)
• Copiez ou créez un lien symbolique de la configuration vers le chemin attendu par le service.

Toujours bloqué ?

Collecter les diagnostics et ouvrir un ticket :

zeroclaw --version
zeroclaw doctor
zeroclaw channel doctor
journalctl --user -u zeroclaw --since Il y a 1 heure > zeroclaw-log.txt

Assainissez zeroclaw-log.txt (caviardez les jetons de canal si certains ont échappé au filtrage, ce qui ne devrait pas arriver) et joignez-le au ticket. Consultez Contributing → Communication pour savoir où.

Voir aussi

• Journal et observabilité
• Service & daemon
• Configuration → Gestion des services
• Référence → Config