2026 — Guide complet d'installation et de configuration OpenClaw : tutoriel pas à pas de zéro à la mise en service

2. Points de friction

1. Limites : les tutoriels s'arrêtent à « démarrage réussi ». Une bannière de bienvenue dans le terminal ne signifie pas que le modèle est connecté, que les outils fichiers fonctionnent ou que la passerelle reçoit des messages. OpenClaw n'est vraiment utilisable que lorsque dépendances et versions Node, onboard + connectivité modèle, passerelle sur 18789, accès Dashboard, périmètres de permissions, journaux traçables et un cas à faible risque passent tous.
2. Coût caché : clés et chemins éparpillés. Clés API seulement dans des notes, openclaw.json5 désynchronisé du .env, workspace pointant vers tout le répertoire personnel — une erreur peut réécrire des clés SSH ou un dépôt de production.
3. Stabilité et audit : on ne sait pas où sont les journaux. Les réinstallations à l'aveugle effacent les indices dans ~/.openclaw/logs/errors.log ; sans sauvegarde, impossible de revenir en arrière après une mise à jour.

3. Préparation avant installation : checklist Mac et environnement

Objectif : éviter de découvrir un problème réseau, Git ou disque en plein milieu de l'installation. Réussite : chaque point ci-dessous est coché avant d'exécuter le script d'installation.

• OS : macOS 12+ (Intel ou Apple Silicon ; Apple Silicon est pratique pour l'inférence locale, les modèles cloud suivent la doc du fournisseur).
• Git : l'installateur officiel suppose un réseau stable et un compte fournisseur de modèle ; git --version ≥ 2.30 recommandé. Sans Git : Xcode Command Line Tools ou brew install git.
• Réseau : accès au script d'installation (GitHub raw) et à l'API du fournisseur LLM ; définir HTTPS_PROXY tôt derrière un proxy d'entreprise.
• Disque : l'installateur peut tirer Python 3.11, Node v22, ripgrep, ffmpeg et des dépôts — réserver ≥ 2 Go libres (plutôt 1,5–3 Go avec le cache Skills ; confirmer dans la doc actuelle).
• Permissions : installation personnelle sans sudo ; en root, chemins possibles sous /root/.openclaw.
• Sauvegarde : si ~/.openclaw existe, exécuter d'abord cp -a ~/.openclaw ~/.openclaw.bak-$(date +%F).
• Répertoire de test : workspace isolé ~/openclaw-lab — pas ~/Documents, dépôts de production ni dossiers sensibles.

# Pré-vol rapide (exécuter en un bloc)
git --version
sw_vers
df -h ~
mkdir -p ~/openclaw-lab/{inbox,outbox,archive}
echo "Exemple lab OpenClaw : notes de planification T2." > ~/openclaw-lab/inbox/sample.txt

Si échec : erreurs Git → CLT/Homebrew ; disque plein → libérer de l'espace ; timeouts → réseau/proxy — ne pas réinstaller trois fois sans sauvegarder les journaux.

4. Installation officielle d'OpenClaw

Objectif : utiliser le point d'entrée d'installation maintenu pour que install.sh gère Node et la CLI. Source : documentation officielle Installation (revérifier les options de version avant publication).

4.1 Recommandé : install.sh officiel (macOS / Linux)

curl -fsSL https://openclaw.ai/install.sh | bash

# Installation seule, onboard plus tard :
# curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

L'installateur détecte le système, installe Node si besoin (la doc recommande Node 24 ou Node 22.19+) et installe la CLI OpenClaw. Chemins typiques (à vérifier à la publication) :

• Config utilisateur : ~/.openclaw/ (openclaw.json5, secrets/, état, journaux)
• Port passerelle par défaut : 18789 (Control UI / WebSocket)
• Arrière-plan macOS : openclaw onboard --install-daemon enregistre un LaunchAgent

4.2 Initialiser : assistant onboard

openclaw onboard --install-daemon

# Trio de vérification officiel :
openclaw --version
openclaw doctor
openclaw gateway status

L'assistant guide le fournisseur de modèle, la clé API et la passerelle. Ne jamais exécuter de scripts d'installation inconnus ; ne jamais committer de clés dans git ni publier de captures dans un chat.

4.3 Enregistrements post-installation

source ~/.zshrc          # ou ouvrir un nouveau terminal
openclaw --version         # noter la version pour le dépannage futur
openclaw doctor            # auto-diagnostic ; essayer --fix si proposé

Réussite : which openclaw résout ; openclaw doctor sans FAIL bloquant. En cas d'échec, vérifier d'abord : 20 dernières lignes du journal d'installation → PATH → Node sous le minimum ou bin npm global absent du PATH.

Ne pas supprimer ~/.openclaw immédiatement en cas d'échec — sauvegarder d'abord la sortie terminal et openclaw doctor.

5. Configurer modèles et clés API

Objectif : permettre à l'agent OpenClaw d'appeler le LLM choisi. Réussite : un test fumée non interactif obtient une réponse cohérente ; openclaw auth list ou le .env contient l'entrée sans clé dans l'historique du shell.

5.1 Configuration interactive (première fois)

openclaw onboard        # modèles, secrets, passerelle (combiner avec --install-daemon)
# Clés aussi via auth-profiles / env — voir la doc Authentication officielle

5.2 Variables d'environnement et fichiers de config

Config principale : ~/.openclaw/openclaw.json5 ; secrets souvent dans ~/.openclaw/.env (confirmer avec openclaw config path et openclaw config env-path). Exemple — noms de variables selon votre fournisseur ; ne pas copier des noms obsolètes :

# Exemple : OpenRouter (remplacer par votre clé ; ne jamais committer)
openclaw config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# Ou éditer .env directement (chmod 600 ~/.openclaw/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.openclaw/.env

Limite : tarifs, quotas, disponibilité régionale et conditions de confidentialité évoluent avec les fournisseurs — lire les conditions actuelles avant la production. Cet article ne vous enferme pas dans un nom de modèle unique.

6. Workspace, permissions et journaux

Objectif : après l'installation, rester traçable, borné et réversible. Principe : moindre privilège — n'ouvrir d'abord que le répertoire de test.

• Workspace : orienter les sessions ou openclaw.json5 vers ~/openclaw-lab ; ajouter AGENTS.md pour les limites d'outils (voir la doc officielle Context Files).
• Permissions macOS : les outils fichier/terminal peuvent demander l'accès complet au disque — lors de la première acceptation, limiter au dossier de test, pas à tout le disque.
• Journaux : par défaut ~/.openclaw/logs/ (agent.log, errors.log, gateway.log). Utiliser openclaw logs list, openclaw logs errors --since 30m.
• Hygiène des secrets : chmod 600 ~/.openclaw/.env ; ne pas synchroniser les zip de sauvegarde sur le cloud ; bloquer l'accès agent à ~/.ssh, paiements, kubeconfig de production.
• Arrière-plan (optionnel) : pour passerelles Telegram/Discord, openclaw gateway setup et openclaw gateway install ; exploitation longue durée dans notre guide passerelle OpenClaw 7×24.

Réussite : après instruction « lecture/écriture uniquement dans ~/openclaw-lab », les tentatives hors de ce chemin sont refusées ou journalisées.

7. Ouvrir le Dashboard et valider la passerelle (port 18789)

Objectif : confirmer la Control UI et la passerelle WebSocket. Réussite : http://127.0.0.1:18789 se charge ; openclaw gateway status indique 18789 en écoute.

openclaw gateway status
openclaw dashboard
# Ou dans le navigateur :
# http://127.0.0.1:18789/

# Mac distant (tunnel SSH — ne pas exposer 18789 sur Internet) :
# ssh -L 18789:127.0.0.1:18789 user@mac-distant

# Conflit de port :
lsof -i :18789
openclaw gateway restart
openclaw doctor --fix

En cas d'échec, vérifier d'abord : port occupé → lsof ; UI vide mais statut OK → cache/proxy/WebSocket ; accès distant en échec → tunnel SSH local uniquement. launchd : avec --install-daemon, après redémarrage openclaw gateway status doit être actif ; sinon contrôler les journaux LaunchAgent et le contexte utilisateur (voir notre article sur les variables d'environnement launchd).

8. Acceptation au premier lancement : runbook en sept étapes

Ces sept étapes font passer de « configuration terminée » à « prêt pour l'exploitation » — les exécuter telles quelles et conserver des extraits de journaux.

1. Diagnostic : openclaw doctor --fix → aucun FAIL non traité.
2. Ping modèle : openclaw agent --message "Reply with exactly: OPENCLAW_OK" → la réponse contient OPENCLAW_OK.
3. Lecture fichier : l'agent lit ~/openclaw-lab/inbox/sample.txt et cite la première ligne.
4. Écriture fichier : écrit ~/openclaw-lab/outbox/ping.txt → visible avec cat.
5. Journaux : openclaw logs errors --since 10m → pas de nouvel ERROR inexpliqué.
6. Nouveau terminal : fermer la fenêtre, rouvrir, répéter l'étape 2 → le PATH n'est pas limité à la session.
7. Redémarrage optionnel : répéter l'étape 2 après reboot ; si la passerelle est installée, aussi openclaw gateway status.

Seuils citables (acceptation personnelle, pas un SLA officiel) : réponse fumée < 60 s ; 0 ERROR inexpliqué dans errors.log sur 10 minutes ; nouveau fichier visible sous ~/openclaw-lab/outbox.

9. Premier cas pratique : résumé + todos + retour arrière

Scénario : lire un texte d'exemple dans le répertoire de test, produire un court résumé et trois todos en Markdown, conserver une sauvegarde — couvre installation (CLI), configuration (modèle) et workflow (lire → raisonner → écrire → journaux).

# 1. Entrée (ignorer si la section 3 l'a déjà créée)
cat > ~/openclaw-lab/inbox/weekly-notes.txt <<'EOF'
Cette semaine : brouillon du guide d'installation OpenClaw.
Suivi : alerte budget OpenRouter ; évaluer la passerelle Telegram la semaine prochaine.
Risque : ne jamais committer de clés API dans git.
EOF

# 2. Session interactive
openclaw
# Exemple de prompt en session :
# "Utiliser uniquement ~/openclaw-lab. Lire inbox/weekly-notes.txt,
#  écrire un résumé de moins de 150 mots et 3 todos dans outbox/summary-and-todos.md,
#  et copier le fichier source vers archive/weekly-notes.bak"

# 3. Vérification non interactive
ls -la ~/openclaw-lab/outbox/summary-and-todos.md
ls -la ~/openclaw-lab/archive/
openclaw logs agent -n 30 --since 15m

Réussite :

• summary-and-todos.md contient résumé + 3 todos alignés sur la source.
• archive/ contient la sauvegarde ; diff fonctionne.
• Les journaux montrent les appels d'outils ; le tableau de bord fournisseur affiche l'appel (contrôle des coûts).

Retour arrière : rm ~/openclaw-lab/outbox/summary-and-todos.md && cp ~/openclaw-lab/archive/weekly-notes.bak ~/openclaw-lab/inbox/weekly-notes.txt. En cas d'échec, vérifier d'abord : troncature de contexte → permissions sur outbox → erreurs d'outils dans errors.log.

10. Dépannage : corrections par couches, éviter la réinstallation aveugle

Checklist de faits avant publication (mainteneurs) : URL install.sh, macOS minimum, chemins par défaut, sous-commandes CLI, noms de variables fournisseur, chemins des journaux — mettre à jour la doc avant diffusion. Lecteurs : en cas d'erreur, lancer openclaw doctor, puis errors.log, réinstaller en dernier recours uniquement.

11. Étapes suivantes : répertoire de test → workflow réel

Une fois l'acceptation passée, étendre dans cet ordre — ne pas brancher dépôts de production ni paiements dès le premier jour :

1. Autoriser un répertoire de side-project réel ; toujours bloquer ~/.ssh et l'accès global *.
2. Utiliser openclaw cron pour des tâches quotidiennes à faible risque (ex. inventaire d'un dossier Téléchargements — toujours borné).
3. Ajouter une passerelle de messagerie (Telegram/Discord) avec appariement pour bloquer les inconnus (doc Security officielle).
4. Hebdomadaire : openclaw backup --quick, puis s'entraîner à la mise à jour/retour arrière selon la doc de maintenance.