Installer OpenClaw : Guide pas à pas

Ce tutoriel couvre l'installation complète d'OpenClaw sur un environnement local. Vous apprendrez à préparer votre environnement Python, à installer le framework via pip, à configurer votre premier agent et à valider que tout fonctionne correctement. Chaque étape est accompagnée des commandes exactes à exécuter et des erreurs courantes à éviter. À la fin de ce guide, vous disposerez d'un agent OpenClaw opérationnel, prêt à être enrichi de skills personnalisés ou déployé sur un serveur. Consultez le guide complet OpenClaw pour comprendre l'architecture avant de commencer.

---

Prérequis

Avant d'installer OpenClaw, vérifiez que votre environnement remplit les conditions suivantes.

Python 3.10 ou supérieur

OpenClaw requiert Python 3.10 minimum. Les versions antérieures ne sont pas supportées en raison de l'utilisation de la syntaxe match/case et des annotations de type modernes.

Vérifiez votre version :

python3 --version
# Python 3.11.8  ← acceptable
# Python 3.9.x  ← trop ancien, mettre à jour

Si vous devez gérer plusieurs versions de Python, utilisez pyenv :

# Installation de pyenv (Linux/macOS)
curl https://pyenv.run | bash

# Installer Python 3.11
pyenv install 3.11.8
pyenv global 3.11.8

# Vérifier
python3 --version

pip et virtualenv

pip est inclus avec Python 3.10+. Vérifiez qu'il est à jour :

pip3 install --upgrade pip

L'utilisation d'un environnement virtuel est fortement recommandée pour isoler les dépendances d'OpenClaw des autres projets Python :

# Créer un environnement virtuel
python3 -m venv .venv

# Activer l'environnement (Linux/macOS)
source .venv/bin/activate

# Activer l'environnement (Windows)
.venv\Scripts\activate

# Vérifier que le virtualenv est actif
which python3
# /chemin/vers/votre/projet/.venv/bin/python3

Clé API LLM

OpenClaw utilise un LLM comme moteur de raisonnement. Vous avez besoin d'au moins une clé API parmi :

• OpenAI : OPENAI_API_KEY — recommandé pour débuter
• Anthropic : ANTHROPIC_API_KEY
• Mistral : MISTRAL_API_KEY
• Ollama : aucune clé, modèle local (voir section dédiée)

Stockez vos clés dans un fichier .env à la racine du projet, jamais en dur dans le code :

# .env
OPENAI_API_KEY=sk-proj-...

Attention : ajoutez .env à votre .gitignore immédiatement pour éviter de committer vos clés API.

---

Installation via pip

Avec votre virtualenv activé, installez OpenClaw :

pip install openclaw

Pour installer avec tous les skills natifs inclus :

pip install "openclaw[all]"

Pour une installation minimale avec seulement les dépendances de base :

pip install "openclaw[core]"

Vérifier l'installation

openclaw --version
# openclaw 0.9.4

python3 -c "import openclaw; print(openclaw.__version__)"
# 0.9.4

Pièges courants à l'installation

Conflit de dépendances avec pydantic : OpenClaw utilise Pydantic v2. Si vous avez des projets utilisant Pydantic v1 dans le même environnement, des conflits peuvent apparaître. La solution est d'utiliser un virtualenv dédié (recommandé de toute façon).

# Si vous voyez : "pydantic v1 detected, OpenClaw requires pydantic>=2.0"
pip install --upgrade pydantic

Erreur avec numpy sur Python 3.12 : certains skills natifs (notamment extract_text) dépendent de numpy. Si vous utilisez Python 3.12, spécifiez la version :

pip install "numpy>=1.26.0"
pip install "openclaw[all]"

SSL errors sur certains VPS : si vous obtenez des erreurs SSL lors du pip install, mettez à jour les certificats :

pip install --upgrade certifi

---

Configuration initiale

OpenClaw se configure via un fichier YAML. Créez un répertoire pour votre projet et initialisez la configuration :

mkdir mon-agent-openclaw
cd mon-agent-openclaw
openclaw init

La commande init génère un fichier openclaw.yaml avec une configuration par défaut :

# openclaw.yaml
agent:
  name: "mon_agent"
  description: "Agent IA généraliste"
  reasoning_mode: "react"  # react | plan_execute | reflexion
  max_iterations: 15
  timeout_seconds: 120

llm:
  provider: "openai"       # openai | anthropic | mistral | ollama
  model: "gpt-4o-mini"     # modèle économique pour les tests
  temperature: 0.2
  max_tokens: 4096

memory:
  enabled: true
  backend: "sqlite"         # sqlite | postgres | redis
  db_path: "./memory.db"
  episodic_retention_days: 30

skills:
  - name: "web_search"
    enabled: true
    config:
      provider: "duckduckgo"  # duckduckgo (gratuit) | serpapi (requiert clé)
      max_results: 5

  - name: "write_file"
    enabled: true
    config:
      base_dir: "./outputs"
      allowed_extensions: [".txt", ".md", ".json", ".csv"]

  - name: "http_request"
    enabled: true
    config:
      timeout_seconds: 30
      allowed_domains: []   # vide = tous les domaines autorisés

logging:
  level: "INFO"             # DEBUG | INFO | WARNING | ERROR
  format: "text"            # text | json
  output: "stdout"          # stdout | fichier.log

env_file: ".env"

Charger les variables d'environnement

Créez le fichier .env à côté du openclaw.yaml :

# .env
OPENAI_API_KEY=sk-proj-votre-clé-ici

Vérifiez que OpenClaw lit bien le fichier :

openclaw config validate
# Configuration validée
# LLM: openai/gpt-4o-mini
# Skills actifs: web_search, write_file, http_request
# Mémoire: sqlite (./memory.db)

---

Premier agent

Une fois la configuration validée, créez un fichier Python pour votre premier agent :

# agent.py
from openclaw import Agent
from openclaw.config import load_config

# Charger la configuration depuis openclaw.yaml
config = load_config("./openclaw.yaml")

# Instancier l'agent
agent = Agent(config)

# Définir une tâche
task = """
Recherche les 3 dernières actualités sur les agents IA,
résume chacune en 2 phrases et enregistre le résultat
dans le fichier outputs/veille_ia.txt
"""

# Lancer l'agent
print("Démarrage de l'agent...")
result = agent.run(task=task)

# Afficher le résultat
print("\n--- Résultat ---")
print(result.summary)
print(f"\nIterations effectuées : {result.iterations}")
print(f"Skills utilisés : {', '.join(result.skills_called)}")
print(f"Durée : {result.duration_seconds:.1f}s")

Exécutez-le :

python3 agent.py

Vous devriez voir l'agent raisonner en temps réel (si le niveau de log est DEBUG) et produire un fichier outputs/veille_ia.txt.

Utiliser Ollama pour une installation sans clé API

Si vous ne disposez pas de clé API, vous pouvez utiliser Ollama avec un modèle local :

# Installer Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Télécharger un modèle
ollama pull llama3.2

# Modifier openclaw.yaml
# llm:
#   provider: "ollama"
#   model: "llama3.2"
#   base_url: "http://localhost:11434"

Note : les modèles locaux sont plus lents et moins performants pour les tâches de raisonnement complexe. Ils conviennent bien aux tests et au développement local.

---

Tester l'installation

OpenClaw fournit une suite de tests intégrée pour vérifier que chaque composant fonctionne correctement.

Tests de connectivité

# Tester la connexion au LLM
openclaw test llm
# Connexion OpenAI: OK
# Modèle gpt-4o-mini: accessible
# Latence: 420ms

# Tester les skills actifs
openclaw test skills
# web_search (duckduckgo): OK
# write_file: OK
# http_request: OK

# Test complet
openclaw test all
# Tous les composants opérationnels

Test manuel avec une tâche simple

openclaw run --task "Dis-moi la date d'aujourd'hui et écris-la dans outputs/test.txt"

Si le fichier outputs/test.txt est créé avec la bonne date, l'installation est fonctionnelle.

Déboguer une installation défaillante

Activez les logs en mode DEBUG pour voir ce qui se passe :

OPENCLAW_LOG_LEVEL=DEBUG python3 agent.py

Les erreurs les plus fréquentes et leurs solutions :

Erreur	Cause probable	Solution
AuthenticationError: Invalid API key	Clé API manquante ou incorrecte	Vérifier .env et env_file dans le YAML
ModuleNotFoundError: openclaw	Virtualenv non activé	source .venv/bin/activate
SkillNotFoundError: web_search	Skill non installé	pip install "openclaw[all]"
PermissionError: ./outputs	Répertoire non créé	mkdir -p outputs
MaxIterationsReached	Tâche trop complexe	Augmenter max_iterations dans le YAML

---

Bonnes pratiques

Toujours utiliser un virtualenv dédié

Ne mélangez jamais les dépendances d'OpenClaw avec d'autres projets. Créez un virtualenv par projet d'agent.

Versionner openclaw.yaml dans Git

Le fichier openclaw.yaml est la définition de votre agent. Committez-le dans Git. En revanche, le fichier .env et la base de données memory.db ne doivent jamais être versionnés.

Exemple de .gitignore :

.env
*.db
.venv/
outputs/
__pycache__/

Commencer avec gpt-4o-mini

Pour le développement et les tests, utilisez gpt-4o-mini plutôt que gpt-4o. Le coût est 15 fois inférieur, et les performances sont suffisantes pour la grande majorité des tâches. Passez à un modèle plus puissant uniquement si les résultats sont insatisfaisants.

Définir des timeouts explicites

Sans timeout, un agent peut rester bloqué sur une tâche qui ne converge pas. Définissez toujours timeout_seconds dans la configuration.

---

Conclusion

Votre installation OpenClaw est maintenant opérationnelle. Vous avez un agent capable de rechercher sur le web, de manipuler des fichiers et de mémoriser ses actions. La prochaine étape est d'enrichir cet agent avec des skills personnalisés adaptés à votre cas d'usage. Pour un déploiement sur serveur, consultez le guide OpenClaw sur VPS qui couvre la configuration systemd, la sécurisation et le monitoring. Pour explorer toutes les capacités du framework, le guide complet OpenClaw reste votre référence principale.

---

Checklist de validation finale

Avant de passer au développement de votre agent, vérifiez chaque point :

• ✅ Python 3.10 ou supérieur installé (python3 --version)
• ✅ Virtualenv créé et activé (which python3 pointe vers .venv)
• ✅ OpenClaw installé (openclaw --version retourne un numéro de version)
• ✅ Fichier .env créé avec les clés API nécessaires
• ✅ Fichier openclaw.yaml validé (openclaw config validate sans erreur)
• ✅ Tests de connectivité passés (openclaw test all)
• ✅ Premier agent exécuté avec succès (outputs/ contient un fichier généré)
• ✅ .env et memory.db ajoutés au .gitignore