English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Start here

Dépannage général

Si vous n’avez que 2 minutes, utilisez cette page comme porte d’entrée de triage.

60 premières secondes

Exécutez exactement cette échelle dans l’ordre :

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

Sortie correcte en une ligne :

  • openclaw status → affiche les canaux configurés et aucune erreur d’authentification évidente.
  • openclaw status --all → le rapport complet est présent et partageable.
  • openclaw gateway probe → la cible Gateway attendue est joignable (Reachable: yes). Capability: ... indique le niveau d’authentification que la sonde a pu prouver, et Read probe: limited - missing scope: operator.read correspond à des diagnostics dégradés, pas à un échec de connexion.
  • openclaw gateway status → Runtime: running, Connectivity probe: ok, et une ligne Capability: ... plausible. Utilisez --require-rpc si vous avez aussi besoin d’une preuve RPC avec portée de lecture.
  • openclaw doctor → aucune erreur bloquante de configuration ou de service.
  • openclaw channels status --probe → un Gateway joignable renvoie l’état de transport en direct par compte, ainsi que des résultats de sonde/audit comme works ou audit ok ; si le Gateway est injoignable, la commande se replie sur des résumés de configuration uniquement.
  • openclaw logs --follow → activité stable, aucune erreur fatale répétée.

L’assistant semble limité ou des outils manquent

Si l’assistant ne peut pas inspecter les fichiers, exécuter des commandes, utiliser l’automatisation du navigateur ou voir les outils attendus, vérifiez d’abord le profil d’outils effectif :

bash
openclaw statusopenclaw status --allopenclaw doctor

Causes courantes :

  • tools.profile: "messaging" est volontairement étroit pour les agents limités au chat.
  • tools.profile: "coding" est le profil habituel pour les workflows de dépôt, fichiers, shell et runtime.
  • tools.profile: "full" expose l’ensemble d’outils le plus large et doit être limité aux agents de confiance contrôlés par l’opérateur.
  • Les remplacements par agent agents.list[].tools peuvent restreindre ou étendre le profil racine pour un agent.

Modifiez le profil d’outils racine ou par agent, puis redémarrez ou rechargez le Gateway et relancez openclaw status --all. Consultez Outils pour le modèle de profil et les remplacements d’autorisation/refus.

Contexte long Anthropic 429

Si vous voyez : HTTP 429: rate_limit_error: Extra usage is required for long context requests, allez à /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

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

Si votre backend /v1 local ou auto-hébergé répond aux petites sondes directes /v1/chat/completions, mais échoue avec openclaw infer model run ou lors de tours d’agent normaux :

  1. Si l’erreur indique que messages[].content attend une chaîne, définissez models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. Si le backend échoue encore uniquement lors des tours d’agent OpenClaw, définissez models.providers.<provider>.models[].compat.supportsTools: false et réessayez.
  3. Si de minuscules appels directs fonctionnent encore, mais que des prompts OpenClaw plus volumineux font planter le backend, traitez le problème restant comme une limitation du modèle/serveur amont et poursuivez dans le runbook approfondi : /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

Échec de l’installation d’un Plugin avec des extensions openclaw manquantes

Si l’installation échoue avec package.json missing openclaw.extensions, le paquet Plugin utilise une ancienne forme qu’OpenClaw n’accepte plus.

Correction dans le paquet Plugin :

  1. Ajoutez openclaw.extensions à package.json.
  2. Faites pointer les entrées vers les fichiers runtime construits (généralement ./dist/index.js).
  3. Republiez le Plugin et relancez openclaw plugins install <package>.

Exemple :

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 les installations ou mises à jour de Plugins

Si une mise à jour se termine mais que les Plugins sont obsolètes, désactivés, ou affichent des messages comme blocked by install policy, install policy failed closed, ou Disabled "<plugin>" after plugin update failure, vérifiez security.installPolicy.

La politique d’installation s’exécute lors des installations et mises à jour de Plugins. Les versions des Plugins appartenant à OpenClaw évoluent normalement avec la version OpenClaw, donc une mise à jour d’OpenClaw peut aussi nécessiter des mises à jour correspondantes des Plugins @openclaw/* pendant la synchronisation post-mise à jour.

Évitez ces formes de politique trop larges, sauf si vous maintenez aussi la règle de mise à niveau correspondante :

  • Geler les Plugins appartenant à OpenClaw sur une seule ancienne version exacte, par exemple en autorisant uniquement @openclaw/*@2026.5.3.
  • Bloquer seulement par type de source, par exemple chaque requête de Plugin npm, réseau ou request.mode: "update".
  • Traiter la commande de politique comme facultative. Lorsque security.installPolicy est activé, un exécutable de politique manquant, lent, illisible ou bloqué par les permissions échoue en fermeture sécurisée.
  • Approuver des versions de Plugins sans tenir compte de openclawVersion de la requête de politique ni des métadonnées du candidat Plugin.

Des règles de politique plus sûres autorisent les mises à jour de Plugins de confiance appartenant à OpenClaw lorsque le candidat est compatible avec l’hôte OpenClaw actuel, au lieu d’épingler une seule version pour toujours. Si vous bloquez npm par défaut, créez une exception étroite pour les paquets Plugin @openclaw/* de confiance ou les ids de Plugins que vous utilisez. Si vous différenciez les requêtes d’installation et de mise à jour, appliquez la même règle de confiance à request.mode: "update".

Récupération :

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

Si la politique est volontairement stricte, assouplissez-la pour la fenêtre de mise à niveau OpenClaw de confiance, relancez openclaw plugins update --all, puis restaurez la règle plus stricte. Si un Plugin a été désactivé après un échec de mise à jour, inspectez-le et ne le réactivez qu’après la réussite de la mise à jour :

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

Référence : Politique d’installation opérateur

Plugin présent mais bloqué par une propriété suspecte

Si openclaw doctor, la configuration initiale ou les avertissements au 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 autre utilisateur Unix que le processus qui les charge. Ne supprimez pas la configuration du Plugin. Corrigez la propriété des fichiers ou exécutez OpenClaw avec le même utilisateur que celui qui possède le répertoire d’état.

Les installations Docker s’exécutent normalement en tant que node (uid 1000). Pour la configuration Docker par défaut, réparez 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 root, réparez plutôt la racine de Plugin gérée pour qu’elle appartienne à root :

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

Documentation approfondie :

Arbre de décision

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]
Aucune réponse
bash
openclaw statusopenclaw gateway statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --follow

Une sortie correcte ressemble à :

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable, ou admin-capable
  • Votre canal affiche un transport connecté et, lorsque c’est pris en charge, works ou audit ok dans channels status --probe
  • L’expéditeur apparaît comme approuvé (ou la politique DM est ouverte/en liste d’autorisation)

Signatures de journal courantes :

  • drop guild message (mention required → le filtrage par mention a bloqué le message dans Discord.
  • pairing request → l’expéditeur n’est pas approuvé et attend l’approbation d’appairage en DM.
  • blocked / allowlist dans les journaux de canal → l’expéditeur, le salon ou le groupe est filtré.

Pages approfondies :

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

Une sortie correcte ressemble à :

  • Dashboard: http://... est affiché dans openclaw gateway status
  • Connectivity probe: ok
  • Capability: read-only, write-capable, ou admin-capable
  • Aucune boucle d’authentification dans les journaux

Signatures de journal courantes :

  • device identity required → le contexte HTTP/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 utilisateur de contrôle.
  • AUTH_TOKEN_MISMATCH avec des indications de nouvelle tentative (canRetryWithDeviceToken=true) → une nouvelle tentative avec jeton d’appareil de confiance peut se produire automatiquement.
  • Cette nouvelle tentative avec jeton mis en cache réutilise l’ensemble de portées mis en cache stocké avec le jeton d’appareil appairé. Les appelants avec deviceToken explicite / scopes explicites conservent plutôt leur ensemble de portées demandé.
  • Sur le chemin asynchrone de l’interface utilisateur de contrôle Tailscale Serve, les tentatives échouées pour le même {scope, ip} sont sérialisées avant que le limiteur n’enregistre l’échec, donc une deuxième mauvaise nouvelle tentative simultanée peut déjà afficher retry later.
  • too many failed authentication attempts (retry later) depuis une origine de navigateur localhost → des échecs répétés depuis cette même Origin sont temporairement verrouillés ; une autre origine localhost utilise un compartiment séparé.
  • unauthorized répété après cette nouvelle tentative → mauvais jeton/mot de passe, incohérence du mode d’authentification ou jeton d’appareil appairé obsolète.
  • gateway connect failed: → l’interface utilisateur cible la mauvaise URL/le mauvais port ou un Gateway injoignable.

Pages approfondies :

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

Une sortie correcte ressemble à :

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only, write-capable, ou admin-capable

Signatures de journal courantes :

  • Gateway start blocked: set gateway.mode=local ou existing config is missing gateway.mode → le mode Gateway est distant, ou le fichier de configuration ne contient pas l’empreinte du mode local et doit être réparé.
  • refusing to bind gateway ... without auth → liaison non local loopback sans chemin d’authentification Gateway valide (jeton/mot de passe, ou proxy de confiance lorsque configuré).
  • another gateway instance is already listening ou EADDRINUSE → le port est déjà utilisé.

Pages approfondies :

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

Une sortie correcte ressemble à ceci :

  • Le transport du canal est connecté.
  • Les vérifications d’appairage/de liste d’autorisation réussissent.
  • Les mentions sont détectées là où elles sont requises.

Signatures de journal courantes :

  • mention required → le filtrage par mention de groupe a bloqué le traitement.
  • pairing / pending → l’expéditeur du DM 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 :

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

Une sortie correcte ressemble à ceci :

  • cron.status indique qu’il est activé avec un prochain réveil.
  • cron runs affiche des entrées ok récentes.
  • Heartbeat est activé et n’est pas en dehors des heures actives.

Signatures de journal courantes :

  • cron: scheduler disabled; jobs will not run automatically → Cron est désactivé.
  • heartbeat skipped avec reason=quiet-hours → en dehors des heures actives configurées.
  • heartbeat skipped avec reason=empty-heartbeat-file → HEARTBEAT.md existe, mais ne contient que du blanc, un commentaire, un en-tête, une clôture, ou une structure de checklist vide.
  • heartbeat skipped avec reason=no-tasks-due → le mode tâche de HEARTBEAT.md est actif, mais aucun intervalle de tâche n’est encore arrivé à échéance.
  • heartbeat skipped avec reason=alerts-disabled → toute la visibilité de Heartbeat est désactivée (showOk, showAlerts et useIndicator sont tous désactivés).
  • requests-in-flight → voie principale occupée ; le réveil Heartbeat a été différé.
  • unknown accountId → le compte cible de livraison Heartbeat n’existe pas.

Pages détaillées :

Node est appairé, mais l’outil échoue pour camera canvas screen exec
bash
openclaw statusopenclaw gateway statusopenclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw logs --follow

Une sortie correcte ressemble à ceci :

  • Node est répertorié comme connecté et appairé pour le rôle node.
  • La capacité existe pour la commande que vous invoquez.
  • L’état de l’autorisation est accordé pour l’outil.

Signatures de journal courantes :

  • NODE_BACKGROUND_UNAVAILABLE → ramenez l’application node au premier plan.
  • *_PERMISSION_REQUIRED → l’autorisation du système d’exploitation a été refusée/manque.
  • SYSTEM_RUN_DENIED: approval required → l’approbation exec est en attente.
  • SYSTEM_RUN_DENIED: allowlist miss → la commande ne figure pas dans la liste d’autorisation exec.

Pages détaillées :

Exec 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, la valeur par défaut est auto.
  • host=auto se résout en sandbox lorsqu’un runtime sandbox est actif, sinon en gateway.
  • host=auto ne fait que le routage ; le comportement sans invite « YOLO » vient de security=full avec ask=off sur gateway/node.
  • Sur gateway et node, tools.exec.security non défini vaut full par défaut.
  • tools.exec.ask non défini vaut off par défaut.
  • Résultat : si vous voyez des approbations, une politique locale à l’hôte ou par session a rendu exec plus strict que les valeurs par défaut actuelles.

Restaurer le comportement actuel par défaut sans approbation :

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

Alternatives plus sûres :

  • Définissez uniquement tools.exec.host=gateway si vous voulez seulement un routage d’hôte stable.
  • Utilisez security=allowlist avec ask=on-miss si vous voulez l’exec sur l’hôte tout en conservant une revue en cas d’absence dans la liste d’autorisation.
  • Activez le mode sandbox si vous voulez que host=auto se résolve de nouveau en sandbox.

Signatures de journal courantes :

  • Approval required. → la commande attend /approve ....
  • SYSTEM_RUN_DENIED: approval required → l’approbation exec sur l’hôte node est en attente.
  • exec host=sandbox requires a sandbox runtime for this session → sélection sandbox implicite/explicite, mais le mode sandbox est désactivé.

Pages détaillées :

L’outil de navigateur échoue
bash
openclaw statusopenclaw gateway statusopenclaw browser statusopenclaw logs --followopenclaw doctor

Une sortie correcte ressemble à ceci :

  • L’état du navigateur indique running: true et un navigateur/profil choisi.
  • openclaw démarre, ou user peut voir les onglets Chrome locaux.

Signatures de journal courantes :

  • unknown command "browser" ou unknown command 'browser' → plugins.allow est défini et n’inclut pas browser.
  • Failed to start Chrome CDP on port → le lancement du navigateur local a échoué.
  • browser.executablePath not found → le chemin du binaire configuré 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 → l’URL CDP configurée contient un port invalide ou hors limites.
  • No Chrome tabs found for profile="user" → le profil d’attache Chrome MCP n’a aucun onglet Chrome local ouvert.
  • Remote CDP for profile "<name>" is not reachable → le point de terminaison CDP distant configuré n’est pas joignable depuis cet hôte.
  • Browser attachOnly is enabled ... not reachable ou Browser attachOnly is enabled and CDP websocket ... is not reachable → le profil en attache seule n’a aucune cible CDP active.
  • remplacements obsolètes de viewport / mode sombre / locale / hors ligne sur des profils en attache seule ou CDP distants → exécutez openclaw browser stop --browser-profile <name> pour fermer la session de contrôle active et libérer l’état d’émulation sans redémarrer le Gateway.

Pages détaillées :

Associé

Was this useful?
On this page

On this page