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 que c’est que ça ? », j’ai compilé les 10 problèmes que j’ai vus le plus souvent — de ma propre expérience et en aidant des personnes sur le Discord de la communauté. Ce ne sont pas des problèmes théoriques tirés de cas extrêmes de documentation. Ce sont des choses qui tombent réellement en panne sur des installations réelles.
1. Syndrome « Ça Fonctionnait Hier »
Le problème OpenClaw le plus courant 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 d’état 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 mettez en place un rappel dans votre calendrier pour vérifier ces éléments chaque mois, car les fournisseurs changent des choses sans vous envoyer de mail.
2. La Fuite de Mémoire Qui Ralentit Votre Serveur
Après quelques jours de fonctionnement, OpenClaw devient lent, puis plus lent, puis plante. L’utilisation de la mémoire grimpe régulièrement jusqu’à ce que le système d’exploitation tue le processus.
Diagnostic : 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 maximale pour le contexte. Activez l’élagage automatique des anciens messages. Redémarrez le service après la correction, 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 indique « en ligne » sur Slack/Discord, mais il ne répond à aucun message.
Diagnostic : Il s’agit généralement d’un problème de permissions. Le bot a besoin de permissions spécifiques (lire les messages, écrire des messages, lire les canaux) et doit être invité explicitement dans chaque canal. Une autre cause fréquente : l’URL du webhook n’est pas accessible de l’extérieur.
Solution : Vérifiez les permissions du bot dans la console de développeur de la plateforme. Vérifiez que le bot est membre du canal dans lequel vous testez. Testez l’URL du webhook à partir d’une source externe (utilisez un service comme httpbin ou requestbin pour confirmer que votre point de terminaison est accessible).
4. Les Tâches Cron Sont Exécutées Mais Produisent un Résultat Vide
Votre tâche planifiée s’exécute à l’heure (vous pouvez le voir dans les journaux) mais la sortie est vide ou incompréhensible.
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. La tâche s’exécute, l’IA n’a rien avec quoi travailler, et elle produit des résultats incohérents.
Solution : Testez le prompt exact comme une tâche manuelle unique 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 Terriblement 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 l’état 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 temporairement de fournisseur, ou utilisez une réponse mise en cache si 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é »
Soudains pics d’erreurs 429 ou le bot qui se tait pendant les périodes de forte utilisation.
Diagnostic : Vous dépassez la limite de taux de votre fournisseur 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 : Mettez en œuvre la mise en queue des demandes avec une planification consciente des limites de taux. Passez à un niveau d’API supérieur si le niveau gratuit est trop restrictif. Pour les scénarios de pointe, ajoutez un recouvrement exponentiel (attendre et réessayer avec des délais croissants).
7. L’Agent Dit des Choses Qu’il Ne Devrait Pas
L’agent révèle des détails du prompt système, répond de manière inappropriée, ou s’écarte du sujet d’une manière qui semble être une injection de prompt.
Diagnostic : Si l’agent est exposé à des entrées non fiables (canaux publics, messages d’utilisateurs), l’injection de prompt est probablement en cause. Quelqu’un a créé une entrée qui contourne 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 des entrées pour les motifs d’injection connus. Pour des configurations hautement sécurisées, 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 tombent de manière intermittente.
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, résolution DNS échouée).
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 de fichiers, même si les chemins semblent corrects.
Diagnostic : Le processus OpenClaw s’exécute sous un compte utilisateur spécifique. Ce compte utilisateur doit avoir des 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 réparer. N’utilisez pas les 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 : Changements de format de configuration entre les versions, suppression de fonctionnalités dépréciées, ou 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 des choses se cassent, votre sauvegarde vous permet de revenir immédiatement. Ne jamais mettre à jour la production sans une sauvegarde vérifiée et un plan de retour.
L’Approche Universelle de Débogage
Lorsque quelque chose se 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 (état 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 consistante ?)
5. Cherchez dans le Discord de la communauté (quelqu’un d’autre a probablement déjà rencontré ce problème)
Et lorsque 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 une ultime ressource valable. Parfois, les ordinateurs se comportent simplement comme des ordinateurs.
🕒 Published: