Comment installer ZeroClaw : Guide de démarrage rapide convivial pour les débutants pour une alternative OpenClaw légère

Pourquoi ZeroClaw vaut la peine d’être installé

Si vous avez déjà installé un outil IA, regardé le binaire atterrir dans votre « PATH », et n’aviez toujours aucune preuve qu’il pouvait atteindre un modèle, comprendre son espace de travail ou répondre en toute sécurité, vous comprenez déjà le problème que ce guide résout. Une installation terminée prouve seulement que les fichiers ont été copiés. Elle ne prouve pas que le runtime de l’agent est utilisable.

C’est là que ZeroClaw devient intéressant. C’est un runtime d’agent IA léger construit autour d’un seul binaire Rust, avec support pour les fournisseurs de modèles hébergés au lieu d’une pile locale lourde dès le premier jour. En pratique, cela signifie que c’est plus proche d’un « runtime contrôlé d’utilisation d’outils » que d’un « chatbot dans un terminal ». Pour les lecteurs curieux de l’angle « alternative OpenClaw », l’attrait pratique n’est pas le battage médiatique ou les benchmarks. C’est l’histoire d’installation plus légère, le poids des dépendances réduit, et le fait que tester cela sur un VPS Ubuntu semble gérable au lieu de se transformer en un projet d’infrastructure complet.

Cet article reste étroitement concentré sur un résultat : installer ZeroClaw, exécuter « zeroclaw onboard », vérifier une première session CLI sûre, et repartir avec une idée réaliste de ce qu’il faut essayer ensuite. C’est le bon premier jalon pour une procédure pas à pas VPS conviviale pour les débutants, car « fonctionner » devrait signifier une première réponse ancrée que vous pouvez vérifier, pas une longue visite des fonctionnalités.

📝 Remarque : Ce guide prouve la première utilisation CLI fonctionnelle. Ce n’est pas un guide de déploiement en production, et il n’essaie pas de couvrir Docker, les passerelles publiques ou les services en arrière-plan

Ce qu’est ZeroClaw — en termes simples

ZeroClaw est mieux compris comme un runtime d’agent que comme « un chatbot IA ». Le modèle n’est qu’une partie du système. ZeroClaw est la couche qui connecte un compte fournisseur, un choix de modèle, un profil d’agent et un espace de travail délimité pour que l’outil puisse faire plus que répondre à une seule invite isolée.

Les quatre termes ci-dessous sont ceux qui importent le plus dans ce tutoriel :

Cette idée d’espace de travail compte plus qu’il n’y paraît. Dans cet article, l’espace de travail est la pièce dans laquelle l’agent est autorisé à travailler. C’est pourquoi installer ZeroClaw n’est pas la même chose que configurer ZeroClaw : le binaire peut exister sur le disque tandis que le fournisseur, le modèle, l’alias et l’espace de travail manquent toujours ou sont mal câblés.

📝 Remarque : Une installation réussie n’est que la moitié de l’histoire. Le jalon significatif est une configuration fonctionnelle sous ~/.zeroclaw qui peut atteindre un fournisseur et fonctionner à l’intérieur d’un espace de travail visible.

C’est aussi la façon la plus claire d’expliquer pourquoi certaines personnes considèrent ZeroClaw comme une alternative OpenClaw sans forcer une comparaison complète. La valeur n’est pas « OpenClaw réécrit en Rust », et ce guide ne le traite pas de cette façon. La valeur est une posture d’auto-hébergement plus légère, la flexibilité des fournisseurs et un runtime à binaire unique qui est facile à essayer sur un VPS.

Les bons premiers cas d’utilisation sont tout aussi ancrés : résumer une copie de repo sûre, expliquer un fichier de configuration, gérer une tâche d’assistant en lecture seule à l’intérieur d’un espace de travail à faible risque, ou l’utiliser comme assistant délimité pour les opérateurs qui veulent de la visibilité avant d’autoriser des changements réels.

Avant d’installer : ligne de base Ubuntu, prérequis et sécurité

Avant d’exécuter le programme d’installation, passez une minute à confirmer que le VPS est vraiment un bon choix pour le chemin que cet article utilise. Les exigences minimales sont simples : accès SSH à un VPS Ubuntu, curl, un compte fournisseur hébergé avec une clé API, et une machine ou un espace de travail à faible risque pour la première session.

Exécutez d’abord les vérifications ci-dessous. Dans la série de validation affichée dans les captures d’écran, elles ont renvoyé Ubuntu 24.04.4 LTS (Noble Numbat), x86_64, et /usr/bin/curl. C’est suffisant pour confirmer la ligne de base du guide sans prétendre que chaque serveur renverra une sortie identique.

cat /etc/os-release

uname -m
command -v curl

Pour l’exemple de fournisseur hébergé, OpenRouter est le choix par défaut le plus propre car il garde la procédure pas à pas VPS conviviale et évite la configuration du modèle local sur le serveur. Si vous utilisez déjà un autre fournisseur supporté, c’est bien, mais ayez la clé API prête avant que zeroclaw onboard commence à poser des questions. L’objectif ici est le premier succès, pas le shopping de fournisseurs, donc un chemin hébergé propre est mieux que d’essayer d’évaluer chaque fournisseur dans la même séance.

ZeroClaw supporte à la fois les chemins d’installation précompilée et source. Pensez à la route précompilée comme un appareil prêt à l’emploi et à la route source comme un kit à construire soi-même. Les deux sont légitimes, mais ils servent des lecteurs différents. Pour ce démarrage rapide, l’important est de comprendre la différence maintenant et de faire la recommandation réelle à l’étape d’installation.

⚠️ Avertissement : Utilisez cette liste de contrôle de première exécution avant de continuer :

• restez dans un espace de travail à faible risque
• conservez le comportement supervisé par défaut
• évitez l’exposition publique et les données de production
• rendez la première tâche en lecture seule à dessein

Installer ZeroClaw avec le script officiel

Avec la vérification préalable terminée, utilisez le programme d’installation officiel comme chemin principal. C’est la route supportée la plus courte pour un démarrage rapide VPS Ubuntu :

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash

Sur ce chemin d’installation, le script s’exécute de manière non interactive et prend automatiquement le chemin de la version précompilée. Dans la série de validation pour ce guide, il a détecté la cible Linux, téléchargé le tarball de la version GitHub correspondante, vérifié la somme de contrôle, installé les ressources du tableau de bord web sous ~/.local/share/zeroclaw/web/dist, et placé le binaire zeroclaw dans ~/.cargo/bin. Parce que les captures d’écran ont été prises à partir du compte root, les chemins concrets affichés sont /root/.local/share/zeroclaw/web/dist, /root/.cargo/bin/zeroclaw, et /root/.bashrc ; sur un compte utilisateur régulier, attendez la même disposition sous votre propre répertoire personnel.

Ce chemin rapide n’est pas un raccourci ou une installation moins officielle. C’est la route de démarrage rapide normale pour le public pour lequel ce guide est écrit : téléchargez la version correspondante, vérifiez-la, et placez le binaire dans ~/.cargo/bin/zeroclaw. Si vous voulez intentionnellement une compilation source, utilisez plutôt le chemin de clonage de repo ci-dessous au lieu de vous attendre à ce que ce flux d’installation s’arrête et offre un choix de compilation séparé.

💡 Conseil : Sur Linux, le problème post-installation le plus courant est PATH, pas l’installation elle-même. Suivez la suggestion du programme d’installation pour ajouter export PATH=”$HOME/.cargo/bin:$PATH” à votre profil shell et rechargez-le avec source ~/.bashrc (ou rouvrez le shell). Si vous avez seulement besoin d’un correctif temporaire pour la session actuelle, utilisez l’export d’une ligne affichée ci-dessous.

Après que le binaire soit en place, le script se termine par un message de confirmation non interactif au lieu de lancer la configuration automatiquement. Dans la série de validation pour ce guide, ce message de fermeture pointait vers zeroclaw quickstart, mais le binaire installé « v0.7.5 » exposait onboard comme la sous-commande de configuration réelle dans zeroclaw –help. Il souligne également que zeroclaw daemon est le chemin pour le daemon toujours actif plus le tableau de bord web tandis que zeroclaw agent est le chemin du chat CLI ponctuel.

Pour cet article, continuez avec zeroclaw onboard ensuite. Cela garde la procédure pas à pas alignée sur la promesse réelle de l’article : première session d’agent fonctionnelle dans le terminal, pas l’appairage du tableau de bord ou le runtime toujours actif.

Si vous êtes soucieux de la sécurité et préférez inspecter le programme d’installation avant de l’exécuter, utilisez cette approche alternative :

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

Avant de penser aux fournisseurs ou aux invites, vérifiez que le binaire est appelable dans le shell :

zeroclaw --version

Si cela fonctionne, l’installation elle-même a réussi. Si le shell dit command not found, appliquez le correctif PATH temporaire ci-dessous et testez à nouveau :

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

Séparer cette étape de la configuration est important. Un zeroclaw –version fonctionnant vous dit que le problème d’installation est résolu avant de commencer à déboguer la configuration du fournisseur.

Exécutez zeroclaw onboard et vérifiez ce qu’il a créé

C’est le point où « installé » doit devenir « configuré ». Sur le chemin d’installation non interactif utilisé ci-dessus, le script ignore explicitement l’invite de configuration. Si le message du programme d’installation mentionne zeroclaw quickstart mais que le binaire ne le reconnaît pas, faites confiance à zeroclaw –help et démarrez l’assistant de première exécution avec :

zeroclaw onboard

L’assistant s’ouvre sur l’écran de l’espace de travail. Dans la série capturée, le chemin de l’espace de travail par défaut était /root/.zeroclaw/workspace. À moins que vous ayez une bonne raison de le déplacer, acceptez la valeur par défaut. Sur un compte non-root, la même disposition vivra sous votre propre répertoire personnel.

Pour cette procédure pas à pas CLI pour débutants, laissez les profils multi-espaces de travail désactivés. Les activer crée une mémoire, des secrets et des répertoires d’audit séparés par engagement, ce qui peut être utile plus tard, mais cela ajoute une surcharge mentale supplémentaire pour un premier test de fumée.

Sur l’écran du fournisseur, choisissez OpenRouter. La liste est beaucoup plus grande que ce qu’un guide pour débutants a besoin, ce qui est exactement pourquoi il aide à choisir un chemin hébergé propre et à s’y tenir pour la première exécution.

Collez votre clé API OpenRouter quand on vous le demande. L’entrée est masquée, et l’invite note explicitement que ZeroClaw stocke le secret via le trousseau du système d’exploitation quand c’est possible au lieu de vous demander de le coder en dur dans config.toml.

La liste des modèles OpenRouter est longue. Dans la série capturée, deepseek/deepseek-v4-pro a été sélectionné. Vous pouvez choisir un autre modèle OpenRouter actuel si vous préférez, mais le reste de cette procédure pas à pas suit cette sélection exacte.

Quand l’assistant vous demande des paramètres avancés, laissez-les désactivés pour ce guide. Les activer est pour les remplacements ciblés tels que la température, le délai d’attente, l’URL de base ou le protocole de câblage.

Sur l’écran Canaux, sélectionnez Terminé sans ajouter Discord, Telegram, Slack ou toute autre surface externe. Cela garde la première validation CLI uniquement. Vous pouvez ajouter des canaux plus tard une fois que le chemin de l’agent local fonctionne.

Pour la mémoire, choisissez SQLite avec recherche vectorielle (recommandé). C’est le meilleur choix par défaut ici car il garde tout local tout en vous donnant le support de la recherche hybride et des embeddings.

Laissez auto-save défini sur Oui pour que vos propres invites soient enregistrées comme historique de conversation. Si vous voulez plus tard un contrôle manuel plus strict, vous pouvez désactiver cela et sauvegarder la mémoire uniquement explicitement.

Laissez le contrôle du matériel désactivé. Cette configuration VPS n’a pas besoin de GPIO, de cartes tethérées USB ou de sondes de débogage.

Pour le fournisseur de tunnel public, gardez-le à aucun. Cela correspond à la posture de sécurité de cet article : aucune exposition publique lors du premier test de fumée.

Quand l’étape Personnalité dit qu’elle est déjà configurée, laissez Reconfigurer ? à Non. La personnalité par défaut est suffisante pour la validation de première exécution.

Ce qui importe ici n’est pas de mémoriser chaque panneau de l’assistant. Ce qui importe est le chemin que les captures d’écran prouvent : espace de travail unique, fournisseur OpenRouter, entrée de clé API masquée, un choix de modèle concret, aucun remplacement avancé, aucun canal supplémentaire, mémoire SQLite locale, auto-save activé, matériel désactivé, aucun tunnel public, et aucune réécriture de personnalité. C’est plus que suffisant pour produire une première configuration CLI utilisable sous ~/.zeroclaw.

Après la fin de l’intégration, confirmez que le répertoire de configuration principal et l’espace de travail existent :

Si la série d’intégration se termine correctement, vous devriez revenir au shell avec un message de configuration chargée comme celui ci-dessous :

ls ~/.zeroclaw
ls ~/.zeroclaw/workspace

Dans la série capturée, ~/.zeroclaw contenait config.toml et workspace/, et l’espace de travail lui-même montrait IDENTITY.md et SOUL.md.

C’est déjà suffisant pour prouver que ZeroClaw a maintenant une salle d’opération, pas seulement un binaire installé. C’est aussi pourquoi l’analogie de l’espace de travail est utile : vous vérifiez que la pièce existe, que l’agent a du contexte à l’intérieur, et que la configuration a dépassé « le programme d’installation a terminé ». Les fichiers tels que IDENTITY.md et SOUL.md ne sont pas décoratifs. Ils font partie du contexte que ZeroClaw utilise pour comprendre comment il devrait se comporter à l’intérieur de cet espace de travail.

Avant la première invite en direct, exécutez une vérification de santé compacte :

zeroclaw status

zeroclaw doctor

Pour ce premier test de fumée CLI uniquement, ne paniquez pas si zeroclaw doctor n’est pas parfaitement propre. Dans la série capturée, les vérifications importantes ont réussi : le fichier de configuration a été trouvé, le fournisseur openrouter était valide, la clé API était configurée, le modèle par défaut était défini, et l’espace de travail existait et était accessible en écriture.

Les avertissements et erreurs restants ne sont pas critiques pour un chat terminal : « aucun canal configuré » est attendu car la procédure pas à pas a intentionnellement ignoré Discord, Telegram et d’autres canaux externes ; AGENTS.md not found (optional) est explicitement non bloquant ; daemon_state.json not found signifie seulement que le daemon toujours actif n’est pas encore en cours d’exécution ; et la plainte de liste de modèles en direct OpenRouter est mieux lue comme une limitation de sonde que comme preuve que la configuration du fournisseur a échoué, d’autant plus que la sortie rapporte toujours openrouter: 344 models.

grep -E 'default_provider|default_model|[agents.|[risk_profiles.' ~/.zeroclaw/config.toml

Le signal de succès ici est opérationnel, pas cosmétique. zeroclaw status est la source de vérité la plus claire pour le résumé du runtime actif, zeroclaw doctor vous dit si quelque chose d’important est cassé, et la sortie grep est mieux traitée comme un coup d’œil approximatif aux entrées de configuration liées au fournisseur/modèle plutôt que comme une validation parfaite. Attendez-vous à ce que la formulation et les correspondances exactes varient selon la version. Vous ne cherchez pas un mur de texte parfaitement vert. Vous cherchez l’absence de bloqueurs de première exécution et la présence de données de configuration réelles.

📝 Remarque : config.toml peut ne pas afficher votre clé API en texte brut. C’est peut-être normal. Dans la série d’intégration capturée, l’invite de clé API a explicitement dit que le secret serait stocké via le trousseau du système d’exploitation quand c’est possible, donc « aucune clé visible en texte brut dans le fichier TOML » n’est pas la même chose que « la configuration a échoué ».

Démarrez le premier chat CLI sûr

Avec la configuration et l’espace de travail en place, lancez l’agent en mode interactif :

zeroclaw agent

Dans la série capturée, ZeroClaw a chargé la configuration, initialisé la mémoire sauvegardée par SQLite, imprimé la bannière du mode interactif, et s’est arrêté à l’invite >. L’objectif n’est pas de démarrer une démo flashy. L’objectif est de prouver la connectivité de bout en bout, la configuration valide et la conscience de l’espace de travail ancrée en une seule étape à faible risque. Un test en lecture seule vous donne un signal beaucoup plus utile à ce stade qu’une invite « regardez ce qu’il peut faire » capable d’écriture.

Pour la première invite, utilisez cette vérification exacte en lecture seule :

tell me your current workspace path, list the top-level files you can see there, and briefly explain what each one is for. Do not create, edit, or delete anything.

Parce que le runtime est en mode supervisé, la première réponse utile peut nécessiter une approbation d’outil. Dans la série capturée, ZeroClaw a demandé d’exécuter une commande shell en lecture seule : “pwd && echo “—-” && ls -la”

C’est exactement le type de commande que vous voulez pour ce test de fumée : il imprime le chemin de l’espace de travail et liste le contenu de haut niveau sans rien changer. Approuvez-le avec Y pour un oui unique. Vous pouvez également le refuser avec N, mais alors l’agent perdrait le moyen le plus facile de répondre à partir de l’état du système de fichiers réel au lieu de deviner.

📝 Remarque : Vous pouvez également voir un avertissement de suivi des coûts pour le modèle OpenRouter sélectionné avant l’invite d’approbation. Dans la série capturée, ZeroClaw a averti qu’aucune entrée de tarification n’était définie pour openrouter/deepseek/deepseek-v4-pro. Cela ne bloque pas le chat lui-même. Cela signifie seulement que l’utilisation des jetons peut être enregistrée avec un coût nul jusqu’à ce que vous définissiez explicitement la tarification du modèle.

Cette invite est forte car elle teste trois choses à la fois. Premièrement, ZeroClaw doit atteindre le fournisseur et obtenir une réponse. Deuxièmement, l’agent doit comprendre l’espace de travail configuré. Troisièmement, la réponse doit être suffisamment spécifique pour que vous puissiez la comparer à ce qui est réellement sur le disque. En d’autres termes, cela prouve que l’agent reste dans la pièce qui lui a été donnée.

Une bonne première réponse devrait répondre à quatre conditions :

• aucune erreur d’authentification ou de fournisseur
• aucune défaillance « config not found » ou modèle manquant
• le chemin de l’espace de travail correct apparaît dans la réponse
• les fichiers de haut niveau réels sont nommés, sans prétention que quelque chose a été changé

Si vous voulez une autre façon d’invoquer l’agent, vous pouvez envoyer la même invite comme une commande ponctuelle au lieu de rester dans la session interactive. Traitez cela comme optionnel, pas comme la procédure pas à pas principale. Le chemin interactif est toujours la meilleure première expérience car il rend le runtime observable au lieu de magique.

zeroclaw agent -m "tell me your current workspace path, list the top-level files you can see there, and briefly explain what each one is for. Do not create, edit, or delete anything."

Que faire ensuite une fois que ZeroClaw fonctionne

Le bon prochain mouvement n’est pas d’activer chaque fonctionnalité que vous pouvez trouver. C’est d’ajouter une couche contrôlée à la fois, pour que vous sachiez toujours quel changement a introduit un nouveau risque ou une nouvelle friction.

💡 Conseil : Une fois que le premier chat sûr fonctionne, conservez la même discipline pour la phase suivante. Passez d’abord à une copie de repo sûre ou à un répertoire de notes, gardez les tâches en lecture seule si possible, et développez les privilèges uniquement après que le flux de travail de base semble prévisible.

Les bonnes tâches de suivi sont ennuyeuses à dessein : résumer un README, expliquer un fichier de configuration, ou lister les idées de nettoyage sans rien changer. Ce type de travail est un signal élevé car il utilise le même runtime que vous venez de valider, mais il ne vous force pas à accéder en écriture avant de faire confiance à l’outil. Si vous voulez un meilleur premier espace de travail réel, utilisez une copie de repo sûre, un répertoire de notes de staging ou un petit dossier de docs interne plutôt que n’importe quoi en production.

Les bons prochains pas, dans l’ordre, ressemblent à ceci :

• pointez ZeroClaw vers une copie de repo sûre ou un répertoire de notes
• essayez une tâche d’assistant en lecture seule
• comparez les fournisseurs seulement après que le flux de travail de base semble stable
• regardez les services, les canaux ou Docker plus tard comme