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.

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épannageSolutions
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 actuelleUtilisez 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épannageSolutions
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 toujoursRelancez 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épannageSolutions
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 distanteLa 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épannageSolutions
Les variables d'environnement ne sont pas définies correctement.Exécutezecho $ANTHROPIC_API_KEYpour afficher la sortieSi 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épannageSolutions
Le répertoire des modèles locaux est obsolète.Exécutezpi update --modelspour actualiser le répertoire des modèlesAprè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 disponiblesSé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épannageSolutions
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.minimumContrastRatioDé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épannageSolutions
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épannageSolutions
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 possiblesMéthodes de dépannageSolutions
Historique de conversation trop longExécuter/sessionVérifier le nombre de messages et l'utilisation des tokensExécuter/compactCompresser l'historique de conversation
Compression automatique non activéeVérifiercompaction.enableds'il est défini sur trueAprès l'avoir défini sur true, redémarrer pi pour que cela prenne effet
Une seule session s'est accumulée pendant trop longtempsutiliser/sessionObserver la croissance de la taille du fichier de sessionUtiliser 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 possiblesMéthodes de dépannageSolutions
N'a pas utilisé le point d'entrée de repriseExécuterpi -rOu saisir /resume en mode interactif pour parcourir la liste des sessionsSélectionnez la session cible dans la liste pour reprendre
sessionDirLes paramètres ont été modifiésVérifiez dans settings.jsonsessionDirla valeur actuelle deRevenez 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 sessionExécutezls ~/.pi/agent/sessions/Confirmez qu'il est lisible et inscriptibleExé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 possiblesMéthodes de dépannageSolutions
Latence réseau élevée ou lien rompuExécutezping api.anthropic.comVérifiez la latence et la perte de paquetsChangez 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’étatAppuyez sur Shift+Tab pour réduire le niveau de raisonnement
Le prompt système ou le contenu du fichier de contexte est trop volumineuxVérifiez la taille des fichiers de contexte tels que AGENTS.mdRaccourcissez le prompt système, rationalisez le contenu d'AGENTS.md
La consommation de tokens par requête est trop élevéeExécutez/sessionAffichez la répartition de l’utilisation des tokens et de la consommation de tempsExé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 possiblesMéthodes de dépannageSolutions
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 tokensExécutez manuellement/compactCompressez le contexte
Un grand nombre de tentatives invalides sont mélangées aux messages historiquesutilisez/treeVérifiez les branches et les conversations invalidesutilisez/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 actuelleVérifiez si les références @ et les fichiers de contexte contiennent du contenu non pertinentRé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
$ pi
Autres extensions