Problèmes courants et dépannage de Pi Agent
Voici les problèmes courants et les solutions rencontrés lors de l'utilisation de Pi Agent.
Problèmes d'installation
Cette section couvre les erreurs typiques et les pistes de résolution lors de l'installation.
npm install échoue
Symptôme : la commande d'installation se termine avec une erreur à mi-chemin. Les erreurs courantes se répartissent en trois catégories : version, réseau et permissions.
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| La version de Node.js est trop basse. Pi Agent nécessite Node.js 22.19.0 ou une version supérieure. | Exécuteznode --versionpour vérifier la version actuelle | Utilisez nvm pour installer et passer à 22 LTS ou une version supérieure |
| Problème de réseau : l'accès au registre npm officiel depuis la Chine expire souvent. | Vérifiez si l'erreur contient des messages de délai d'attente réseau tels que ETIMEDOUT. | Exécuteznpm config set registry https://registry.npmmirror.comPassez à un registre miroir et réinstallez. |
| Problème d'autorisation : le répertoire d'installation global sur macOS/Linux n'est pas accessible en écriture par l'utilisateur actuel. | Vérifiez si l'erreur contient des erreurs d'autorisation EACCES. | Utilisez nvm pour gérer Node.js, ou configurez le préfixe npm vers un répertoire utilisateur. Évitez d'utiliser sudo. |
Commande pi introuvable après l'installation
Symptôme : l'installation indique une réussite, mais la saisie de pi donne « command not found ».
Vérifiez d'abord le préfixe d'installation global de npm :
$ npm prefix -g /usr/local
Vérifiez ensuite si le répertoire bin sous ce préfixe est dans PATH :
$ echo $PATH | grep "$(npm prefix -g)/bin" /usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin
Lorsque le répertoire n'est pas dans PATH, cette commande ne produit aucune sortie :
$ echo $PATH | grep "$(npm prefix -g)/bin"
Aucune sortie signifie que le répertoire bin global n'est pas dans PATH, c'est pourquoi la commande pi est introuvable.
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| Le répertoire bin global n'est pas ajouté à PATH. | Utilisez la commande grep ci-dessus pour confirmer s'il y a une sortie. | conservez$(npm prefix -g)/binAjoutez à~/.zshrcou~/.bashrcdans le PATH, puis redémarrez le terminal pour que cela prenne effet. |
| Changement de version de Node, l'ancien lien symbolique n'est plus valide. | Exécutezls $(npm prefix -g)/binpour vérifier si pi existe toujours | Relancez l'installation globale sous la version actuelle de Node. |
Problèmes d'authentification
Cette section couvre les solutions pour les échecs de connexion à /login et d'authentification par clé API.
Échec de connexion à /login
Symptôme : après avoir saisi /login, le navigateur ne peut pas terminer la redirection, ou l'interface reste dans un état d'attente d'autorisation.
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| L'abonnement n'est pas dans un état valide. | Connectez-vous au site officiel du fournisseur pour confirmer si l'abonnement a expiré. | Renouvelez l'abonnement, ou passez à un autre fournisseur pour vous connecter. |
| Impossible d'accéder au serveur d'authentification du fournisseur. | Ouvrez le site du fournisseur dans un navigateur pour confirmer l'accessibilité réseau. | Configurez un proxy et réessayez. Voir la section Paramètres du proxy ci-dessous. |
| Utilisation de /login sur une connexion SSH distante | La machine distante n'a pas de navigateur, donc le callback OAuth ne peut pas être transmis. | Copiez l'URL d'autorisation dans un navigateur local, puis collez manuellement l'URL de callback pour terminer la connexion. |
La clé API ne fonctionne pas
Symptôme : Les variables d'environnement ont été exportées, mais l'application demande encore « non authentifié » au démarrage, ou continue d'utiliser les anciens identifiants.
Vérifiez dans l'ordre suivant :
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| Les variables d'environnement ne sont pas définies correctement. | Exécutezecho $ANTHROPIC_API_KEYpour afficher la sortie | Si la sortie est vide, ajoutez export au fichier de configuration du shell, puis rechargez-le. |
| auth.jsonDes identifiants en double existent déjà dans [file], avec une priorité plus élevée que les variables d'environnement. | Vérifiez~/.pi/agent/auth.jsonsi une entrée pour ce fournisseur existe déjà dans [file]. | Exécutez/logoutSupprimez les anciens identifiants, ou modifiez auth.json directement pour mettre à jour la clé. |
| Le format de la clé API est incorrect. | Vérifiez si le contenu copié contient des espaces ou des guillemets supplémentaires. | Copiez à nouveau la clé entièrement et reconfigurez. |
auth.jsonLes identifiants enregistrés dans [file] ont une priorité plus élevée que les variables d'environnement.
Lorsque la clé API ne fonctionne pas, vérifiez d'abord~/.pi/agent/auth.json, ne vous concentrez pas uniquement sur les variables d'environnement.
Modèle indisponible
Symptôme : Le modèle attendu est introuvable dans la liste des modèles, ou une erreur d'autorisation s'affiche lors de son appel.
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| Le répertoire des modèles locaux est obsolète. | Exécutezpi update --modelspour actualiser le répertoire des modèles | Après actualisation, rouvrez le sélecteur de modèle. |
| Vous ne savez pas quels modèles sont actuellement disponibles. | Exécutezpi --list-modelspour afficher la liste des modèles disponibles | Sélectionnez dans la liste un modèle disponible pour le compte actuel. |
| La clé API n’a pas accès au modèle correspondant. | Dans la console du fournisseur, vérifiez la portée d’autorisation du modèle pour cette clé. | Mettez à niveau le forfait, ou passez à un modèle autorisé. |
| Le modèle GitHub Copilot affiche « non pris en charge ». | Vérifiez si le modèle a été activé dans VS Code. | Activez d’abord le modèle dans VS Code Copilot Chat, puis revenez à Pi Agent pour l’utiliser. |
Problèmes d’interface
Cette section couvre trois types d’anomalies d’interface : le rendu du terminal, l’affichage des images et les raccourcis clavier.
Affichage anormal de l'interface (couleurs incorrectes, désalignement)
Symptôme : les couleurs semblent ternes ou déformées, et les bordures des tableaux et des zones de texte sont mal alignées.
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| Le terminal ne prend pas en charge la True Color. | Exécutezecho $COLORTERMSi la sortie est truecolor ou 24bit, cela signifie que c'est pris en charge. | Passez à un terminal qui prend en charge la True Color (iTerm2, Windows Terminal, etc.). |
| VS Code a automatiquement ajusté le contraste du terminal. | Vérifiez le paramètreterminal.integrated.minimumContrastRatio | Définissez ce paramètre sur 1. |
| Le terminal actuel a une mauvaise compatibilité de rendu. | Exécutez dans un autre terminal pour confirmer si le problème se reproduit. | Changez de terminal ; iTerm2 ou Windows Terminal est recommandé. |
Les images ne peuvent pas être affichées
Symptôme : après avoir envoyé ou collé une image, seul un espace réservé ou un espace vide est visible dans le terminal.
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| Le terminal ne prend pas en charge les protocoles d’affichage d’images. | Vérifiez si le terminal prend en charge imgcat d’iTerm2 ou icat de Kitty. | Passez à un terminal qui prend en charge les protocoles d’images. |
| L’affichage des images est désactivé par la configuration. | Vérifiezterminal.showImagess’il est défini sur true. | Passez-le à true et exécutez/reloadpour appliquer la configuration. |
Les raccourcis clavier ne fonctionnent pas
Symptôme : appuyer sur les raccourcis clavier décrits dans la documentation n’a aucun effet ou déclenche les fonctions propres du terminal.
| Causes possibles | Étapes de dépannage | Solutions |
|---|---|---|
| Le terminal intercepte le raccourci clavier. | Vérifiez la liste des raccourcis clavier dans les paramètres du terminal. | Modifiez ou libérez les associations en conflit dans le terminal. |
| Mauvaise mémorisation des raccourcis clavier actuels. | Exécutez/hotkeyspour afficher toutes les associations de raccourcis clavier actuelles. | Utilisez les raccourcis réels indiqués dans la liste. |
| À ajuster selon vos habitudes personnelles. | Vérifiez si le fichier de configuration~/.pi/agent/keybindings.jsonexiste. | Modifiez ce fichier pour personnaliser les raccourcis clavier |
Problèmes de session
Cette section couvre deux types de problèmes : la taille excessive du fichier de session et l'impossibilité de trouver des sessions historiques.
Fichier de session trop volumineux
Symptôme : l'utilisation du contexte ne cesse d'augmenter, les réponses ralentissent, ou la compression est déclenchée prématurément.
| Causes possibles | Méthodes de dépannage | Solutions |
|---|---|---|
| Historique de conversation trop long | Exécuter/sessionVérifier le nombre de messages et l'utilisation des tokens | Exécuter/compactCompresser l'historique de conversation |
| Compression automatique non activée | Vérifiercompaction.enableds'il est défini sur true | Après l'avoir défini sur true, redémarrer pi pour que cela prenne effet |
| Une seule session s'est accumulée pendant trop longtemps | utiliser/sessionObserver la croissance de la taille du fichier de session | Utiliser régulièrement/newDémarrer une nouvelle session, répartir les sessions par tâche |
Impossible de trouver la session précédente
Symptôme : les enregistrements de travail précédents ne sont pas visibles dans la liste pi -r.
| Causes possibles | Méthodes de dépannage | Solutions |
|---|---|---|
| N'a pas utilisé le point d'entrée de reprise | Exécuterpi -rOu saisir /resume en mode interactif pour parcourir la liste des sessions | Sélectionnez la session cible dans la liste pour reprendre |
| sessionDirLes paramètres ont été modifiés | Vérifiez dans settings.jsonsessionDirla valeur actuelle de | Revenez au répertoire d'origine, ou migrez les fichiers du répertoire d'origine vers le nouveau répertoire |
| Anomalie d'autorisation du répertoire de session | Exécutezls ~/.pi/agent/sessions/Confirmez qu'il est lisible et inscriptible | Exécutezchmod -R u+rw ~/.pi/agent/sessionsCorrigez les permissions |
Problèmes de performance
Cette section couvre deux types de problèmes de performance : des réponses lentes et une dégradation des performances sous un contexte long.
Les réponses de l'IA sont lentes
Symptôme : après avoir soumis une requête, aucun premier mot n'est produit pendant longtemps, ou le temps total est nettement plus élevé que d'habitude.
| Causes possibles | Méthodes de dépannage | Solutions |
|---|---|---|
| Latence réseau élevée ou lien rompu | Exécutezping api.anthropic.comVérifiez la latence et la perte de paquets | Changez de réseau, ou configurez un proxy comme décrit dans les paramètres de proxy ci-dessous |
| Niveau de raisonnement trop élevé, temps de réflexion prolongé | Vérifiez le niveau de raisonnement actuel dans la barre d’état | Appuyez sur Shift+Tab pour réduire le niveau de raisonnement |
| Le prompt système ou le contenu du fichier de contexte est trop volumineux | Vérifiez la taille des fichiers de contexte tels que AGENTS.md | Raccourcissez le prompt système, rationalisez le contenu d'AGENTS.md |
| La consommation de tokens par requête est trop élevée | Exécutez/sessionAffichez la répartition de l’utilisation des tokens et de la consommation de temps | Exécutez/compactou/newRaccourcissez le contexte et réessayez |
Si vous utilisez un environnement proxy, passez àcurl -x $HTTP_PROXY https://api.anthropic.compour tester.
Dans un environnement proxy, un échec de ping ne signifie pas que l'API est indisponible.
ping utilise ICMP, tandis que l'API utilise HTTPS ; dans ce cas, utilisez curl pour vérifier le lien réel.
Les performances de l'IA se dégradent après un contexte volumineux
Symptôme : après un plus grand nombre de tours de conversation, l'IA commence à oublier les accords précédents ou donne des réponses répétitives.
| Causes possibles | Méthodes de dépannage | Solutions |
|---|---|---|
| Le contexte est proche de la limite de la fenêtre, et le contenu initial finit par être compressé | Exécutez/sessionVérifiez l'utilisation actuelle des tokens | Exécutez manuellement/compactCompressez le contexte |
| Un grand nombre de tentatives invalides sont mélangées aux messages historiques | utilisez/treeVérifiez les branches et les conversations invalides | utilisez/newDémarrez une nouvelle session, écrivez les conclusions dans AGENTS.md |
| Le contenu du fichier référencé n'a aucun rapport avec la tâche actuelle | Vérifiez si les références @ et les fichiers de contexte contiennent du contenu non pertinent | Réduire le contenu superflu du fichier de contexte, ne conserver que ce dont la tâche actuelle a besoin |
Paramètres du proxy
Cette section explique comment permettre à Pi Agent d'accéder normalement à l'API dans un environnement réseau restreint.
Accéder à l'API depuis la Chine
Configurer un proxy HTTP dans settings.json :
{
"httpProxy": "http://127.0.0.1:7890"
}
Ou démarrer après avoir défini les variables d'environnement :
$ export HTTP_PROXY=http://127.0.0.1:7890 $ export HTTPS_PROXY=http://127.0.0.1:7890 $ piAutres extensions