OpenClaw Dépannage : Solutions à 10 Problèmes Courants

J’ai vu OpenClaw faire des choses étranges. Se planter sans messages d’erreur. Répondre dans la mauvaise langue sans raison. Refuser de reconnaître qu’un canal Slack parfaitement configuré existe. Une fois, il a commencé à répondre à chaque message avec un haïku. Je n’ai pas demandé le mode haïku. Il n’y a pas de mode haïku.

Après huit mois et environ 400 moments de « qu’est-ce qui se passe ? », j’ai compilé les 10 problèmes que j’ai vus le plus souvent — d’après ma propre expérience et en aidant des gens sur le Discord de la communauté. Ce ne sont pas des problèmes théoriques issus de cas limites dans la documentation. Ce sont les choses qui se cassent réellement sur des installations réelles.

1. Syndrome « Ça Fonctionnait Hier »

Le problème le plus courant avec OpenClaw n’est pas un bug — c’est une clé API qui a expiré, un modèle qui a été déprécié, ou un point de terminaison de service qui a changé. Vous n’avez rien changé, mais quelque chose en amont l’a fait.

Diagnostic : Vérifiez d’abord la page de statut de votre fournisseur de modèle. Ensuite, vérifiez la validité de votre clé API. Ensuite, vérifiez si le nom du modèle dans votre configuration existe toujours. Neuf fois sur dix, le problème est externe.

Solution : Mettez à jour la clé, le nom du modèle ou le point de terminaison. Et fixez un rappel sur votre calendrier pour vérifier ces éléments tous les mois, car les fournisseurs changent des choses sans vous envoyer de mail.

2. La Fuite de Mémoire Qui Ravit Votre Serveur

Après quelques jours d’exécution, OpenClaw devient lent, puis plus lent, puis se plante. L’utilisation de la mémoire grimpe régulièrement jusqu’à ce que le système d’exploitation tue le processus.

Diagnostic : C’est presque toujours un contexte de conversation qui grandit sans limites. Chaque message s’ajoute au contexte, et si les anciens messages ne sont pas élagués, le contexte finit par consommer toute la mémoire disponible.

Solution : Configurez la compression de contexte. Définissez une taille de contexte maximale. Activez l’élagage automatique des anciens messages. Redémarrez le service après avoir appliqué la solution, et surveillez l’utilisation de la mémoire pendant 24 heures pour confirmer qu’elle se stabilise.

3. Le Bot Slack/Discord Ne Répond Pas

Vous avez tout configuré, le bot apparaît « en ligne » dans Slack/Discord, mais il ne répond à aucun message.

Diagnostic : C’est généralement un problème d’autorisation. Le bot a besoin d’autorisations spécifiques (lire les messages, écrire des messages, lire les canaux) et doit être invité dans chaque canal explicitement. Une autre cause courante : l’URL du webhook n’est pas accessible depuis l’extérieur.

Solution : Vérifiez les autorisations du bot dans la console développeur de la plateforme. Vérifiez que le bot est membre du canal où vous testez. Testez l’URL du webhook depuis une source externe (utilisez un service comme httpbin ou requestbin pour vérifier que votre point de terminaison est accessible).

4. Les Tâches Cron Fonctionnent Mais Produisent Une Sortie Vide

Votre tâche planifiée s’exécute à l’heure (vous pouvez le voir dans les journaux) mais la sortie est vide ou incohérente.

Diagnostic : Le prompt est probablement trop vague ou fait référence à des données auxquelles l’agent n’a pas accès. « Résumez les métriques d’aujourd’hui » échoue si l’agent n’a pas accès à la base de données des métriques. Le travail s’exécute, l’IA n’a rien avec quoi travailler, et elle produit des choses inutilisables.

Solution : Testez le prompt exact comme tâche manuelle d’abord. Assurez-vous que toutes les sources de données sont accessibles. Incluez des instructions explicites sur où trouver les données.

5. Les Réponses Sont Douloureusement Lentes

Chaque réponse prend 15 à 30 secondes au lieu des 2 à 3 secondes attendues.

Diagnostic : Trois causes courantes. Premièrement : votre contexte de conversation est trop grand (le modèle doit traiter des milliers de tokens d’historique avant de générer une réponse). Deuxièmement : l’API du modèle est lente (vérifiez le statut du fournisseur). Troisièmement : latence réseau entre votre serveur et le point de terminaison API.

Solution : Pour la taille du contexte : activez la compression, limitez la longueur de l’historique. Pour la lenteur de l’API : attendez, changez de fournisseur temporairement, ou utilisez une réponse mise en cache lorsque c’est possible. Pour le réseau : envisagez d’héberger plus près de la région du fournisseur de l’API.

6. Erreurs « Taux Limité »

Des rafales soudaines d’erreurs 429, ou le bot devenant silencieux pendant les périodes de forte utilisation.

Diagnostic : Vous dépassez la limite de taux de votre fournisseur d’API. Cela se produit lorsque plusieurs utilisateurs interagissent simultanément, ou lorsqu’un flux de travail déclenche de nombreux appels API en succession rapide.

Solution : Implémentez une mise en file d’attente des requêtes avec un planificateur conscient des limites de taux. Mettez à niveau votre niveau d’API si le niveau gratuit est trop restrictif. Pour les scénarios de rafale, ajoutez un délai exponentiel (attendez et réessayez avec des délais croissants).

7. L’Agent Dit Des Choses Qu’il Ne Devrait Pas

L’agent révèle des détails sur le prompt système, répond de manière inappropriée, ou s’écarte du sujet de manières qui semblent relever de l’injection de prompt.

Diagnostic : Si l’agent est exposé à une entrée non fiable (canaux publics, messages d’utilisateur), une injection de prompt est probable. Quelqu’un a créé une entrée qui remplace vos instructions système.

Solution : Ajoutez un filtrage de sortie pour les motifs sensibles (clés API, fragments de prompt système). Mettez en œuvre une validation d’entrée pour les motifs d’injection connus. Pour des configurations à haute sécurité, traitez les entrées non fiables dans un contexte séparé des instructions système.

8. Échecs de Connexion à la Base de Données

L’agent ne peut pas se connecter à votre base de données, ou les connexions chutent par intermittence.

Diagnostic : Épuisement du pool de connexions (trop de connexions ouvertes), problèmes d’authentification (mot de passe changé, certificat SSL expiré), ou problèmes réseau (pare-feu bloquant, échec de résolution DNS).

Solution : Vérifiez les paramètres du pool de connexions et augmentez-les si nécessaire. Vérifiez les identifiants. Testez la connexion indépendamment (utilisez un client de base de données pour confirmer que vous pouvez vous connecter avec les mêmes identifiants depuis le même serveur).

9. Permissions du Système de Fichiers

L’agent ne peut pas lire ou écrire des fichiers, même si les chemins semblent corrects.

Diagnostic : Le processus OpenClaw s’exécute sous un compte utilisateur spécifique. Ce compte utilisateur a besoin de permissions de lecture/écriture sur les répertoires que l’agent essaie d’accéder.

Solution : Vérifiez sous quel utilisateur OpenClaw s’exécute. Vérifiez que cet utilisateur a les permissions appropriées sur les répertoires cibles. Sur Linux : ls -la pour vérifier, chown ou chmod pour corriger. N’utilisez pas de permissions 777 — donnez le minimum d’accès nécessaire.

10. Les Mises à Jour Cassent Tout

Vous mettez à jour OpenClaw, et votre configuration soigneusement réglée cesse de fonctionner.

Diagnostic : Les changements de format de configuration entre les versions, les fonctionnalités dépréciées supprimées, ou les conflits de dépendances. C’est le problème le plus frustrant car vous n’avez pas changé votre code — vous vouliez juste les dernières fonctionnalités.

Solution : Lisez le changelog avant de mettre à jour. Sauvegardez votre configuration avant de mettre à jour. Testez la mise à jour sur une instance de développement d’abord. Si quelque chose casse, votre sauvegarde vous permet de revenir en arrière immédiatement. Ne mettez jamais à jour la production sans une sauvegarde vérifiée et un plan de retour en arrière.

L’Approche Universelle du Débogage

Quand quelque chose casse et que vous ne savez pas pourquoi :

1. Vérifiez les journaux (90 % des réponses se trouvent dans les journaux)
2. Vérifiez les services externes (statut de l’API, connexion à la base de données, réseau)
3. Vérifiez ce qui a changé (avez-vous mis à jour quelque chose ? Le fournisseur a-t-il changé quelque chose ?)
4. Reproduisez le problème (pouvez-vous le déclencher de manière constante ?)
5. Recherchez sur le Discord de la communauté (quelqu’un d’autre a probablement déjà rencontré ce problème)

Et quand tout échoue : redémarrez le service et voyez si le problème disparaît. Cela ne devrait pas être la première étape, mais c’est un dernier recours valable. Parfois, les ordinateurs ne font que faire leur propre chose.

🕒 Published: March 26, 2026