OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Start here

Dépannage général

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 :

bash
openclaw statusopenclaw status --allopenclaw gateway probeopenclaw gateway statusopenclaw doctoropenclaw channels status --probeopenclaw logs --follow

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 :

bash
openclaw statusopenclaw status --allopenclaw doctor

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>.
json
{  "name": "@openclaw/my-plugin",  "version": "1.2.3",  "openclaw": {    "extensions": ["./dist/index.js"]  }}

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 :

bash
openclaw doctor --deepopenclaw plugins update --allopenclaw status --all

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 :

bash
openclaw plugins inspect <plugin-id> --runtime --jsonopenclaw plugins enable <plugin-id>

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 :

text
blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)plugin present but blocked

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 :

bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspaceopenclaw doctor --fix

Si vous exécutez volontairement OpenClaw en tant que superutilisateur, corrigez plutôt la racine gérée des Plugins :

bash
sudo chown -R root:root /path/to/openclaw-config/npmopenclaw doctor --fix

Documentation détaillée : Propriétaire bloquant du chemin d’un Plugin, Docker : permissions et EACCES

Arbre de décision

flowchart TD
  A[OpenClaw ne fonctionne pas] --> B{Quel est le premier élément défaillant}
  B --> C[Aucune réponse]
  B --> D[Le tableau de bord ou l’interface de contrôle ne se connecte pas]
  B --> E[Le Gateway ne démarre pas ou le service ne fonctionne pas]
  B --> F[Le canal se connecte, mais les messages ne circulent pas]
  B --> G[Le Cron ou le Heartbeat ne s’est pas déclenché ou n’a rien transmis]
  B --> H[Le Node est associé, mais l’exécution de la caméra, du canevas ou de l’écran échoue]
  B --> I[L’outil de navigation échoue]

  C --> C1[/Section Aucune réponse/]
  D --> D1[/Section Interface de contrôle/]
  E --> E1[/Section Gateway/]
  F --> F1[/Section Flux du canal/]
  G --> G1[/Section Automatisation/]
  H --> H1[/Section Outils du Node/]
  I --> I1[/Section Navigateur/]
Aucune réponse
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

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

Le tableau de bord ou l’interface de contrôle ne se connecte pas
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

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

Le Gateway ne démarre pas ou le service est installé, mais ne fonctionne pas
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

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

Le canal se connecte, mais les messages ne circulent pas
bash
openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

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

Le Cron ou le Heartbeat ne s’est pas déclenché ou n’a rien transmis
bash
openclaw statusopenclaw gateway statusopenclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw logs --follow

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

Le Node est appairé, mais l’outil échoue pour la caméra, le canevas, l’écran ou l’exécution
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

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

L’exécution demande soudainement une approbation
bash
openclaw config get tools.exec.hostopenclaw config get tools.exec.securityopenclaw config get tools.exec.askopenclaw gateway restart

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 :

bash
openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

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

Échec de l’outil de navigation
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

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

Was this useful?
On this page

On this page