Configurer OpenClaw : guide complet

La configuration d'OpenClaw détermine le comportement de chaque agent : quel modèle LLM utiliser, comment gérer les erreurs réseau, où stocker la mémoire, quels skills charger. Un fichier openclaw.yaml mal structuré conduit à des agents imprévisibles ou silencieusement défaillants. Ce guide couvre l'ensemble des paramètres disponibles, du fichier YAML de base aux configurations avancées multi-agents, avec des exemples concrets pour OpenAI, Anthropic et Mistral. Avant de configurer, assurez-vous d'avoir suivi Installer OpenClaw.

Le fichier openclaw.yaml expliqué

openclaw.yaml est le point d'entrée de toute configuration OpenClaw. Il décrit l'agent, ses capacités, ses dépendances et son comportement. OpenClaw le charge au démarrage et valide sa structure via Pydantic — une erreur de schéma arrête le processus immédiatement avec un message clair.

Voici un fichier annoté complet avec tous les blocs disponibles :

# openclaw.yaml — fichier de configuration complet et annoté

# ── Identité de l'agent ──────────────────────────────────────────────────────
agent:
  name: mon-agent                    # Identifiant unique, utilisé dans les logs
  description: "Agent d'analyse SEO" # Description lisible, non utilisée par le LLM
  version: "1.0.0"                   # Version de votre agent (semver recommandé)

# ── Provider LLM ─────────────────────────────────────────────────────────────
llm:
  provider: openai                   # openai | anthropic | mistral | ollama
  model: gpt-4o                      # Nom du modèle selon le provider
  temperature: 0.3                   # 0.0 (déterministe) → 1.0 (créatif)
  max_tokens: 4096                   # Limite de tokens en sortie
  timeout: 60                        # Secondes avant abandon de l'appel LLM
  retry:
    max_attempts: 3                  # Nombre de tentatives en cas d'erreur
    backoff_factor: 2.0              # Facteur d'attente exponentielle entre tentatives

# ── Skills ───────────────────────────────────────────────────────────────────
skills:
  - path: skills/brave_search.py     # Chemin relatif au répertoire du projet
    name: BraveSearchSkill           # Nom de la classe Python à instancier
  - path: skills/web_scraper.py
    name: WebScraperSkill
  - path: skills/slack_notifier.py
    name: SlackNotifierSkill

# ── Mémoire ──────────────────────────────────────────────────────────────────
memory:
  backend: postgresql                # postgresql | redis | sqlite | none
  connection: ${DATABASE_URL}        # Référence à une variable d'environnement
  ttl: 86400                         # Durée de vie des entrées en secondes (24h)
  max_entries: 1000                  # Nombre maximum d'entrées par agent

# ── File de tâches ───────────────────────────────────────────────────────────
queue:
  backend: redis                     # redis | memory (dev seulement)
  connection: ${REDIS_URL}
  concurrency: 2                     # Nombre de tâches exécutées en parallèle

# ── Tâches planifiées ────────────────────────────────────────────────────────
tasks:
  - name: analyse-serp-hebdo
    trigger: cron
    schedule: "0 7 * * 1"           # Tous les lundis à 7h
    prompt: "Analyse les SERPs pour les mots-clés prioritaires."
  - name: rapport-quotidien
    trigger: cron
    schedule: "0 18 * * *"          # Tous les jours à 18h
    prompt: "Génère le rapport de performance de la journée."

# ── Observabilité ────────────────────────────────────────────────────────────
logging:
  level: INFO                        # DEBUG | INFO | WARNING | ERROR
  format: json                       # json | text
  output: stdout                     # stdout | file
  file_path: logs/agent.log          # Ignoré si output = stdout

# ── API HTTP (optionnel) ─────────────────────────────────────────────────────
api:
  enabled: true
  host: "0.0.0.0"
  port: 8000
  auth_token: ${API_AUTH_TOKEN}      # Token Bearer pour sécuriser l'API

Les providers LLM supportés

OpenClaw supporte nativement quatre providers. La configuration du bloc llm varie légèrement selon le provider choisi.

OpenAI

llm:
  provider: openai
  model: gpt-4o          # gpt-4o | gpt-4o-mini | gpt-4-turbo | gpt-3.5-turbo
  temperature: 0.3
  max_tokens: 4096
  api_base: https://api.openai.com/v1   # Optionnel, utile pour les proxies

OpenAI est le provider par défaut. GPT-4o offre le meilleur équilibre coût/performance pour la majorité des tâches d'agents. GPT-4o-mini convient aux tâches simples à fort volume.

Anthropic

llm:
  provider: anthropic
  model: claude-sonnet-4-5     # claude-opus-4 | claude-sonnet-4-5 | claude-haiku-3-5
  temperature: 0.3
  max_tokens: 8192

Claude se distingue par sa fenêtre de contexte étendue et sa fiabilité sur les instructions longues. claude-sonnet-4-5 est recommandé pour les agents complexes, claude-haiku-3-5 pour la rapidité.

Mistral

llm:
  provider: mistral
  model: mistral-large-latest   # mistral-large-latest | mistral-small-latest | open-mistral-7b
  temperature: 0.3
  max_tokens: 4096
  endpoint: https://api.mistral.ai/v1

Mistral propose des modèles performants à coût réduit et offre des options d'hébergement souverain (Mistral La Plateforme). Pertinent pour les projets avec contraintes RGPD strictes.

Ollama (modèles locaux)

llm:
  provider: ollama
  model: llama3.2              # Tout modèle installé localement
  endpoint: http://localhost:11434
  temperature: 0.3

Ollama permet d'exécuter des modèles entièrement en local, sans envoi de données vers des APIs tierces. Utile pour les données confidentielles ou les environnements sans accès internet.

Variables d'environnement essentielles

OpenClaw résout automatiquement les références ${VAR} dans le YAML au moment du chargement. Voici le .env.example complet :

# .env.example

# ── LLM Providers ──────────────────────────────────────────────────────────
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-api03-...
MISTRAL_API_KEY=...

# ── Base de données ────────────────────────────────────────────────────────
DATABASE_URL=postgresql://user:password@localhost:5432/openclaw_db

# ── Cache et file ─────────────────────────────────────────────────────────
REDIS_URL=redis://localhost:6379/0

# ── Skills externes ────────────────────────────────────────────────────────
BRAVE_API_KEY=BSA...
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
SLACK_BOT_TOKEN=xoxb-...
SENDGRID_API_KEY=SG....
TWITTER_BEARER_TOKEN=AAAA...

# ── API interne OpenClaw ───────────────────────────────────────────────────
API_AUTH_TOKEN=un-token-long-et-aleatoire

# ── Comportement ──────────────────────────────────────────────────────────
OPENCLAW_LOG_LEVEL=INFO
OPENCLAW_ENV=production        # development | staging | production

Configuration des agents

Paramètres du bloc agent

Paramètre	Type	Défaut	Description
name	string	requis	Identifiant unique de l'agent
description	string	""	Description lisible
version	string	"1.0.0"	Version sémantique
max_iterations	int	10	Nombre max de cycles de raisonnement
verbose	bool	false	Active le mode verbeux dans les logs

Paramètres du bloc llm

Paramètre	Type	Défaut	Description
provider	string	openai	Provider LLM
model	string	requis	Nom du modèle
temperature	float	0.7	Créativité (0.0–1.0)
max_tokens	int	2048	Tokens max en sortie
timeout	int	30	Timeout en secondes
retry.max_attempts	int	3	Tentatives max en cas d'erreur
retry.backoff_factor	float	2.0	Facteur de backoff exponentiel

Sécurité des clés API

Les clés API ne doivent jamais apparaître en clair dans openclaw.yaml ni dans le code source. Respectez ces règles sans exception :

Règle 1 — Variables d'environnement uniquement

# Correct
llm:
  provider: openai
# La clé est lue depuis OPENAI_API_KEY dans l'environnement

# Incorrect (ne jamais faire)
llm:
  api_key: sk-proj-ma-vraie-cle

OpenClaw lit automatiquement OPENAI_API_KEY, ANTHROPIC_API_KEY et MISTRAL_API_KEY depuis l'environnement sans configuration supplémentaire.

Règle 2 — .gitignore strict

# Ajoutez ces lignes à .gitignore
.env
.env.local
.env.production
*.key
secrets/

Règle 3 — Rotation des clés

En cas de fuite suspectée, invalidez immédiatement la clé depuis la console du provider, puis regénérez-en une nouvelle. Ne comptez pas sur la suppression d'un commit Git pour effacer une clé exposée.

Règle 4 — Principe du moindre privilège

Créez des clés API dédiées par agent avec les permissions minimales nécessaires. Une clé OpenAI utilisée uniquement pour des completions n'a pas besoin d'accès aux fine-tunings.

Pour un déploiement sur serveur, consultez OpenClaw sur VPS et Sécurité OpenClaw.

Configuration avancée (timeouts, retry, logs)

Timeouts

Définissez des timeouts à deux niveaux pour éviter les blocages :

llm:
  timeout: 60          # Timeout de l'appel LLM en secondes

skills:
  default_timeout: 15  # Timeout appliqué à tous les skills sauf override individuel
  overrides:
    pdf_extractor:
      timeout: 60      # Les PDFs volumineux nécessitent plus de temps

Retry et backoff

llm:
  retry:
    max_attempts: 3
    backoff_factor: 2.0
    retry_on:            # Codes HTTP déclenchant un retry
      - 429              # Rate limit
      - 500
      - 502
      - 503

Avec backoff_factor: 2.0, les délais entre tentatives sont : 1s, 2s, 4s. Augmentez max_attempts à 5 pour les APIs avec rate limits agressifs (ex: Twitter).

Logs structurés

logging:
  level: INFO
  format: json           # JSON pour ingestion par Loki, Datadog, CloudWatch
  output: stdout
  fields:                # Champs ajoutés à chaque entrée de log
    service: mon-agent
    environment: ${OPENCLAW_ENV}

Un log JSON typique en production :

{
  "timestamp": "2026-03-07T09:15:32Z",
  "level": "INFO",
  "message": "Skill executed successfully",
  "skill": "BraveSearchSkill",
  "duration_ms": 342,
  "service": "mon-agent",
  "environment": "production"
}

Exemple concret : config multi-agent

Voici une configuration pour un pipeline à trois agents qui collaborent : un agent de recherche, un agent de rédaction et un agent de publication.

# openclaw-multi.yaml

# ── Agent 1 : Chercheur ───────────────────────────────────────────────────
agents:
  - name: researcher
    description: "Collecte et analyse les sources sur un sujet donné"
    llm:
      provider: openai
      model: gpt-4o-mini    # Modèle économique pour la recherche
      temperature: 0.2
      max_tokens: 2048
    skills:
      - path: skills/brave_search.py
        name: BraveSearchSkill
      - path: skills/web_scraper.py
        name: WebScraperSkill
    output:
      target: writer         # Passe le résultat à l'agent suivant
      format: json

  # ── Agent 2 : Rédacteur ─────────────────────────────────────────────────
  - name: writer
    description: "Rédige un article structuré à partir des sources"
    llm:
      provider: anthropic
      model: claude-sonnet-4-5   # Modèle plus puissant pour la rédaction
      temperature: 0.5
      max_tokens: 8192
    skills:
      - path: skills/openai_summary.py
        name: OpenAISummarySkill
    input:
      source: researcher
    output:
      target: publisher
      format: markdown

  # ── Agent 3 : Éditeur/Publicateur ───────────────────────────────────────
  - name: publisher
    description: "Valide et publie le contenu"
    llm:
      provider: mistral
      model: mistral-small-latest  # Tâche simple, modèle léger
      temperature: 0.1
    skills:
      - path: skills/slack_notifier.py
        name: SlackNotifierSkill
    input:
      source: writer

# ── Mémoire partagée entre agents ──────────────────────────────────────────
shared_memory:
  backend: postgresql
  connection: ${DATABASE_URL}

# ── Tâche déclenchant le pipeline ──────────────────────────────────────────
tasks:
  - name: pipeline-contenu
    trigger: cron
    schedule: "0 8 * * 2,4"   # Mardi et jeudi à 8h
    entry_agent: researcher
    prompt: "Recherche et rédige un article sur les dernières avancées en agents IA autonomes."

Démarrage du pipeline multi-agent :

python -m openclaw.run --config openclaw-multi.yaml

Bonnes pratiques

Séparez les configs par environnement : maintenez openclaw.dev.yaml, openclaw.staging.yaml et openclaw.prod.yaml. Les différences principales : niveau de log, modèle LLM (plus économique en dev), backends mémoire (sqlite en dev, postgresql en prod).

Validez avant déploiement : OpenClaw propose une commande de validation à sec :

python -m openclaw.validate --config openclaw.yaml

Elle vérifie la syntaxe YAML, la présence des variables d'environnement référencées et l'existence des fichiers skills. Intégrez-la dans votre CI.

Versionner openclaw.yaml : contrairement au .env, le fichier YAML doit être versionné. Il documente l'architecture de votre agent. Committez-le avec des messages clairs (feat: add TwitterMonitorSkill to researcher agent).

Températures basses pour les agents : sauf pour les tâches créatives, maintenez temperature entre 0.1 et 0.4. Des températures élevées introduisent de l'imprévisibilité dans le choix des skills et la formulation des actions.

Monitoring des coûts : activez les limites de dépenses dans les dashboards des providers (OpenAI, Anthropic). Configurez des alertes à 50% et 80% de votre budget mensuel pour éviter les mauvaises surprises liées à des boucles d'agents mal configurées.

Conclusion

Un openclaw.yaml bien structuré est la colonne vertébrale de vos agents : il détermine leurs capacités, leur fiabilité et leur sécurité. Commencez avec une configuration minimale (un agent, un provider, deux ou trois skills), validez le comportement, puis ajoutez la complexité progressivement. Les paramètres de retry, timeout et logging ne sont pas optionnels en production — ils sont la différence entre un agent qui gère les pannes gracieusement et un agent qui bloque silencieusement.