Skip to main content
Porte d’entrée du triage. 2 minutes pour établir un diagnostic, puis passez à la page détaillée.

​
Les 60 premières secondes

Exécutez cette séquence dans l’ordre :
Sortie correcte, une ligne pour chaque commande :
  • openclaw status affiche les canaux configurés, sans erreur d’authentification.
  • openclaw status --all produit un rapport complet et partageable.
  • openclaw gateway probe affiche Reachable: yes. Capability: ... correspond au niveau d’authentification confirmé par la sonde ; Read probe: limited - missing scope: operator.read indique un diagnostic dégradé, et non un échec de connexion.
  • openclaw gateway status affiche Runtime: running, Connectivity probe: ok et une valeur plausible pour Capability: .... Ajoutez --require-rpc pour exiger également une validation RPC de la portée de lecture.
  • openclaw doctor ne signale aucune erreur bloquante de configuration ou de service.
  • openclaw channels status --probe renvoie l’état réel du transport pour chaque compte (works / audit ok) lorsque le Gateway est accessible ; sinon, la commande se rabat sur des résumés fondés uniquement sur la configuration.
  • openclaw logs --follow affiche une activité régulière, sans erreurs fatales répétées.

​
L’assistant semble limité ou certains outils sont absents

Vérifiez le profil d’outils effectif :
Causes courantes :
  • tools.profile: "minimal" autorise uniquement session_status.
  • tools.profile: "messaging" est restreint et destiné aux agents de discussion uniquement.
  • tools.profile: "coding" est le profil par défaut des nouvelles configurations locales (travail sur les dépôts, les fichiers, le shell et l’environnement d’exécution).
  • tools.profile: "full" supprime les restrictions du profil ; réservez-le aux agents de confiance contrôlés par un opérateur.
  • La configuration agents.list[].tools propre à chaque agent restreint ou étend le profil racine pour cet agent.
Modifiez le profil, redémarrez ou rechargez le Gateway, puis vérifiez à nouveau avec openclaw status --all. Tableau complet des profils et groupes : Profils d’outils.

​
Erreur 429 d’Anthropic avec un contexte long

HTTP 429: rate_limit_error: Extra usage is required for long context requests → Utilisation supplémentaire requise pour les contextes longs lors d’une erreur 429 d’Anthropic.

​
Le backend local compatible avec OpenAI fonctionne directement, mais échoue dans OpenClaw

Votre backend /v1 local ou auto-hébergé répond aux sondes directes /v1/chat/completions, mais échoue avec openclaw infer model run ou pendant les interactions normales d’un agent :
  1. Si l’erreur indique que messages[].content doit être une chaîne, définissez models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. Si l’échec persiste uniquement pendant les interactions des agents OpenClaw, définissez models.providers.<provider>.models[].compat.supportsTools: false, puis réessayez.
  3. Si les petits appels directs fonctionnent, mais que les requêtes OpenClaw plus volumineuses font planter le backend, il s’agit d’une limite du modèle ou du serveur en amont, et non d’un bogue d’OpenClaw. Poursuivez avec Le backend local compatible avec OpenAI réussit les sondes directes, mais les exécutions d’agents échouent.

​
L’installation du Plugin échoue en raison de l’absence d’extensions OpenClaw

package.json missing openclaw.extensions signifie que le paquet du Plugin utilise une structure qu’OpenClaw n’accepte plus. Correctif dans le paquet du Plugin :
  1. Ajoutez openclaw.extensions à package.json en le faisant pointer vers les fichiers compilés de l’environnement d’exécution (généralement ./dist/index.js).
  2. Republiez le paquet, puis exécutez à nouveau openclaw plugins install <package>.
Référence : Architecture des Plugins

​
La politique d’installation bloque l’installation ou la mise à jour des Plugins

La mise à jour se termine, mais les Plugins sont obsolètes, désactivés ou affichent blocked by install policy, install policy failed closed ou Disabled "<plugin>" after plugin update failure : vérifiez security.installPolicy. La politique d’installation s’applique aux installations et mises à jour des Plugins. Les versions des Plugins @openclaw/* évoluent normalement avec la version d’OpenClaw ; une mise à jour d’OpenClaw peut donc nécessiter une mise à jour correspondante des Plugins pendant la synchronisation qui suit la mise à jour. Évitez les formes de politique suivantes, sauf si vous maintenez également la règle de mise à niveau correspondante :
  • Verrouiller les Plugins appartenant à OpenClaw sur une seule ancienne version exacte (par exemple uniquement @openclaw/*@2026.5.3).
  • Bloquer uniquement selon le type de source (toutes les requêtes npm, réseau ou request.mode: "update").
  • Considérer la commande de politique comme facultative : lorsque security.installPolicy est activé, l’absence, la lenteur, l’illisibilité ou le blocage par les permissions de l’exécutable de politique provoque un échec par défaut.
  • Approuver des versions sans comparer la valeur openclawVersion de la requête aux métadonnées du Plugin candidat.
Préférez des règles qui autorisent les mises à jour fiables de @openclaw/* compatibles avec l’hôte actuel plutôt que de verrouiller indéfiniment une version. Si vous bloquez npm par défaut, ajoutez une exception restreinte pour les identifiants des Plugins que vous utilisez et appliquez à request.mode: "update" la même règle de confiance qu’aux installations. Récupération :
Si la politique est volontairement stricte, assouplissez-la pendant la période de mise à niveau fiable, réexécutez openclaw plugins update --all, puis rétablissez la règle plus stricte. Si l’échec de la mise à jour a désactivé un Plugin, inspectez-le avant de le réactiver :
Référence : Politique d’installation de l’opérateur

​
Le Plugin est présent, mais bloqué en raison d’un propriétaire suspect

openclaw doctor, la configuration ou les avertissements de démarrage affichent :
Les fichiers du Plugin appartiennent à un utilisateur Unix différent de celui du processus qui les charge. Ne supprimez pas la configuration du Plugin ; corrigez le propriétaire des fichiers ou exécutez OpenClaw avec l’utilisateur propriétaire du répertoire d’état. Les installations Docker s’exécutent avec l’utilisateur node (uid 1000). Corrigez les montages liés de l’hôte :
Si vous exécutez volontairement OpenClaw en tant que superutilisateur, corrigez plutôt la racine gérée des Plugins :
Documentation détaillée : Propriétaire bloquant du chemin d’un Plugin, Docker : permissions et EACCES

​
Arbre de décision

Sortie correcte :
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable ou admin-capable
  • Le canal indique que le transport est connecté et, lorsque cette fonction est prise en charge, affiche works ou audit ok dans channels status --probe
  • L’expéditeur est approuvé (ou la politique des messages privés est ouverte ou utilise une liste d’autorisation)
Signatures dans les journaux :
  • drop guild message (mention required → le filtrage des mentions de Discord a bloqué le message.
  • pairing request → l’expéditeur n’est pas approuvé et attend l’approbation de l’association par message privé.
  • blocked / allowlist dans les journaux du canal → l’expéditeur, le salon ou le groupe a été filtré.
Pages détaillées : Aucune réponse, Dépannage des canaux, Association
Sortie correcte :
  • Dashboard: http://... apparaît dans openclaw gateway status
  • Connectivity probe: ok
  • Capability: read-only, write-capable ou admin-capable
  • Aucune boucle d’authentification dans les journaux
Signatures dans les journaux :
  • device identity required → un contexte HTTP ou non sécurisé ne peut pas terminer l’authentification de l’appareil.
  • origin not allowed → l’Origin du navigateur n’est pas autorisée pour la cible Gateway de l’interface de contrôle.
  • AUTH_TOKEN_MISMATCH avec canRetryWithDeviceToken=true → une nouvelle tentative avec le jeton d’un appareil fiable peut avoir lieu automatiquement en réutilisant les portées mises en cache du jeton associé.
  • Des erreurs unauthorized répétées après cette nouvelle tentative → jeton ou mot de passe incorrect, incohérence du mode d’authentification ou jeton obsolète de l’appareil associé.
  • too many failed authentication attempts (retry later) → les échecs répétés provenant de cette Origin du navigateur sont temporairement bloqués ; les autres origines localhost utilisent des compartiments distincts. Consultez Connectivité du tableau de bord et de l’interface de contrôle pour la particularité des nouvelles tentatives simultanées avec Tailscale Serve.
  • gateway connect failed: → l’interface cible une URL ou un port incorrect, ou le Gateway est inaccessible.
Pages détaillées : Connectivité du tableau de bord et de l’interface de contrôle, Interface de contrôle, Authentification
Sortie correcte :
  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable ou admin-capable
Signatures dans les journaux :
  • Gateway start blocked: set gateway.mode=local ou existing config is missing gateway.mode → le mode du Gateway est distant, ou la configuration ne contient pas l’indicateur du mode local et doit être réparée.
  • refusing to bind gateway ... without auth → liaison à une adresse autre que local loopback sans méthode d’authentification valide (jeton ou mot de passe, ou proxy de confiance lorsqu’il est configuré).
  • another gateway instance is already listening ou EADDRINUSE → le port est déjà utilisé.
Pages détaillées : Le service Gateway ne fonctionne pas, Processus en arrière-plan, Configuration
Sortie correcte :
  • Le transport du canal est connecté.
  • Les vérifications d’association et de liste d’autorisation réussissent.
  • Les mentions sont détectées lorsqu’elles sont requises.
Signatures dans les journaux :
  • mention required → le filtrage des mentions de groupe a bloqué le traitement.
  • pairing / pending → l’expéditeur du message privé n’est pas encore approuvé.
  • not_in_channel, missing_scope, Forbidden, 401/403 → problème de jeton d’autorisation du canal.
Pages détaillées : Canal connecté, mais les messages ne circulent pas, Dépannage des canaux
Sortie correcte :
  • cron status indique que le planificateur est activé et affiche son prochain réveil.
  • cron runs affiche des entrées ok récentes.
  • Le Heartbeat est activé et se trouve dans la plage des heures actives.
Signatures dans les journaux :
  • cron: scheduler disabled; jobs will not run automatically → Cron est désactivé.
  • heartbeat skipped avec la raison quiet-hours → en dehors des heures d’activité configurées.
  • heartbeat skipped avec la raison empty-heartbeat-file → HEARTBEAT.md existe, mais ne contient que des éléments de structure vides : lignes blanches, commentaires, en-têtes, délimiteurs de blocs de code ou listes de contrôle vides.
  • heartbeat skipped avec la raison no-tasks-due → le mode tâche est actif, mais l’intervalle d’aucune tâche n’est encore arrivé à échéance.
  • heartbeat skipped avec la raison alerts-disabled → showOk, showAlerts et useIndicator sont tous désactivés.
  • requests-in-flight → voie principale occupée ; réveil du Heartbeat différé.
  • unknown accountId → le compte cible de la livraison du Heartbeat n’existe pas.
Pages détaillées : Livraison des tâches Cron et du Heartbeat, Tâches planifiées : dépannage, Heartbeat
Sortie attendue :
  • Le Node est indiqué comme connecté et appairé pour le rôle node.
  • La fonctionnalité requise par la commande invoquée existe.
  • L’autorisation de l’outil est accordée.
Signatures de journal :
  • NODE_BACKGROUND_UNAVAILABLE → ramenez l’application du Node au premier plan.
  • *_PERMISSION_REQUIRED → autorisation du système d’exploitation refusée ou manquante.
  • SYSTEM_RUN_DENIED: approval required → l’approbation de l’exécution est en attente.
  • SYSTEM_RUN_DENIED: allowlist miss → la commande ne figure pas dans la liste d’autorisation d’exécution.
Pages détaillées : Node appairé, échec de l’outil, Dépannage des Nodes, Approbations d’exécution
Ce qui a changé :
  • Si tools.exec.host n’est pas défini, sa valeur par défaut est auto, qui se résout en sandbox lorsqu’un environnement d’exécution isolé est actif, et en gateway dans le cas contraire.
  • host=auto détermine uniquement le routage ; l’absence de demande de confirmation provient de security=full associé à ask=off sur le Gateway ou le Node.
  • Si tools.exec.security n’est pas défini, sa valeur par défaut est full sur gateway/node.
  • Si tools.exec.ask n’est pas défini, sa valeur par défaut est off.
  • Si des approbations vous sont demandées, une politique locale à l’hôte ou propre à la session a renforcé les restrictions d’exécution par rapport à ces valeurs par défaut.
Rétablissez les valeurs par défaut actuelles sans approbation :
Solutions plus sûres :
  • Définissez uniquement tools.exec.host=gateway pour assurer un routage stable vers l’hôte.
  • Utilisez security=allowlist avec ask=on-miss pour exécuter sur l’hôte avec vérification lorsque la commande ne figure pas dans la liste d’autorisation.
  • Activez le mode isolé afin que host=auto se résolve de nouveau en sandbox.
Signatures de journal :
  • Approval required. → la commande attend une instruction /approve ....
  • SYSTEM_RUN_DENIED: approval required → l’approbation de l’exécution sur l’hôte Node est en attente.
  • exec host=sandbox requires a sandbox runtime for this session → sélection implicite ou explicite de l’environnement isolé alors que le mode isolé est désactivé.
Pages détaillées : Exécution, Approbations d’exécution, Sécurité : éléments vérifiés par l’audit
Sortie attendue :
  • L’état du navigateur affiche running: true ainsi qu’un navigateur et un profil sélectionnés.
  • Le profil openclaw démarre, ou le profil user détecte les onglets Chrome locaux.
Signatures de journal :
  • unknown command "browser" → plugins.allow est défini et exclut browser.
  • Failed to start Chrome CDP on port → échec du lancement du navigateur local.
  • browser.executablePath not found → le chemin configuré vers le fichier exécutable est incorrect.
  • browser.cdpUrl must be http(s) or ws(s) → l’URL CDP configurée utilise un schéma non pris en charge.
  • browser.cdpUrl has invalid port → le port de l’URL CDP configurée est incorrect ou hors plage.
  • No Chrome tabs found for profile="user" → le profil de connexion Chrome MCP ne dispose d’aucun onglet Chrome local ouvert.
  • Remote CDP for profile "<name>" is not reachable → le point de terminaison CDP distant configuré n’est pas accessible depuis cet hôte.
  • Browser attachOnly is enabled ... not reachable → le profil en connexion seule ne dispose d’aucune cible CDP active.
  • Remplacements obsolètes de la fenêtre d’affichage, du mode sombre, des paramètres régionaux ou du mode hors ligne sur les profils en connexion seule ou CDP distants → exécutez openclaw browser stop --browser-profile <name> pour fermer la session de contrôle et libérer l’état d’émulation sans redémarrer le Gateway.
Pages détaillées : Échec de l’outil de navigation, Commande ou outil de navigation manquant, Navigateur : dépannage sous Linux, Navigateur : dépannage du CDP distant sous WSL2/Windows

​
Pages connexes