Skip to main content
Réponses rapides et dépannage approfondi pour les configurations réelles (développement local, VPS, multi-agent, clés OAuth/API, basculement de modèle). Pour les diagnostics d’exécution, consultez Dépannage. Pour la référence complète de la configuration, consultez Configuration.

Les 60 premières secondes en cas de problème

1

État rapide

Résumé local rapide : système d’exploitation + mise à jour, accessibilité du Gateway/service, agents/sessions, configuration du fournisseur + problèmes d’exécution (lorsque le Gateway est accessible).
2

Rapport à copier-coller (partage sans risque)

Diagnostic en lecture seule avec la fin du journal (jetons masqués).
3

État du démon et du port

Affiche l’exécution du superviseur par rapport à l’accessibilité RPC, l’URL cible de la sonde et la configuration probablement utilisée par le service.
4

Sondes approfondies

Sonde en direct de l’état du Gateway, y compris les sondes de canaux lorsqu’elles sont prises en charge (nécessite un Gateway accessible). Consultez État de santé.
5

Suivre le dernier journal

Si RPC est indisponible, utilisez à la place :
Les journaux de fichiers sont distincts des journaux de service ; consultez Journalisation et Dépannage.
6

Exécuter le docteur (réparations)

Répare/migre la configuration et l’état, puis exécute les vérifications d’état. Consultez Docteur.
7

Instantané du Gateway (WS uniquement)

Demande un instantané complet au Gateway en cours d’exécution. Consultez État de santé.

Démarrage rapide et configuration initiale

La FAQ de première exécution — installation, intégration, routes d’authentification, abonnements, échecs initiaux — se trouve dans la FAQ de première exécution.

Qu’est-ce qu’OpenClaw ?

OpenClaw est un assistant IA personnel que vous exécutez sur vos propres appareils. Il répond sur les services de messagerie que vous utilisez déjà (Discord, Google Chat, iMessage, Mattermost, Signal, Slack, Telegram, WebChat, WhatsApp et les plugins de canaux intégrés tels que QQ Bot) et peut également proposer la voix ainsi qu’un Canvas en direct sur les plateformes prises en charge. Le Gateway est le plan de contrôle toujours actif ; l’assistant est le produit.
OpenClaw n’est pas « seulement une surcouche pour Claude ». C’est un plan de contrôle privilégiant le local qui exécute un assistant performant sur votre propre matériel, accessible depuis les applications de discussion que vous utilisez déjà, avec des sessions avec état, une mémoire et des outils, sans confier vos flux de travail à un SaaS hébergé.
  • Vos appareils, vos données : exécutez le Gateway où vous le souhaitez (Mac, Linux, VPS) et conservez localement l’espace de travail et l’historique des sessions.
  • De vrais canaux, pas un bac à sable web : Discord/iMessage/Signal/Slack/Telegram/WhatsApp/etc., plus la voix sur mobile et Canvas sur les plateformes prises en charge.
  • Indépendant du modèle : utilisez Anthropic, MiniMax, OpenAI, OpenRouter, etc., avec un routage et un basculement par agent.
  • Option entièrement locale : exécutez des modèles locaux afin que toutes les données puissent rester sur votre appareil.
  • Routage multi-agent : séparez les agents par canal, compte ou tâche, chacun avec son propre espace de travail et ses propres valeurs par défaut.
  • Open source et modifiable : inspectez, étendez et auto-hébergez sans dépendance envers un fournisseur.
Documentation : Gateway, Canaux, Multi-agent, Mémoire.
Bons premiers projets : créer un site web (WordPress, Shopify ou un site statique) ; prototyper une application mobile (structure, écrans, plan d’API) ; organiser des fichiers et des dossiers ; connecter Gmail et automatiser les résumés ou les suivis.Il peut gérer des tâches importantes, mais fonctionne mieux lorsqu’elles sont divisées en phases avec des sous-agents pour le travail en parallèle.
  • Briefings personnels : résumés de votre boîte de réception, de votre calendrier et des actualités qui vous intéressent.
  • Recherche et rédaction : recherches rapides, résumés et premières versions d’e-mails ou de documents.
  • Rappels et suivis : notifications et listes de contrôle pilotées par Cron ou Heartbeat.
  • Automatisation du navigateur : remplir des formulaires, collecter des données, répéter des tâches web.
  • Coordination entre appareils : envoyez une tâche depuis votre téléphone, laissez le Gateway l’exécuter sur un serveur et récupérez le résultat dans la discussion.
Oui, pour la recherche, la qualification et la rédaction : analyser des sites, établir des listes restreintes, résumer les prospects, rédiger des ébauches de messages de prospection ou de textes publicitaires.Pour les campagnes de prospection ou de publicité, gardez un humain dans la boucle. Évitez le spam, respectez les lois locales et les politiques des plateformes, et vérifiez tout avant l’envoi. Laissez OpenClaw préparer les brouillons ; vous les approuvez.Documentation : Sécurité.
OpenClaw est un assistant personnel et une couche de coordination, pas un remplacement d’IDE. Utilisez Claude Code ou Codex pour bénéficier de la boucle de développement directe la plus rapide dans un dépôt. Utilisez OpenClaw pour la mémoire persistante, l’accès entre appareils et l’orchestration des outils.
  • Mémoire persistante et espace de travail conservés entre les sessions.
  • Accès multiplateforme (Telegram, WhatsApp, TUI, WebChat).
  • Orchestration des outils (navigateur, fichiers, planification, hooks).
  • Gateway toujours actif (exécutez-le sur un VPS et interagissez depuis n’importe où).
  • Nodes pour le navigateur, l’écran, la caméra et l’exécution en local.
Présentation : https://openclaw.ai/showcase.

Skills et automatisation

Utilisez des remplacements gérés plutôt que de modifier la copie du dépôt. Placez les modifications dans ~/.openclaw/skills/<name>/SKILL.md (ou ajoutez un dossier via skills.load.extraDirs dans ~/.openclaw/openclaw.json). Ordre de priorité : <workspace>/skills -> <workspace>/.agents/skills -> ~/.agents/skills -> ~/.openclaw/skills -> intégrés -> skills.load.extraDirs, afin que les remplacements gérés aient priorité sur les Skills intégrés sans modifier git. Pour effectuer une installation globale tout en limitant la visibilité à certains agents, conservez la copie partagée dans ~/.openclaw/skills et contrôlez la visibilité avec agents.defaults.skills / agents.list[].skills. Seules les modifications dignes d’être intégrées en amont doivent être proposées sous forme de PR pour la copie du dépôt.
Oui : ajoutez des répertoires via skills.load.extraDirs dans ~/.openclaw/openclaw.json (priorité la plus faible dans l’ordre ci-dessus). clawhub installe par défaut dans ./skills, qu’OpenClaw traite comme <workspace>/skills lors de la session suivante. Pour limiter la visibilité à certains agents, combinez cela avec agents.defaults.skills ou agents.list[].skills.
Modèles pris en charge :
  • Tâches Cron : les tâches isolées peuvent définir un remplacement de model par tâche.
  • Agents : acheminez les tâches vers des agents distincts avec différents modèles par défaut, niveaux de réflexion et paramètres de flux.
  • Changement à la demande : /model change à tout moment le modèle de la session actuelle.
Exemple — même modèle, paramètres différents par agent :
Placez les valeurs par défaut partagées par modèle dans agents.defaults.models["provider/model"].params, puis les remplacements propres à chaque agent directement dans agents.list[].params. Ne dupliquez pas le même modèle dans agents.list[].models["provider/model"].params imbriqué ; ce chemin est destiné au catalogue de modèles par agent et aux remplacements d’exécution.Consultez Tâches Cron, Routage multi-agent, Configuration, Commandes slash.
Utilisez des sous-agents pour les tâches longues ou parallèles : ils s’exécutent dans leur propre session, renvoient un résumé et maintiennent la réactivité de votre discussion principale. Demandez au bot de « créer un sous-agent pour cette tâche », ou utilisez /subagents. Utilisez /status pour savoir si le Gateway est actuellement occupé.Les tâches longues et les sous-agents consomment tous deux des jetons ; définissez un modèle moins coûteux pour les sous-agents via agents.defaults.subagents.model si le coût est important.Documentation : Sous-agents, Tâches en arrière-plan.
Liez un fil Discord à un sous-agent ou à une cible de session afin que les messages de suivi qui y sont envoyés restent dans cette session liée.
  • Créez-le avec sessions_spawn en utilisant thread: true (éventuellement mode: "session" pour un suivi persistant).
  • Ou effectuez la liaison manuellement avec /focus <target>.
  • /agents inspecte l’état de la liaison.
  • /session idle <duration|off> et /session max-age <duration|off> contrôlent la suppression automatique du focus.
  • /unfocus détache le fil.
Configuration : session.threadBindings.enabled (commutateur global), session.threadBindings.idleHours (valeur par défaut 24, 0 désactive), session.threadBindings.maxAgeHours (valeur par défaut 0 = aucune limite stricte) et remplacements par canal channels.discord.threadBindings.{enabled,idleHours,maxAgeHours}. channels.discord.threadBindings.spawnSessions contrôle la liaison automatique lors de la création (valeur par défaut true).Documentation : Sous-agents, Discord, Référence de configuration, Commandes slash.
Vérifiez la route résolue du demandeur :
  • La remise d’un sous-agent en mode achèvement privilégie un fil lié ou une route de conversation lorsqu’il en existe.
  • Si l’origine de l’achèvement ne contient qu’un canal, OpenClaw se rabat sur la route enregistrée de la session du demandeur (lastChannel / lastTo / lastAccountId) afin que la remise directe puisse tout de même réussir.
  • En l’absence de route liée et de route enregistrée exploitable, la remise directe peut échouer et le résultat est alors placé dans la file d’attente de remise de la session au lieu d’être publié immédiatement.
  • Les cibles non valides ou obsolètes peuvent également imposer le recours à la file d’attente ou provoquer l’échec final de la remise.
  • Si la dernière réponse visible de l’assistant enfant est exactement NO_REPLY / no_reply ou ANNOUNCE_SKIP, OpenClaw supprime intentionnellement l’annonce au lieu de publier une ancienne progression obsolète.
Débogage : openclaw tasks show <lookup>, où <lookup> est un identifiant de tâche, un identifiant d’exécution ou une clé de session.Documentation : Sous-agents, Tâches en arrière-plan, Outils de session.
Cron s’exécute dans le processus du Gateway ; il ne se déclenche pas si le Gateway ne fonctionne pas en continu.
  • Vérifiez que Cron est activé (cron.enabled) et que OPENCLAW_SKIP_CRON n’est pas défini.
  • Vérifiez que le Gateway fonctionne 24 h/24 et 7 j/7 (sans mise en veille ni redémarrage).
  • Vérifiez le fuseau horaire de la tâche (--tz par rapport au fuseau horaire de l’hôte).
Débogage :
Documentation : Tâches Cron, Automatisation.
Vérifiez le mode de livraison :
  • --no-deliver / delivery.mode: "none" : aucun envoi de secours par le programme d’exécution n’est attendu.
  • Cible d’annonce manquante ou non valide (channel / to) : le programme d’exécution a ignoré la livraison sortante.
  • Échecs d’authentification du canal (unauthorized, Forbidden) : le programme d’exécution a tenté d’effectuer la livraison, mais les identifiants l’ont bloquée.
  • Un résultat isolé silencieux (NO_REPLY / no_reply uniquement) est considéré comme intentionnellement non livrable ; la livraison de secours mise en file d’attente est donc également supprimée.
Pour les tâches Cron isolées, l’agent peut toujours effectuer un envoi direct avec l’outil message lorsqu’une route de discussion est disponible. --announce contrôle uniquement la livraison de secours par le programme d’exécution du texte final que l’agent n’a pas déjà envoyé lui-même.Débogage :
Documentation : Tâches Cron, Tâches en arrière-plan.
Il s’agit du chemin de changement de modèle en direct, et non d’une planification en double. Une exécution Cron isolée conserve un transfert de modèle à l’exécution et réessaie lorsque l’exécution active lève LiveSessionModelSwitchError, en conservant le fournisseur/modèle sélectionné (ainsi que toute substitution de profil d’authentification sélectionnée) avant la nouvelle tentative.Ordre de priorité de sélection du modèle : d’abord la substitution de modèle du hook Gmail (hooks.gmail.model), puis le model propre à la tâche, ensuite toute substitution de modèle enregistrée pour la session Cron, puis la sélection normale du modèle de l’agent/par défaut.La boucle de nouvelle tentative est limitée à la tentative initiale plus 2 nouvelles tentatives après changement ; Cron abandonne ensuite au lieu de boucler indéfiniment.Débogage :
Documentation : Tâches Cron, CLI cron.
Utilisez les commandes natives openclaw skills ou déposez les Skills dans votre espace de travail ; l’interface utilisateur Skills de macOS n’est pas disponible sous Linux. Parcourez les Skills sur https://clawhub.ai.
Par défaut, la commande native openclaw skills install écrit dans le répertoire skills/ de l’espace de travail actif. Ajoutez --global pour installer dans le répertoire partagé et géré des Skills pour tous les agents locaux. Installez la CLI clawhub séparée uniquement pour publier ou synchroniser vos propres Skills. Utilisez agents.defaults.skills ou agents.list[].skills pour restreindre les agents qui voient les Skills partagées.
Oui, au moyen du planificateur du Gateway :
  • Tâches Cron pour les tâches planifiées ou récurrentes (elles persistent après les redémarrages).
  • Heartbeat pour les vérifications périodiques de la session principale.
  • Tâches isolées pour les agents autonomes qui publient des résumés ou les livrent dans des discussions.
Documentation : Tâches Cron, Automatisation, Heartbeat.
Pas directement. Les Skills macOS sont filtrées par metadata.openclaw.os ainsi que par les binaires requis, et ne sont chargées que lorsqu’elles sont admissibles sur l’hôte du Gateway. Sous Linux, les Skills réservées à darwin (apple-notes, apple-reminders, things-mac) ne se chargeront pas, sauf si vous remplacez ce filtrage.Trois méthodes sont prises en charge :Option A - exécuter le Gateway sur un Mac (la plus simple). Exécutez le Gateway là où se trouvent les binaires macOS, puis connectez-vous depuis Linux en mode distant ou via Tailscale. Les Skills se chargent normalement, car l’hôte du Gateway utilise macOS.Option B - utiliser un Node macOS (sans SSH). Exécutez le Gateway sous Linux, associez un Node macOS (application de barre des menus), puis définissez Node Run Commands sur “Always Ask” ou “Always Allow” sur le Mac. OpenClaw considère les Skills réservées à macOS comme admissibles lorsque les binaires requis existent sur le Node ; l’agent les exécute au moyen de l’outil nodes. Avec “Always Ask”, l’approbation de “Always Allow” dans l’invite ajoute cette commande à la liste d’autorisation.Option C - utiliser des mandataires SSH pour les binaires macOS (avancé). Conservez le Gateway sous Linux, mais faites en sorte que les binaires CLI requis soient résolus vers des scripts enveloppe SSH qui s’exécutent sur un Mac, puis remplacez la Skill pour autoriser Linux afin qu’elle reste admissible.
  1. Créez un script enveloppe SSH pour le binaire (exemple : memo pour Apple Notes) :
  2. Placez le script enveloppe dans le PATH de l’hôte Linux (par exemple ~/bin/memo).
  3. Remplacez les métadonnées de la Skill (dans l’espace de travail ou ~/.openclaw/skills) afin d’autoriser Linux :
  4. Démarrez une nouvelle session afin d’actualiser l’instantané des Skills.
Elle n’est pas intégrée actuellement. Options :
  • Skill / Plugin personnalisé : le meilleur choix pour un accès fiable aux API (les deux services disposent d’API).
  • Automatisation du navigateur : fonctionne sans code, mais est plus lente et plus fragile.
Pour un contexte par client de type agence : conservez une page Notion par client (contexte + préférences + travail en cours) et demandez à l’agent de récupérer cette page au début d’une session.Pour une intégration native, ouvrez une demande de fonctionnalité ou créez une Skill qui utilise ces API.
Les installations natives sont placées dans le répertoire skills/ de l’espace de travail actif ; utilisez --global pour tous les agents locaux, ou configurez agents.defaults.skills / agents.list[].skills pour limiter la visibilité. Certaines Skills nécessitent des binaires installés par Homebrew ; sous Linux, cela signifie Linuxbrew.Consultez Skills, Configuration des Skills, ClawHub.
Utilisez le profil de navigateur user intégré, qui se connecte au moyen de Chrome DevTools MCP :
Pour utiliser un nom personnalisé, créez un profil MCP explicite :
Celui-ci peut utiliser le navigateur de l’hôte local ou un Node de navigateur connecté. Si le Gateway s’exécute ailleurs, exécutez un hôte de Node sur la machine du navigateur ou utilisez plutôt CDP à distance.Limites actuelles des profils existing-session / user par rapport au profil openclaw géré :
  • click, type, hover, scrollIntoView, drag et select nécessitent des références d’instantané, et non des sélecteurs CSS.
  • Les hooks de téléversement nécessitent ref ou inputRef, un fichier à la fois, sans element CSS.
  • responsebody, l’exportation au format PDF, l’interception des téléchargements et les actions par lots nécessitent toujours le chemin du navigateur géré.
Consultez Navigateur pour obtenir la comparaison complète.

Mise en bac à sable et mémoire

Oui : Mise en bac à sable. Pour la configuration propre à Docker (Gateway complet dans Docker ou images de bac à sable), consultez Docker.
L’image par défaut privilégie la sécurité et s’exécute sous l’utilisateur node ; elle exclut donc les paquets système, Homebrew et les navigateurs intégrés. Pour une configuration plus complète :
  • Rendez /home/node persistant avec OPENCLAW_HOME_VOLUME afin que les caches survivent.
  • Intégrez les dépendances système dans l’image avec OPENCLAW_IMAGE_APT_PACKAGES.
  • Installez les navigateurs Playwright au moyen de la CLI intégrée : node /app/node_modules/playwright-core/cli.js install chromium.
  • Définissez PLAYWRIGHT_BROWSERS_PATH et rendez ce chemin persistant.
Documentation : Docker, Navigateur.
Oui, si le trafic privé correspond aux messages privés et le trafic public aux groupes. Définissez agents.defaults.sandbox.mode: "non-main" afin que les sessions de groupe/canal (clés non principales) s’exécutent dans le moteur de bac à sable configuré, tandis que la session principale de messages privés reste sur l’hôte. Docker est le moteur par défaut une fois la mise en bac à sable activée. Limitez les outils disponibles dans les sessions isolées au moyen de tools.sandbox.tools.Procédure de configuration : Groupes : messages privés personnels + groupes publics. Référence principale : Configuration du Gateway.
Définissez agents.defaults.sandbox.docker.binds sur ["host:container:mode"] (par exemple "/home/user/src:/src:ro"). Les montages globaux et propres à chaque agent sont fusionnés ; les montages propres à chaque agent sont ignorés lorsque scope: "shared". Utilisez :ro pour tout contenu sensible ; les montages contournent les barrières du système de fichiers du bac à sable.OpenClaw valide les sources des montages à la fois par rapport au chemin normalisé et au chemin canonique résolu à travers l’ancêtre existant le plus profond ; les échappements via un parent qui est un lien symbolique échouent donc de manière sécurisée, même lorsque le dernier segment du chemin n’existe pas encore.Consultez Mise en bac à sable et Bac à sable, stratégie des outils et mode élevé.
La mémoire d’OpenClaw est constituée de fichiers Markdown dans l’espace de travail de l’agent : notes quotidiennes dans memory/YYYY-MM-DD.md, notes organisées à long terme dans MEMORY.md (sessions principales/privées uniquement).OpenClaw effectue également un vidage silencieux de la mémoire avant la Compaction avant que la Compaction ne résume la conversation, afin de rappeler au modèle d’écrire d’abord des notes durables. Cette opération ne s’exécute que lorsque l’espace de travail est accessible en écriture (les bacs à sable en lecture seule l’ignorent) ; désactivez-la avec agents.defaults.compaction.memoryFlush.enabled: false. Consultez Mémoire.
Demandez au bot d’écrire le fait dans la mémoire : les notes à long terme sont enregistrées dans MEMORY.md, le contexte à court terme dans memory/YYYY-MM-DD.md. Rappeler au modèle d’enregistrer les souvenirs résout généralement le problème. S’il continue à les oublier, vérifiez que le Gateway utilise le même espace de travail à chaque exécution.Documentation : Mémoire, Espace de travail de l’agent.
Les fichiers de mémoire résident sur le disque et persistent jusqu’à leur suppression ; la limite correspond à votre espace de stockage, et non au modèle. Le contexte de session reste limité par la fenêtre de contexte du modèle ; les longues conversations peuvent donc être compactées ou tronquées. C’est pourquoi la recherche en mémoire existe : elle ne réintègre dans le contexte que les parties pertinentes.Documentation : Mémoire, Contexte.
Uniquement si vous utilisez les plongements OpenAI, qui constituent le fournisseur par défaut. L’OAuth Codex couvre les discussions/complétions et n’accorde pas l’accès aux plongements ; se connecter avec Codex (OAuth ou connexion par la CLI Codex) n’active donc pas la recherche sémantique en mémoire. Les plongements OpenAI nécessitent toujours une véritable clé API (OPENAI_API_KEY ou models.providers.openai.apiKey).Pour rester en local, définissez agents.defaults.memorySearch.provider: "local" (GGUF/llama.cpp). Autres fournisseurs pris en charge : Bedrock, DeepInfra, Gemini (GEMINI_API_KEY ou memorySearch.remote.apiKey), GitHub Copilot, LM Studio, Mistral, Ollama, compatible avec OpenAI et Voyage. Consultez Mémoire et Recherche en mémoire pour les détails de configuration.

Emplacement des éléments sur le disque

Non : l’état propre à OpenClaw est local, mais les services externes voient toujours ce que vous leur envoyez.
  • Local par défaut : les sessions, les fichiers de mémoire, la configuration et l’espace de travail se trouvent sur l’hôte du Gateway (~/.openclaw ainsi que le répertoire de votre espace de travail).
  • Distant par nécessité : les messages envoyés aux fournisseurs de modèles (Anthropic/OpenAI/etc.) sont transmis à leurs API, et les plateformes de discussion (Slack/Telegram/WhatsApp/etc.) stockent les données des messages sur leurs serveurs.
  • Vous contrôlez l’empreinte : les modèles locaux conservent les prompts sur votre machine, mais le trafic des canaux transite toujours par les serveurs du canal.
Voir aussi : Espace de travail de l’agent, Mémoire.
Tout se trouve sous $OPENCLAW_STATE_DIR (par défaut : ~/.openclaw) :L’ancien chemin mono-agent ~/.openclaw/agent/* est migré par openclaw doctor.Votre espace de travail (AGENTS.md, fichiers de mémoire, Skills, etc.) est distinct et configuré via agents.defaults.workspace (par défaut : ~/.openclaw/workspace).
Ces fichiers se trouvent dans l’espace de travail de l’agent, et non dans ~/.openclaw.
  • Espace de travail (par agent) : AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, et éventuellement HEARTBEAT.md. Le fichier racine memory.md en minuscules sert uniquement d’entrée de réparation héritée ; openclaw doctor --fix peut le fusionner dans MEMORY.md lorsque les deux existent.
  • Répertoire d’état (~/.openclaw) : configuration, état des canaux/fournisseurs, profils d’authentification, sessions, journaux, Skills partagées (~/.openclaw/skills).
L’espace de travail par défaut est ~/.openclaw/workspace et peut être configuré :
Si le bot « oublie » après un redémarrage, vérifiez que le Gateway utilise le même espace de travail à chaque lancement (le mode distant utilise l’espace de travail de l’hôte du Gateway, et non celui de votre ordinateur portable local).Conseil : pour conserver durablement un comportement ou une préférence, demandez au bot de l’écrire dans AGENTS.md ou MEMORY.md plutôt que de vous fier à l’historique de discussion.Consultez Espace de travail de l’agent et Mémoire.
Oui. SOUL.md est l’un des fichiers d’initialisation de l’espace de travail injectés dans le contexte de l’agent. La limite d’injection par fichier est de 20000 caractères par défaut ; le budget total d’initialisation pour l’ensemble des fichiers est de 60000 caractères.Modifiez les valeurs par défaut partagées :
Vous pouvez également remplacer ces valeurs pour un agent sous agents.list[].bootstrapMaxChars / bootstrapTotalMaxChars.Utilisez /context pour vérifier les tailles brutes et injectées, ainsi que la présence éventuelle d’une troncature. Limitez SOUL.md à la voix, au positionnement et à la personnalité ; placez les règles de fonctionnement dans AGENTS.md et les faits durables dans la mémoire.Consultez Contexte et Configuration de l’agent.
Placez votre espace de travail d’agent dans un dépôt git privé et sauvegardez-le dans un emplacement privé (par exemple, un dépôt GitHub privé). Cela enregistre la mémoire ainsi que les fichiers AGENTS/SOUL/USER et vous permet de restaurer ultérieurement l’« esprit » de l’assistant.Ne validez aucun élément situé sous ~/.openclaw (identifiants, sessions, jetons, charges utiles chiffrées contenant des secrets). Pour une restauration complète, sauvegardez séparément l’espace de travail et le répertoire d’état.Documentation : Espace de travail de l’agent.
Consultez Désinstallation.
Oui. L’espace de travail est le cwd par défaut et le point d’ancrage de la mémoire, pas un bac à sable strict. Les chemins relatifs sont résolus dans l’espace de travail ; les chemins absolus peuvent accéder à d’autres emplacements de l’hôte, sauf si le bac à sable est activé. Pour l’isolation, utilisez agents.defaults.sandbox ou les paramètres de bac à sable propres à chaque agent. Pour utiliser un dépôt comme répertoire de travail par défaut, faites pointer le paramètre workspace de cet agent vers la racine du dépôt : le dépôt OpenClaw lui-même ne contient que le code source, conservez donc l’espace de travail séparément, sauf si vous souhaitez délibérément que l’agent travaille dedans.
L’état des sessions appartient à l’hôte du Gateway. En mode distant, le stockage des sessions qui vous intéresse se trouve sur la machine distante, et non sur votre ordinateur portable local. Consultez Gestion des sessions.

Principes de base de la configuration

OpenClaw lit une configuration JSON5 facultative depuis $OPENCLAW_CONFIG_PATH (valeur par défaut : ~/.openclaw/openclaw.json). Si le fichier est absent, il utilise des valeurs par défaut relativement sûres, notamment un espace de travail par défaut situé dans ~/.openclaw/workspace.
Les liaisons qui ne sont pas en boucle locale nécessitent un chemin d’authentification du Gateway valide : authentification par secret partagé (jeton ou mot de passe), ou gateway.auth.mode: "trusted-proxy" derrière un proxy inverse correctement configuré et tenant compte de l’identité.
  • gateway.remote.token / .password n’activent pas à eux seuls l’authentification locale du Gateway ; les chemins d’appel locaux peuvent utiliser gateway.remote.* comme solution de repli uniquement lorsque gateway.auth.* n’est pas défini.
  • Pour l’authentification par mot de passe, définissez gateway.auth.mode: "password" ainsi que gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
  • Si gateway.auth.token / .password est explicitement configuré via SecretRef et n’est pas résolu, la résolution échoue de manière sécurisée (sans masquage par une solution de repli distante).
  • Les configurations de l’interface de contrôle utilisant un secret partagé s’authentifient via connect.params.auth.token ou connect.params.auth.password (stocké dans les paramètres de l’application/de l’interface). Les modes transmettant l’identité, tels que Tailscale Serve ou trusted-proxy, utilisent plutôt les en-têtes de requête : évitez de placer des secrets partagés dans les URL.
  • Avec gateway.auth.mode: "trusted-proxy", les proxys inverses en boucle locale sur le même hôte nécessitent explicitement gateway.auth.trustedProxy.allowLoopback = true et une entrée de boucle locale dans gateway.trustedProxies.
OpenClaw impose par défaut l’authentification du Gateway, y compris en boucle locale. Si aucun chemin d’authentification explicite n’est configuré, le démarrage sélectionne le mode par jeton et génère un jeton limité à l’exécution pour ce démarrage ; les clients WS locaux doivent donc s’authentifier. Cela empêche d’autres processus locaux d’appeler le Gateway.Configurez explicitement gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN ou OPENCLAW_GATEWAY_PASSWORD lorsque les clients ont besoin d’un secret stable entre les redémarrages. Vous pouvez également choisir le mode par mot de passe, ou trusted-proxy pour les proxys inverses tenant compte de l’identité. Pour une boucle locale ouverte, définissez explicitement gateway.auth.mode: "none". openclaw doctor --generate-gateway-token génère un jeton à tout moment.
Le Gateway surveille la configuration et prend en charge le rechargement à chaud : gateway.reload.mode: "hybrid" (valeur par défaut) applique à chaud les modifications sûres et redémarre pour les modifications critiques. hot, restart et off sont également pris en charge. La plupart des modifications apportées à tools.*, à la politique agents.*, à session.* et à messages.* s’appliquent immédiatement sans aucune action de rechargement ; les modifications de liaison ou de port dans gateway.* nécessitent un redémarrage.
Définissez cli.banner.taglineMode :
  • off : masque le texte du slogan, mais conserve la ligne du titre et de la version de la bannière.
  • default : utilise toujours All your chats, one OpenClaw..
  • random : affiche en alternance des slogans humoristiques ou saisonniers (comportement par défaut).
  • Pour ne pas afficher de bannière du tout, définissez la variable d’environnement OPENCLAW_HIDE_BANNER=1.
web_fetch fonctionne sans clé API. web_search dépend du fournisseur sélectionné :Grok peut également réutiliser l’OAuth xAI de l’authentification du modèle (openclaw onboard --auth-choice xai-oauth).Recommandation : exécutez openclaw configure --section web et choisissez un fournisseur.
La configuration de recherche web propre à chaque fournisseur se trouve sous plugins.entries.<plugin>.config.webSearch.*. Les anciens chemins de fournisseur tools.web.search.* sont toujours chargés à des fins de compatibilité, mais ne doivent pas être utilisés dans les nouvelles configurations. La configuration de repli de récupération web de Firecrawl se trouve sous plugins.entries.firecrawl.config.webFetch.*.
  • Listes d’autorisation : ajoutez web_search/web_fetch/x_search, ou group:web pour les trois.
  • web_fetch est activé par défaut.
  • Si tools.web.fetch.provider est omis, OpenClaw détecte automatiquement le premier fournisseur de repli prêt pour la récupération parmi les identifiants disponibles ; le plugin Firecrawl officiel fournit ce mécanisme de repli.
  • Les démons lisent les variables d’environnement depuis ~/.openclaw/.env (ou l’environnement du service).
Documentation : Outils web.
config.apply remplace la configuration entière ; un objet partiel supprime tout le reste.La version actuelle d’OpenClaw protège contre la plupart des écrasements accidentels :
  • Les écritures de configuration effectuées par OpenClaw valident l’intégralité de la configuration résultante avant l’écriture.
  • Les écritures invalides ou destructrices effectuées par OpenClaw sont rejetées et enregistrées sous openclaw.json.rejected.*.
  • Une modification directe qui empêche le démarrage ou le rechargement à chaud entraîne la fermeture sécurisée du Gateway ou l’abandon du rechargement ; elle ne réécrit pas openclaw.json.
  • openclaw doctor --fix prend en charge la réparation, peut restaurer la dernière configuration valide connue et enregistre le fichier rejeté sous openclaw.json.clobbered.*.
Récupération :
  • Consultez openclaw logs --follow pour rechercher Invalid config at, Config write rejected: ou config reload skipped (invalid config).
  • Examinez le fichier openclaw.json.clobbered.* ou openclaw.json.rejected.* le plus récent à côté de la configuration active.
  • Exécutez openclaw config validate et openclaw doctor --fix.
  • Recopiez uniquement les clés voulues avec openclaw config set ou config.patch.
  • En l’absence de dernière configuration valide connue ou de charge utile rejetée : restaurez à partir d’une sauvegarde, ou réexécutez openclaw doctor et reconfigurez les canaux/modèles.
  • En cas de perte inattendue : signalez un bug en joignant votre dernière configuration connue ou une sauvegarde. Un agent de programmation local peut souvent reconstruire une configuration fonctionnelle à partir des journaux ou de l’historique.
Pour éviter cela : utilisez openclaw config set pour les petites modifications, openclaw configure pour les modifications interactives, config.schema.lookup pour examiner un chemin inconnu (renvoie un nœud de schéma superficiel ainsi que des résumés de ses enfants immédiats) et config.patch pour les modifications RPC partielles ; réservez config.apply au remplacement de la configuration complète. L’outil d’exécution gateway destiné aux agents refuse de réécrire tools.exec.ask / tools.exec.security, même via les anciens alias tools.bash.*.Documentation : Configuration, Configurer, Dépannage du Gateway, Doctor.
Modèle courant : un Gateway (par exemple un Raspberry Pi), accompagné de Nodes et d’agents.
  • Gateway (central) : gère les canaux (Signal/WhatsApp), le routage et les sessions.
  • Nodes (appareils) : les Mac et appareils iOS/Android se connectent comme périphériques et exposent des outils locaux (system.run, canvas, camera).
  • Agents (workers) : cerveaux/espaces de travail distincts pour des rôles spécialisés (par exemple, opérations ou données personnelles).
  • Sous-agents : lancent des tâches en arrière-plan depuis un agent principal afin de les exécuter en parallèle.
  • TUI : permet de se connecter au Gateway et de changer d’agent ou de session.
Documentation : Nodes, Accès à distance, Routage multi-agent, Sous-agents, TUI.
Oui :
La valeur par défaut est false (avec interface graphique). Le mode headless est plus susceptible de déclencher les contrôles anti-bot sur certains sites (X/Twitter bloque souvent les sessions headless). Il utilise le même moteur Chromium et fonctionne pour la plupart des automatisations ; la principale différence est l’absence de fenêtre de navigateur visible (utilisez des captures d’écran pour les éléments visuels). Consultez Navigateur.
Définissez browser.executablePath sur le chemin de votre exécutable Brave (ou de tout navigateur basé sur Chromium), puis redémarrez le Gateway. Consultez Navigateur.

Gateways distants et nœuds

Les messages Telegram sont traités par le Gateway, qui exécute l’agent et n’appelle les nœuds via le WebSocket du Gateway que lorsqu’un outil de nœud est nécessaire :Telegram -> Gateway -> Agent -> node.* -> Nœud -> Gateway -> TelegramLes nœuds ne voient pas le trafic entrant du fournisseur ; ils reçoivent uniquement les appels RPC de nœud.
Associez votre ordinateur en tant que nœud. Le Gateway s’exécute ailleurs, mais peut appeler les outils node.* (écran, caméra, système) sur votre machine locale via le WebSocket du Gateway.
  1. Exécutez le Gateway sur l’hôte toujours actif (VPS/serveur domestique).
  2. Placez l’hôte du Gateway et votre ordinateur sur le même tailnet.
  3. Assurez-vous que le WS du Gateway est accessible (liaison au tailnet ou tunnel SSH).
  4. Ouvrez localement l’application macOS et connectez-vous en mode Remote over SSH (ou directement via le tailnet) afin qu’elle s’enregistre comme nœud.
  5. Approuvez le nœud :
Aucun pont TCP distinct n’est requis ; les nœuds se connectent via le WebSocket du Gateway.Rappel de sécurité : l’association d’un nœud macOS autorise system.run sur cette machine. Associez uniquement des appareils auxquels vous faites confiance ; consultez Sécurité.Documentation : Nœuds, Protocole du Gateway, Mode distant de macOS, Sécurité.
Vérifiez les éléments de base :
Vérifiez ensuite l’authentification et le routage : si vous utilisez Tailscale Serve, confirmez que gateway.auth.allowTailscale est correctement défini ; si vous vous connectez au moyen d’un tunnel SSH, confirmez que le tunnel est actif et pointe vers le bon port ; confirmez que les listes d’autorisation de vos messages privés/groupes incluent votre compte.Documentation : Tailscale, Accès à distance, Canaux.
Oui, bien qu’il n’existe pas de pont intégré entre bots.Solution la plus simple : utilisez un canal de discussion normal auquel les deux bots peuvent accéder (Slack/Telegram/WhatsApp). Faites en sorte que le bot A envoie un message au bot B, puis laissez le bot B répondre normalement.Pont CLI (générique) : exécutez un script qui appelle l’autre Gateway avec openclaw agent --message ... --deliver, en ciblant une discussion dans laquelle l’autre bot est à l’écoute. Si l’un des bots se trouve sur un VPS distant, faites pointer votre CLI vers ce Gateway distant via SSH/Tailscale (consultez Accès à distance) :
Ajoutez une protection afin que les deux bots ne bouclent pas indéfiniment (réponse uniquement aux mentions, listes d’autorisation des canaux ou règle « ne pas répondre aux messages des bots »).Documentation : Accès à distance, CLI de l’agent, Envoi par l’agent.
Non. Un seul Gateway héberge plusieurs agents, chacun disposant de son propre espace de travail, de ses modèles par défaut et de son routage : il s’agit de la configuration normale, bien moins coûteuse et plus simple qu’un VPS par agent. Utilisez des VPS distincts uniquement pour une isolation stricte (périmètres de sécurité) ou pour des configurations très différentes que vous ne souhaitez pas partager.
Oui : les Nodes constituent le moyen privilégié d’accéder à votre ordinateur portable depuis un Gateway distant et offrent bien plus qu’un accès à l’interpréteur de commandes. Le Gateway s’exécute sous macOS/Linux (Windows via WSL2) et reste léger (un petit VPS ou une machine de la catégorie Raspberry Pi convient ; 4 GB de RAM suffisent largement). Une configuration courante consiste donc à utiliser un hôte toujours actif et votre ordinateur portable comme Node.
  • Aucune connexion SSH entrante requise - les Nodes se connectent au WebSocket du Gateway au moyen de l’association d’appareils.
  • Contrôles d’exécution plus sûrs - system.run est soumis aux listes d’autorisation et aux approbations du Node sur cet ordinateur portable.
  • Davantage d’outils d’appareil - les Nodes exposent canvas, camera et screen en plus de system.run.
  • Automatisation locale du navigateur - conservez le Gateway sur un VPS, mais exécutez Chrome localement par l’intermédiaire d’un hôte Node, ou connectez-vous au Chrome local via Chrome MCP.
SSH convient pour un accès ponctuel à l’interpréteur de commandes ; les Nodes sont plus simples pour les flux de travail continus des agents et l’automatisation des appareils.Documentation : Nodes, CLI des Nodes, Navigateur.
Non. Un seul Gateway doit s’exécuter par hôte, sauf si vous exécutez intentionnellement des profils isolés (consultez Plusieurs Gateway). Les Nodes sont des périphériques qui se connectent au Gateway (Nodes iOS/Android ou « mode Node » macOS dans l’application de la barre des menus). Pour les hôtes Node sans interface graphique et le contrôle par CLI, consultez CLI de l’hôte Node.Un redémarrage complet est requis pour les modifications de gateway, de discovery et des surfaces des plugins hébergés.
Oui :
  • config.schema.lookup : inspecte une sous-arborescence de configuration avec son nœud de schéma superficiel, l’indication d’interface correspondante et les résumés de ses enfants immédiats avant l’écriture.
  • config.get : récupère l’instantané actuel et son hachage.
  • config.patch : mise à jour partielle sûre (préférée pour la plupart des modifications RPC) ; recharge à chaud lorsque cela est possible et redémarre lorsque cela est nécessaire.
  • config.apply : valide et remplace l’intégralité de la configuration ; recharge à chaud lorsque cela est possible et redémarre lorsque cela est nécessaire.
  • L’outil d’exécution gateway destiné aux agents refuse toujours de réécrire tools.exec.ask / tools.exec.security ; les anciens alias tools.bash.* sont normalisés vers les mêmes chemins protégés.
Définit votre espace de travail et limite les personnes autorisées à déclencher le bot.
  1. Installez Tailscale et connectez-vous sur le VPS :
  2. Installez Tailscale et connectez-vous sur votre Mac à l’aide de l’application Tailscale, sur le même tailnet.
  3. Activez MagicDNS dans la console d’administration Tailscale afin que le VPS dispose d’un nom stable.
  4. Utilisez le nom d’hôte du tailnet : SSH ssh user@your-vps.tailnet-xxxx.ts.net ; WS du Gateway ws://your-vps.tailnet-xxxx.ts.net:18789.
Pour accéder à l’interface de contrôle sans SSH, utilisez Tailscale Serve sur le VPS :
Cela maintient le Gateway lié à l’interface de bouclage et expose HTTPS via Tailscale. Consultez Tailscale.
Serve expose l’interface de contrôle du Gateway + WS ; les nœuds se connectent via le même point de terminaison WS du Gateway.
  1. Vérifiez que le VPS et le Mac se trouvent sur le même tailnet.
  2. Utilisez l’application macOS en mode distant (la cible SSH peut être le nom d’hôte du tailnet) : elle établit un tunnel vers le port du Gateway et se connecte en tant que nœud.
  3. Approuvez le nœud :
Documentation : Protocole du Gateway, Découverte, mode distant de macOS.
Pour utiliser uniquement des outils locaux (écran/caméra/exec) sur le deuxième ordinateur portable, ajoutez-le en tant que nœud : un seul Gateway, sans configuration dupliquée. Les outils de nœud locaux sont actuellement disponibles uniquement sous macOS. Installez un deuxième Gateway uniquement pour une isolation stricte ou pour deux bots entièrement distincts.Documentation : Nœuds, CLI des nœuds, Plusieurs Gateway.

Variables d’environnement et chargement des fichiers .env

OpenClaw lit les variables d’environnement du processus parent (shell, launchd/systemd, CI, etc.) et charge également :
  • le fichier .env du répertoire de travail actuel ;
  • un fichier .env global de secours depuis ~/.openclaw/.env ($OPENCLAW_STATE_DIR/.env).
Aucun des fichiers .env ne remplace les variables d’environnement existantes. Les clés d’identification des fournisseurs constituent une exception pour le fichier .env de l’espace de travail : les clés telles que GEMINI_API_KEY, XAI_API_KEY ou MISTRAL_API_KEY (ainsi que les autres variables d’environnement d’authentification des fournisseurs intégrés) sont ignorées dans le fichier .env de l’espace de travail et doivent être définies dans l’environnement du processus, dans ~/.openclaw/.env ou dans la configuration env.Les variables d’environnement intégrées à la configuration ne s’appliquent que si elles sont absentes de l’environnement du processus :
Consultez /environment pour connaître l’ordre de priorité complet et toutes les sources.
Deux solutions :
  1. Placez les clés manquantes dans ~/.openclaw/.env afin qu’elles soient chargées même lorsque le service n’hérite pas de l’environnement de votre shell.
  2. Activez l’importation depuis le shell (fonction pratique facultative) :
    Cette option exécute votre shell de connexion et importe uniquement les clés attendues manquantes (sans jamais remplacer les clés existantes). Variables d’environnement équivalentes : OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.
openclaw models status indique si l’importation depuis l’environnement du shell est activée. “Shell env: off” ne signifie pas que vos variables d’environnement sont absentes : cela signifie simplement qu’OpenClaw ne chargera pas automatiquement votre shell de connexion.Si le Gateway s’exécute en tant que service (launchd/systemd), il n’héritera pas de l’environnement de votre shell. Pour résoudre ce problème, placez le jeton dans ~/.openclaw/.env, activez env.shellEnv.enabled: true ou ajoutez-le à la configuration env (cela s’applique uniquement s’il est absent), puis redémarrez le Gateway et vérifiez de nouveau :
Les jetons Copilot sont recherchés dans cet ordre : OPENCLAW_GITHUB_TOKEN, puis COPILOT_GITHUB_TOKEN, puis GH_TOKEN, puis GITHUB_TOKEN.Consultez /concepts/model-providers et /environment.

Sessions et conversations multiples

Envoyez /new ou /reset comme message autonome. Consultez Gestion des sessions.
Oui. La stratégie de réinitialisation par défaut est quotidienne : une nouvelle session commence à une heure locale configurée sur l’hôte du Gateway (session.reset.atHour, valeur par défaut 4, 0-23), en fonction de l’heure de démarrage de la session actuelle. Pour utiliser plutôt une réinitialisation fondée sur l’inactivité, définissez mode: "idle" et session.reset.idleMinutes, ce qui fait expirer une session après une période d’inactivité (selon la dernière interaction réelle, et non les événements système Heartbeat/Cron/exec).
resetByType prend en charge direct (ancien alias dm), group et thread. L’ancien paramètre de premier niveau session.idleMinutes fonctionne toujours comme alias de compatibilité pour une valeur par défaut en mode inactif lorsqu’aucun bloc session.reset/resetByType n’est défini. Les sessions associées à une session CLI active appartenant au fournisseur ne sont pas interrompues par la réinitialisation quotidienne implicite par défaut. Consultez Gestion des sessions pour connaître le cycle de vie complet.
Oui, grâce au routage multi-agent et aux sous-agents : un agent coordinateur et plusieurs agents de travail disposant de leurs propres espaces de travail et modèles.Il vaut mieux considérer cela comme une expérience ludique : cette approche consomme beaucoup de jetons et est souvent moins efficace qu’un seul bot utilisant des sessions distinctes. Le modèle habituel consiste à utiliser un bot avec lequel vous dialoguez, différentes sessions pour le travail en parallèle et des sous-agents créés selon les besoins.Documentation : Routage multi-agent, Sous-agents, CLI des agents.
Le contexte de la session est limité par la fenêtre du modèle. Les conversations longues, les sorties d’outils volumineuses ou les nombreux fichiers peuvent déclencher une Compaction ou une troncation.
  • Demandez au bot de résumer l’état actuel et de l’écrire dans un fichier.
  • Utilisez /compact avant les tâches longues et /new lorsque vous changez de sujet.
  • Conservez le contexte important dans l’espace de travail et demandez au bot de le relire.
  • Utilisez des sous-agents pour les travaux longs ou parallèles afin de réduire la taille de la conversation principale.
  • Choisissez un modèle doté d’une fenêtre de contexte plus grande si cela se produit souvent.
Réinitialisation complète non interactive :
Relancez ensuite la configuration :
L’intégration propose également Réinitialiser si elle détecte une configuration existante ; consultez Intégration (CLI). Si vous avez utilisé des profils (--profile / OPENCLAW_PROFILE), réinitialisez chaque répertoire d’état (par défaut ~/.openclaw-<profile>). Réinitialisation réservée au développement : openclaw gateway --dev --reset efface la configuration de développement, les identifiants, les sessions et l’espace de travail.
  • Compaction (conserve la conversation et résume les échanges plus anciens) : /compact ou /compact <instructions> pour orienter le résumé.
  • Réinitialisation (nouvel identifiant de session pour la même clé de conversation) : /new ou /reset.
Si le problème persiste, ajustez l’élagage des sessions (agents.defaults.contextPruning) pour supprimer les anciennes sorties d’outils ou utilisez un modèle doté d’une fenêtre de contexte plus grande.Documentation : Compaction, Élagage des sessions, Gestion des sessions.
Erreur de validation du fournisseur : le modèle a généré un bloc tool_use sans le champ input requis. Cela signifie généralement que l’historique de la session est obsolète ou corrompu (souvent après de longues discussions ou une modification d’outil/de schéma).Solution : démarrez une nouvelle session avec /new (message autonome).
Les Heartbeat s’exécutent toutes les 30m par défaut, ou toutes les 1h lorsque le mode d’authentification déterminé est l’authentification OAuth/par jeton d’Anthropic (y compris la réutilisation de Claude CLI) et que heartbeat.every n’est pas défini. Pour ajuster la fréquence ou les désactiver :
Si HEARTBEAT.md existe, mais est effectivement vide (uniquement des lignes vides, des commentaires Markdown/HTML, des titres ATX, des marqueurs de bloc délimité ou des éléments de liste vides), OpenClaw ignore l’exécution du Heartbeat afin d’économiser des appels d’API. Si le fichier est absent, le Heartbeat s’exécute tout de même et le modèle décide de l’action à entreprendre.Les remplacements propres à chaque agent utilisent agents.list[].heartbeat. Documentation : Heartbeat.
Non. OpenClaw fonctionne avec votre propre compte : si vous appartenez au groupe, OpenClaw peut le voir. Par défaut, les réponses dans les groupes sont bloquées jusqu’à ce que vous autorisiez les expéditeurs (groupPolicy: "allowlist").Pour limiter les réponses dans les groupes à vous seul :
Méthode la plus rapide : suivez les journaux et envoyez un message de test dans le groupe.
Recherchez chatId (ou from) se terminant par @g.us, par exemple 1234567890-1234567890@g.us.Si les groupes sont déjà configurés ou ajoutés à la liste d’autorisation, affichez-les depuis la configuration :
Documentation : WhatsApp, Annuaire, Journaux.
Deux causes courantes : le filtrage par mention est activé par défaut (vous devez @mentionner le bot ou correspondre à mentionPatterns), ou vous avez configuré channels.whatsapp.groups sans "*" et le groupe ne figure pas dans la liste d’autorisation.Consultez Groupes et Messages de groupe.
Les conversations directes sont regroupées dans la session principale par défaut. Les groupes/canaux possèdent leurs propres clés de session, et les sujets Telegram/fils de discussion Discord constituent des sessions distinctes. Consultez Groupes et Messages de groupe.
Il n’existe aucune limite stricte : plusieurs dizaines, voire plusieurs centaines, conviennent, mais surveillez les éléments suivants :
  • Croissance de l’espace disque : les sessions actives et les transcriptions sont stockées dans la base de données SQLite propre à chaque agent ; les anciens artefacts ou les archives peuvent encore s’accumuler sous ~/.openclaw/agents/<agentId>/sessions/.
  • Coût en jetons : davantage d’agents implique une utilisation simultanée accrue des modèles.
  • Charge opérationnelle : profils d’authentification, espaces de travail et routage des canaux propres à chaque agent.
Conservez un espace de travail actif par agent (agents.defaults.workspace), élaguez les anciennes sessions avec openclaw sessions cleanup si l’espace disque augmente (ne modifiez pas manuellement l’état SQLite actif) et utilisez openclaw doctor pour repérer les espaces de travail parasites et les incohérences de profils.
Oui, grâce au routage multi-agent : exécutez plusieurs agents isolés et routez les messages entrants selon le canal, le compte ou le pair. Slack est pris en charge comme canal et peut être associé à des agents précis.L’accès au navigateur est puissant, mais ne permet pas de « faire tout ce qu’un humain peut faire » : les protections anti-bot, les CAPTCHA et l’authentification multifacteur peuvent toujours bloquer l’automatisation. Pour un contrôle plus fiable, utilisez Chrome MCP localement sur l’hôte ou CDP sur la machine qui exécute réellement le navigateur.Configuration recommandée : hôte du Gateway toujours actif (VPS/Mac mini), un agent par rôle (liaisons), canal ou canaux Slack liés à ces agents, et navigateur local via Chrome MCP ou un Node si nécessaire.Documentation : Routage multi-agent, Slack, Navigateur, Nodes.

Modèles, basculement et profils d’authentification

La FAQ sur les modèles — valeurs par défaut, sélection, alias, changement, basculement, profils d’authentification — se trouve dans la FAQ sur les modèles.

Gateway : ports, « déjà en cours d’exécution » et mode distant

gateway.port contrôle le port multiplexé unique pour WebSocket + HTTP (interface de contrôle, hooks, etc.). Ordre de priorité :
« Running » correspond au point de vue du superviseur (launchd/systemd/schtasks) ; la sonde de connectivité correspond à la CLI qui se connecte réellement au WebSocket du Gateway. Fiez-vous à ces lignes de openclaw gateway status : Probe target: (l’URL utilisée par la sonde), Listening: (ce qui écoute réellement sur le port), Last gateway error: (cause racine courante lorsque le processus est actif, mais que le port n’est pas en écoute).
Vous modifiez un fichier de configuration tandis que le service en utilise un autre (souvent en raison d’une divergence de --profile / OPENCLAW_STATE_DIR).Pour corriger le problème, exécutez cette commande avec le même --profile / environnement que celui que le service doit utiliser :
OpenClaw applique un verrou d’exécution en liant immédiatement l’écouteur WebSocket au démarrage (ws://127.0.0.1:18789 par défaut). Si la liaison échoue avec EADDRINUSE, il lève GatewayLockError (« another gateway instance is already listening »).Solution : arrêtez l’autre instance, libérez le port ou exécutez openclaw gateway --port <port>.
Définissez gateway.mode: "remote" et indiquez une URL WebSocket distante, éventuellement avec des identifiants distants à secret partagé :
  • openclaw gateway ne démarre que lorsque gateway.mode vaut local (ou si vous transmettez une option de remplacement).
  • L’application macOS surveille le fichier de configuration et change de mode à chaud lorsque ces valeurs changent.
  • gateway.remote.token / .password sont uniquement des identifiants distants côté client ; ils n’activent pas à eux seuls l’authentification du Gateway local.
Le chemin d’authentification de votre Gateway et la méthode d’authentification de l’interface ne correspondent pas.Faits (issus du code) :
  • L’interface de contrôle conserve le jeton dans sessionStorage, limité à l’onglet actuel du navigateur et à l’URL du Gateway sélectionnée ; les actualisations dans le même onglet continuent donc de fonctionner sans persistance durable du jeton dans localStorage.
  • En cas de AUTH_TOKEN_MISMATCH, les clients de confiance peuvent effectuer une tentative supplémentaire limitée avec un jeton d’appareil mis en cache lorsque le Gateway renvoie des indications de nouvelle tentative (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
  • Cette nouvelle tentative avec le jeton mis en cache réutilise les portées approuvées mises en cache avec le jeton d’appareil ; les appelants fournissant explicitement deviceToken / scopes conservent les portées demandées au lieu d’hériter de celles du cache.
  • En dehors de ce chemin de nouvelle tentative, l’ordre de priorité de l’authentification à la connexion est le suivant : jeton partagé ou mot de passe explicite, puis deviceToken explicite, puis jeton d’appareil enregistré, puis jeton d’amorçage.
  • L’amorçage intégré par code de configuration renvoie un jeton d’appareil Node avec scopes: [], ainsi qu’un jeton limité de transfert à l’opérateur pour l’intégration mobile de confiance. Le transfert à l’opérateur peut lire la configuration native au moment de la configuration, mais n’accorde ni les portées de modification de l’association ni operator.admin.
Solution :
  • Méthode la plus rapide : openclaw dashboard (affiche et copie l’URL du tableau de bord, puis tente de l’ouvrir ; affiche une indication SSH en mode sans interface graphique).
  • Aucun jeton pour le moment : openclaw doctor --generate-gateway-token.
  • À distance : créez d’abord un tunnel avec ssh -N -L 18789:127.0.0.1:18789 user@host, puis ouvrez http://127.0.0.1:18789/.
  • Mode à secret partagé : définissez gateway.auth.token / OPENCLAW_GATEWAY_TOKEN ou gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, puis collez le secret correspondant dans les paramètres de l’interface de contrôle.
  • Mode Tailscale Serve : vérifiez que gateway.auth.allowTailscale est activé et que vous ouvrez l’URL Serve, et non une URL loopback/tailnet brute qui contourne les en-têtes d’identité Tailscale.
  • Mode proxy de confiance : vérifiez que vous passez par le proxy configuré avec gestion des identités. Les proxys loopback sur le même hôte nécessitent également gateway.auth.trustedProxy.allowLoopback = true.
  • Si la divergence persiste après l’unique nouvelle tentative : renouvelez et réapprouvez le jeton de l’appareil associé :
  • Renouvellement refusé : les sessions d’appareils associés ne peuvent renouveler que le jeton de leur propre appareil, sauf si elles disposent également de operator.admin, et les valeurs --scope explicites ne peuvent pas dépasser les portées d’opérateur actuelles de l’appelant.
  • Toujours bloqué : exécutez openclaw status --all et consultez le Dépannage. Consultez le Tableau de bord pour les détails d’authentification.
La liaison tailnet sélectionne une adresse IP Tailscale parmi vos interfaces réseau (100.64.0.0/10). Si la machine n’est pas connectée à Tailscale (ou si l’interface est inactive), le Gateway revient à loopback au lieu d’exposer une autre interface réseau.Solution : démarrez Tailscale sur cet hôte et redémarrez le Gateway, ou passez explicitement à gateway.bind: "loopback" / "lan".tailnet est explicite ; auto privilégie loopback. Utilisez gateway.bind: "tailnet" pour limiter l’exposition hors loopback au Tailnet tout en conservant l’écouteur 127.0.0.1 requis sur le même hôte.
Généralement non : un Gateway peut gérer plusieurs canaux de messagerie et agents. N’utilisez plusieurs Gateways que pour la redondance (par exemple, un bot de secours) ou une isolation stricte, et isolez chacun avec ses propres OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, agents.defaults.workspace et un gateway.port unique.Recommandation : utilisez openclaw --profile <name> ... pour chaque instance (crée automatiquement ~/.openclaw-<name>), un gateway.port unique dans la configuration de chaque profil (ou --port pour les exécutions manuelles), ainsi qu’un service par profil avec openclaw --profile <name> gateway install.Les profils ajoutent également un suffixe aux noms des services : launchd ai.openclaw.<profile>, systemd openclaw-gateway-<profile>.service, Windows OpenClaw Gateway (<profile>). L’unité systemd non qualifiée openclaw-gateway n’existe que pour le profil par défaut ; l’ancien nom d’unité systemd antérieur au changement de nom, clawdbot-gateway, est migré automatiquement.Guide complet : Gateways multiples.
Le Gateway est un serveur WebSocket et attend une trame connect comme premier message. Tout autre message ferme la connexion avec le code 1008 (violation de la politique).Causes courantes : vous avez ouvert l’URL HTTP dans un navigateur au lieu d’utiliser un client WS, utilisé le mauvais port ou chemin, ou un proxy/tunnel a supprimé les en-têtes d’authentification ou envoyé une requête ne provenant pas du Gateway.Solution : utilisez l’URL WS (ws://<host>:18789 ou wss://... via HTTPS), n’ouvrez pas le port WS dans un onglet de navigateur normal et incluez le jeton ou le mot de passe dans la trame connect lorsque l’authentification est activée. Exemple avec la CLI/TUI :
Détails du protocole : Protocole du Gateway.

Journalisation et débogage

Journaux dans un fichier (structurés) : /tmp/openclaw/openclaw-YYYY-MM-DD.log. Définissez un chemin stable via logging.file, le niveau de journalisation du fichier via logging.level et la verbosité de la console via --verbose et logging.consoleLevel.Commande la plus rapide pour les suivre :
Journaux du service/superviseur (lorsque le Gateway s’exécute via launchd/systemd) :
  • Sortie standard de launchd sous macOS : ~/Library/Logs/openclaw/gateway.log (les profils utilisent gateway-<profile>.log ; la sortie d’erreur standard est supprimée).
  • Linux : journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager.
  • Windows : schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST.
Consultez le Dépannage pour en savoir plus.
Si vous exécutez le Gateway manuellement, openclaw gateway --force peut récupérer le port. Consultez Gateway.
Trois modes d’installation sous Windows :1) Configuration locale du Windows Hub : l’application native gère un Gateway WSL local appartenant à l’application. Ouvrez OpenClaw Companion depuis le menu Démarrer ou la zone de notification, puis utilisez Gateway Setup ou l’onglet Connections.2) Gateway WSL2 manuel : le Gateway s’exécute dans Linux.
Si vous n’avez jamais installé le service, démarrez-le au premier plan : openclaw gateway run.3) CLI/Gateway Windows natif : s’exécute directement sous Windows.
Si vous l’exécutez manuellement (sans service) : openclaw gateway run.Documentation : Windows, Guide opérationnel du service Gateway.
Vérification rapide de l’état :
Causes courantes : l’authentification du modèle n’est pas chargée sur l’hôte du Gateway (vérifiez models status), l’association du canal ou la liste d’autorisation bloque les réponses (vérifiez la configuration du canal et les journaux), ou WebChat/le tableau de bord est ouvert sans le bon jeton. En cas d’accès distant, vérifiez que le tunnel ou la connexion Tailscale est actif et que le WebSocket du Gateway est accessible.Documentation : Canaux, Dépannage, Accès distant.
Cela signifie généralement que l’interface a perdu la connexion WebSocket. Vérifiez : le Gateway est-il en cours d’exécution (openclaw gateway status) ? Est-il opérationnel (openclaw status) ? L’interface dispose-t-elle du bon jeton (openclaw dashboard) ? En cas d’accès distant, le tunnel ou la liaison Tailscale est-il actif ?Consultez ensuite les journaux en temps réel :
Documentation : Tableau de bord, Accès distant, Dépannage.
Faites ensuite correspondre l’erreur :
  • BOT_COMMANDS_TOO_MUCH : le menu Telegram comporte trop d’entrées. OpenClaw réduit déjà le nombre d’entrées à la limite de Telegram et réessaie avec moins de commandes, mais certaines entrées du menu peuvent tout de même être omises. Réduisez les commandes de plugins, de Skills ou personnalisées, ou désactivez channels.telegram.commands.native si vous n’avez pas besoin du menu.
  • TypeError: fetch failed, Network request for 'setMyCommands' failed! ou erreurs réseau similaires : sur un VPS ou derrière un proxy, vérifiez que les connexions HTTPS sortantes sont autorisées et que la résolution DNS fonctionne pour api.telegram.org.
Si le Gateway est distant, consultez les journaux sur l’hôte du Gateway.Documentation : Telegram, Dépannage des canaux.
Dans la TUI, utilisez /status pour afficher l’état actuel. Si vous attendez des réponses dans un canal de discussion, vérifiez que la distribution est activée (/deliver on).Documentation : TUI, Commandes slash.
Si vous avez installé le service (launchd sous macOS, systemd sous Linux) :
Au premier plan, arrêtez-le avec Ctrl-C, puis exécutez openclaw gateway run.Documentation : Guide d’exploitation du service Gateway.
openclaw gateway restart redémarre le service en arrière-plan (launchd/systemd). openclaw gateway exécute le Gateway au premier plan pour cette session de terminal. Utilisez les sous-commandes du Gateway si vous avez installé le service ; utilisez l’exécution directe au premier plan pour une utilisation ponctuelle.
Démarrez le Gateway avec --verbose pour obtenir davantage de détails dans la console, puis examinez le fichier journal pour rechercher les erreurs d’authentification des canaux, de routage des modèles et de RPC.

Médias et pièces jointes

Les pièces jointes sortantes de l’agent doivent utiliser des champs de média structurés tels que media, mediaUrl, path ou filePath. Consultez Configuration de l’assistant OpenClaw et Envoi par l’agent.
Vérifiez également que le canal cible prend en charge les médias sortants et n’est pas bloqué par des listes d’autorisation ; que le fichier respecte les limites de taille du fournisseur (les images sont redimensionnées pour que leur côté maximal ne dépasse pas 2048px) ; tools.fs.workspaceOnly=true limite les envois depuis des chemins locaux aux fichiers de l’espace de travail, du stockage temporaire/de médias et validés par le bac à sable ; tools.fs.workspaceOnly=false (valeur par défaut) permet aux envois structurés de médias locaux d’utiliser les fichiers locaux de l’hôte que l’agent peut déjà lire, pour les médias ainsi que les types de documents sûrs (images, audio, vidéo, PDF, documents Office et documents texte validés tels que Markdown/MD, TXT, JSON, YAML/YML). Il ne s’agit pas d’un détecteur de secrets : un fichier secret.txt ou config.json lisible par l’agent peut être joint si son extension et son contenu satisfont à la validation. Conservez les fichiers sensibles hors des chemins accessibles à l’agent, ou gardez tools.fs.workspaceOnly=true pour imposer des restrictions plus strictes aux envois depuis des chemins locaux.Consultez Images.

Sécurité et contrôle d’accès

Traitez les messages privés entrants comme des données non fiables. Les valeurs par défaut réduisent les risques :
  • Le comportement par défaut des canaux prenant en charge les messages privés est l’appairage : les expéditeurs inconnus reçoivent un code d’appairage et leur message n’est pas traité. Approuvez-les avec openclaw pairing approve --channel <channel> [--account <id>] <code>. Le nombre de demandes en attente est limité à 3 par canal ; consultez openclaw pairing list --channel <channel> [--account <id>] si aucun code n’est arrivé.
  • L’ouverture publique des messages privés nécessite une activation explicite (dmPolicy: "open" et liste d’autorisation "*").
Exécutez openclaw doctor pour détecter les politiques de messages privés risquées.
Non. L’injection de prompt concerne le contenu non fiable, et pas seulement les personnes autorisées à envoyer des messages privés au bot. Si votre assistant lit du contenu externe (recherche/récupération sur le Web, pages de navigateur, e-mails, documents, pièces jointes, journaux collés), ce contenu peut contenir des instructions visant à détourner le modèle, même si vous êtes le seul expéditeur.Le risque est maximal lorsque des outils sont activés : le modèle peut être manipulé afin d’exfiltrer le contexte ou d’appeler des outils en votre nom. Réduisez l’étendue des conséquences :
  • utilisez un agent « lecteur » en lecture seule ou sans outils pour résumer le contenu non fiable
  • désactivez web_search / web_fetch / browser pour les agents ayant accès aux outils
  • traitez également comme non fiable le texte décodé des fichiers et documents : l’extraction de input_file d’OpenResponses et celle des pièces jointes multimédias encadrent toutes deux le texte extrait par des marqueurs explicites de délimitation du contenu externe au lieu de transmettre directement le texte brut du fichier
  • utilisez un bac à sable et des listes d’autorisation d’outils strictes
Détails : Sécurité.
Le langage et l’environnement d’exécution comptent, mais ils ne constituent pas le risque principal pour un agent personnel. Les risques concrets concernent l’exposition du Gateway, les personnes autorisées à envoyer des messages au bot, l’injection de prompt, la portée des outils, la gestion des identifiants, l’accès au navigateur, l’accès à l’exécution de commandes et la confiance accordée aux Skills/plugins tiers.Rust et WASM peuvent offrir une isolation plus forte pour certaines catégories de code, mais ils ne résolvent pas l’injection de prompt, les mauvaises listes d’autorisation, l’exposition publique du Gateway, les outils dotés d’autorisations excessives ni un profil de navigateur déjà connecté à des comptes sensibles. Considérez les mesures suivantes comme les principaux contrôles : gardez le Gateway privé ou authentifié, utilisez l’appairage et des listes d’autorisation pour les messages privés/groupes, refusez les outils risqués ou exécutez-les dans un bac à sable pour les données non fiables, n’installez que des plugins et Skills de confiance, puis exécutez openclaw security audit --deep après toute modification de la configuration.Détails : Sécurité, Mise en bac à sable.
Une configuration de référence plus sûre : Gateway lié à loopback, ou exposé uniquement par un accès privé authentifié (tailnet, tunnel SSH, authentification par jeton/mot de passe ou proxy de confiance correctement configuré) ; messages privés en mode pairing ou allowlist ; groupes placés sur liste d’autorisation et soumis à l’obligation de mention, sauf si tous les membres sont de confiance ; outils à haut risque (exec, browser, gateway, cron) refusés ou strictement limités pour les agents qui lisent du contenu non fiable ; mise en bac à sable activée lorsque l’exécution d’outils nécessite de réduire l’étendue des conséquences.Les liaisons publiques sans authentification, les messages privés/groupes ouverts avec des outils et le contrôle du navigateur exposé sont les problèmes à corriger en premier. Détails : openclaw security audit.
Traitez les Skills et plugins tiers comme du code auquel vous choisissez d’accorder votre confiance. Les pages des Skills ClawHub affichent l’état de l’analyse avant l’installation, mais ces analyses ne constituent pas une frontière de sécurité complète. OpenClaw n’exécute pas de blocage local intégré du code dangereux lors de l’installation ou de la mise à jour des plugins/Skills ; utilisez la stratégie security.installPolicy gérée par l’opérateur pour les décisions locales d’autorisation ou de blocage.Approche plus sûre : privilégiez les auteurs de confiance et les versions épinglées, lisez la Skill ou le plugin avant de l’activer, limitez strictement les listes d’autorisation de plugins/Skills, exécutez les processus traitant des données non fiables dans un bac à sable avec un minimum d’outils et évitez d’accorder au code tiers un accès étendu au système de fichiers, à l’exécution de commandes, au navigateur ou aux secrets.Détails : Skills, Plugins, Sécurité.
Oui, pour la plupart des configurations. Isoler le bot avec des comptes et des numéros de téléphone distincts réduit l’étendue des conséquences en cas de problème et facilite la rotation des identifiants ou la révocation des accès sans affecter vos comptes personnels.Commencez avec un périmètre réduit : n’accordez l’accès qu’aux outils et aux comptes dont vous avez réellement besoin, puis élargissez-le ultérieurement si nécessaire.Documentation : Sécurité, Appairage.
Nous ne recommandons pas une autonomie totale sur vos messages personnels. Approche la plus sûre : conservez les messages privés en mode d’appairage ou utilisez une liste d’autorisation stricte, utilisez un numéro ou un compte distinct s’il doit envoyer des messages en votre nom, et laissez-le préparer des brouillons que vous approuvez avant l’envoi.Pour expérimenter, utilisez un compte dédié et isolé. Consultez Sécurité.
Oui, si l’agent est limité à la discussion et que les données d’entrée sont fiables. Les modèles des gammes inférieures sont plus vulnérables au détournement par des instructions ; évitez-les donc pour les agents ayant accès à des outils ou lisant du contenu non fiable. Si vous devez utiliser un modèle plus petit, restreignez les outils et exécutez-le dans un bac à sable. Consultez Sécurité.
Les codes d’appairage sont envoyés uniquement lorsqu’un expéditeur inconnu envoie un message au bot et que dmPolicy: "pairing" est activé ; /start seul ne génère aucun code.Consultez les demandes en attente :
Pour obtenir un accès immédiat, ajoutez votre identifiant d’expéditeur à la liste d’autorisation ou définissez dmPolicy: "open" pour ce compte.
Non. La politique par défaut des messages privés WhatsApp est l’appairage. Les expéditeurs inconnus reçoivent uniquement un code d’appairage ; leur message n’est pas traité. OpenClaw répond uniquement aux discussions qu’il reçoit ou aux envois explicites que vous déclenchez.
L’invite de numéro de téléphone de l’assistant de configuration définit votre liste d’autorisation/propriétaire afin d’autoriser vos propres messages privés ; elle n’est pas utilisée pour l’envoi automatique. Avec votre numéro WhatsApp personnel, utilisez ce numéro et activez channels.whatsapp.selfChatMode.

Commandes de discussion, interruption des tâches et « il ne s’arrête pas »

La plupart des messages internes ou des messages d’outils n’apparaissent que lorsque le mode détaillé, trace ou raisonnement est activé pour cette session.Corrigez ce réglage dans la discussion où ils apparaissent :
Si le bruit persiste : vérifiez les paramètres de la session dans l’interface de contrôle et définissez le mode détaillé sur hériter ; vérifiez que vous n’utilisez pas un profil de bot comportant verboseDefault: "on" dans la configuration.Documentation : Réflexion et mode détaillé, Sécurité.
Envoyez l’un des éléments suivants comme message autonome (sans barre oblique) pour déclencher une interruption : stop, stop action, stop current action, stop run, stop current run, stop agent, stop the agent, stop openclaw, openclaw stop, stop don't do anything, stop do not do anything, stop doing anything, do not do that, please stop, stop please, abort, esc, exit, interrupt, halt. Les déclencheurs courants dans d’autres langues (français, allemand, espagnol, chinois, japonais, hindi, arabe et russe) fonctionnent également.Pour les processus en arrière-plan démarrés par l’outil exec, demandez à l’agent d’exécuter :
La plupart des commandes slash doivent être envoyées sous forme de message autonome commençant par /, mais quelques raccourcis (comme /status) fonctionnent également au sein d’un message pour les expéditeurs figurant sur la liste d’autorisation. Consultez Commandes slash.
OpenClaw bloque par défaut la messagerie entre fournisseurs. Si un appel d’outil est lié à Telegram, il n’enverra pas de message à Discord sauf si vous l’autorisez explicitement — cette modification prend effet immédiatement, sans redémarrage du Gateway :
Par défaut, les invites reçues pendant une exécution sont dirigées vers l’exécution active. Utilisez /queue pour choisir le comportement de l’exécution active :
  • steer (par défaut) — guide l’exécution active à la prochaine limite du modèle.
  • followup — met les messages en file d’attente et les exécute un par un après la fin de l’exécution en cours.
  • collect — met les messages compatibles en file d’attente et répond une seule fois après la fin de l’exécution en cours.
  • interrupt — interrompt l’exécution en cours et en démarre une nouvelle.
Ajoutez des options aux modes de mise en file d’attente, comme debounce:0.5s cap:25 drop:summarize. Consultez File d’attente des commandes et File d’attente de guidage.

Divers

Les identifiants et la sélection du modèle sont distincts. Définir ANTHROPIC_API_KEY (ou stocker une clé API Anthropic dans les profils d’authentification) active l’authentification, mais le modèle réellement utilisé par défaut est celui que vous configurez dans agents.defaults.model.primary (par exemple anthropic/claude-sonnet-4-6 ou anthropic/claude-opus-4-6). No credentials found for profile "anthropic:default" signifie que le Gateway n’a pas trouvé les identifiants Anthropic dans le fichier auth-profiles.json attendu pour l’agent en cours d’exécution.

Toujours bloqué ? Posez votre question sur Discord ou ouvrez une discussion GitHub.

Pages connexes