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 ne prouve que des 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 qu’il est plus proche d’un “runtime contrôlé d’utilisation d’outils” qu’un “chatbot dans un terminal”. Pour les lecteurs curieux de l’angle “alternative OpenClaw”, l’attrait pratique n’est pas du battage médiatique ou des benchmarks. C’est l’histoire d’installation plus légère, le poids de dépendance inférieur, et le fait que le tester 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 partir 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 “fonctionnel” 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 se comprend mieux comme un agent runtime 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 en isolation.

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

Cette idée d’espace de travail est plus importante 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 encore ou sont mal configurés.

📝 Remarque : Une installation réussie n’est que la moitié de l’histoire. L’étape significative est une configuration fonctionnelle sous ~/.zeroclaw qui peut atteindre un fournisseur et fonctionner dans 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, une flexibilité des fournisseurs et un runtime binaire unique qui est facile à essayer sur un VPS.

Les bons premiers cas d’usage sont tout aussi concrets : résumer une copie de dépôt sûre, expliquer un fichier de configuration, gérer une tâche d’assistant en lecture seule dans 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 tout changement réel.

Avant l’installation : baseline Ubuntu, prérequis et sécurité

Avant d’exécuter l’installateur, prenez une minute pour confirmer que le VPS est vraiment adapté au chemin utilisé par cet article. Les exigences minimales sont simples : accès SSH à un VPS Ubuntu, curl, un compte auprès d’un fournisseur d’hébergement 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 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 baseline 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 d’hébergement, OpenRouter est le choix par défaut le plus propre car il maintient le VPS convivial et évite la configuration du modèle local sur le serveur. Si vous utilisez déjà un autre fournisseur pris en charge, c’est très bien, mais ayez la clé API prête avant que zeroclaw onboard ne commence à poser des questions. L’objectif ici est le premier succès, pas l’exploration des fournisseurs, donc un seul chemin d’hébergement propre est mieux que d’essayer d’évaluer chaque fournisseur dans la même session.

ZeroClaw prend en charge les chemins d’installation précompilés 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 intentionnellement en lecture seule

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 la plus courte prise en charge pour un démarrage rapide Ubuntu VPS :

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 validation pour ce guide, il a détecté la cible Linux, téléchargé la tarball de 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 normal, 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 auquel ce guide est destiné : télécharger la version correspondante, la vérifier, et placer le binaire dans ~/.cargo/bin/zeroclaw. Si vous voulez intentionnellement une compilation à partir des sources, utilisez plutôt le chemin de clonage du dépôt 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 montré ci-dessous.

Une fois le binaire en place, le script se termine par un message de confirmation non interactif au lieu de lancer la configuration automatiquement. Dans la 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 indique é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 de chat CLI ponctuel.

Pour cet article, continuez avec zeroclaw onboard ensuite. Cela maintient la procédure 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 l’exécution toujours active.

Si vous êtes conscient 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 indique que le problème du programme 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 moment 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 lancez l’assistant de première exécution avec :

zeroclaw onboard

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

Pour cette première procédure pas à pas CLI pour débutants, laissez les profils multi-espaces de travail désactivés. Les activer crée des répertoires de mémoire, de secrets et 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 cela aide à choisir un chemin hébergé propre et à s’y tenir pour la première exécution.

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

La liste des modèles OpenRouter est longue. Dans l’exécution 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.

Lorsque l’assistant vous demande des paramètres avancés, laissez-les désactivés pour ce guide. Les activer est destiné aux remplacements ciblés tels que la température, le délai d’expiration, l’URL de base ou le protocole de transmission.

Sur l’écran Canaux, sélectionnez Terminé sans ajouter Discord, Telegram, Slack ou toute autre surface externe. Cela garde la première validation en 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 défaut ici car cela garde tout en 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 ceci et ne sauvegarder la mémoire qu’explicitement.

Laissez le contrôle matériel désactivé. Cette configuration VPS n’a pas besoin de GPIO, de cartes attachées par 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 pendant le premier test de fumée.

Lorsque 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 compte ici, ce n’est pas de mémoriser chaque panneau de l’assistant. Ce qui compte, c’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, pas de remplacements avancés, pas de canaux supplémentaires, mémoire SQLite locale, auto-save activé, matériel désactivé, pas de tunnel public et pas de 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 l’exécution de l’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 l’exécution capturée, ~/.zeroclaw contenait config.toml et workspace/, et l’espace de travail lui-même affichait 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 salle existe, que l’agent a un contexte à l’intérieur, et que la configuration a dépassé « le programme d’installation a terminé ». Des 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 doit se comporter dans cet espace de travail.

Avant la première invite en direct, exécutez un contrôle de santé compact :

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 l’exécution capturée, les contrôles importants 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 non trouvé (optionnel) est explicitement non-bloquant ; daemon_state.json non trouvé signifie seulement que le daemon toujours actif n’est pas encore en cours d’exécution ; et la plainte concernant la liste des modèles en direct d’OpenRouter est mieux lue comme une limitation de sonde que comme une 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 en une ligne. Attendez-vous à ce que la formulation et les correspondances exactes varient selon la version. Vous ne cherchez pas un mur de texte vert parfait. 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 l’exécution d’intégration capturée, l’invite de clé API a explicitement déclaré que le secret serait stocké via le trousseau du système d’exploitation si possible, donc « aucune clé visible dans le fichier TOML » n’est pas la même chose que « la configuration a échoué ».

Démarrer le premier chat CLI sécurisé

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

zeroclaw agent

Dans l’exécution capturée, ZeroClaw a chargé la config, 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 spectaculaire. L’objectif est de prouver la connectivité de bout en bout, une configuration valide, et la conscience de l’espace de travail en une seule étape à faible risque. Un test en lecture seule vous donne un signal bien plus utile à ce stade qu’une invite capable en écriture « regardez ce qu’il peut faire ».

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 l’exécution 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 : elle imprime le chemin de l’espace de travail et liste le contenu de haut niveau sans rien modifier. Approuvez-la avec Y pour un oui unique. Vous pourriez aussi la refuser avec N, mais alors l’agent perdrait le moyen le plus facile de répondre à partir de l’état réel du système de fichiers au lieu de deviner.

📝 Note : Vous pouvez aussi voir un avertissement de suivi des coûts pour le modèle OpenRouter sélectionné avant l’invite d’approbation. Dans l’exécution 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 tokens 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 parce qu’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 assez spécifique pour que vous puissiez la comparer à ce qui se trouve 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 doit répondre à quatre conditions :

• aucune erreur d’authentification ou de fournisseur
• aucune erreur « config non trouvée » ou modèle manquant
• le chemin d’espace de travail correct apparaît dans la réponse
• les fichiers réels de haut niveau sont nommés, sans prétendre que quoi que ce soit a été modifié

Si vous voulez une autre façon d’invoquer l’agent, vous pouvez envoyer la même invite comme commande unique 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 parce qu’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, afin que vous sachiez toujours quel changement a introduit un nouveau risque ou une nouvelle friction.

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

Les bonnes tâches de suivi sont volontairement ennuyeuses : résumer un README, expliquer un fichier de configuration, ou lister des idées de nettoyage sans rien changer. Ce type de travail est de haut signal 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 dépôt sécurisée, 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 :

• pointer ZeroClaw vers une copie de dépôt sécurisée ou un répertoire de notes
• essayer une tâche d’aide en lecture seule
• comparer les fournisseurs uniquement après que le flux de travail de base semble stable
• regarder les services, les canaux, ou Docker plus tard comme des projets séparés

Si vous voulez comparer les fournisseurs plus tard, faites-le après que le flux de travail de base soit stable. Si vous voulez la prochaine étape d’infrastructure après le succès CLI, ce sont les commandes qui valent la peine d’être connues :

zeroclaw service install
zeroclaw service start
zeroclaw service status

C’est le point où cet article devrait s’arrêter et le sujet suivant devrait commencer. La gestion des services, le déploiement Docker, les passerelles publiques, les canaux de messagerie, et le renforcement de la sécurité plus approfondi méritent leurs propres procédures pas à pas.

Si ce premier test de fumée a été utile, un VPS Ubuntu d’AlexHost est un endroit naturel pour continuer à expérimenter avec un runtime d’agent léger sans transformer le jour un en un projet de plateforme complet. La bonne façon de continuer est vers l’extérieur, pas latéralement : utilisez la documentation officielle de configuration, de service, de fournisseur et de sécurité quand vous êtes prêt pour la couche suivante.

Conclusion : de curieux à opérationnel

Le résultat important n’est pas que ZeroClaw soit installé. Le résultat important est qu’il a répondu en toute sécurité à partir d’une première session vérifiée sur le VPS. Cela signifie que la ligne de base Ubuntu a été validée, l’installateur a fonctionné, « zeroclaw onboard » s’est terminé, la configuration et l’espace de travail ont été créés, les contrôles de santé semblaient corrects, et la première réponse en lecture seule est revenue ancrée dans un contexte d’espace de travail réel.

C’est un point d’arrêt significatif. Gardez vos premières expériences petites, supervisées et observables, puis développez une couche à la fois vers les services, les limites de sécurité plus strictes ou les intégrations de canaux quand vous en avez réellement besoin. Pour un démarrage rapide Ubuntu VPS initial, la confiance contrôlée est la victoire. Vous n’avez pas besoin de quitter cet article avec une pile d’automatisation complète. Vous devez le quitter en sachant que le runtime fonctionne, la limite de sécurité est intacte, et l’étape suivante est votre choix plutôt qu’une supposition.