Pi Agent – Häufige Probleme und Fehlerbehebung
Die folgenden sind häufige Probleme und Lösungen, die bei der Verwendung von Pi Agent auftreten.
Installationsprobleme
Dieser Abschnitt behandelt typische Fehler und Lösungswege während der Installation.
npm install schlägt fehl
Symptom: Der Installationsbefehl bricht mittendrin mit einem Fehler ab. Häufige Fehler fallen in drei Kategorien: Version, Netzwerk und Berechtigungen.
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Node-Version zu niedrig. Pi Agent erfordert Node.js 22.19.0 oder höher. | Führenode --versionaus, um die aktuelle Version zu prüfen | Verwende nvm, um 22 LTS oder höher zu installieren und darauf umzuschalten |
| Netzwerk: Der Zugriff auf die offizielle npm-Registry aus China führt häufig zu Zeitüberschreitungen. | Prüfe, ob der Fehler Netzwerk-Timeout-Meldungen wie ETIMEDOUT enthält. | Führen Sienpm config set registry https://registry.npmmirror.com aus.Wechseln Sie zu einer Mirror-Registry und installieren Sie neu. |
| Berechtigungsproblem: Das globale Installationsverzeichnis unter macOS/Linux ist für den aktuellen Benutzer nicht beschreibbar. | Prüfen Sie, ob die Fehlermeldung EACCES-Berechtigungsfehler enthält. | Verwenden Sie nvm zur Verwaltung von Node.js oder konfigurieren Sie das npm-Präfix auf ein Benutzerverzeichnis. Vermeiden Sie die Verwendung von sudo. |
pi-Befehl nach der Installation nicht gefunden
Symptom: Die Installation meldet Erfolg, aber bei Eingabe von pi erscheint "command not found".
Prüfen Sie zuerst das globale Installationspräfix von npm:
$ npm prefix -g /usr/local
Bestätigen Sie dann, ob das bin-Verzeichnis unter diesem Präfix in PATH enthalten ist:
$ echo $PATH | grep "$(npm prefix -g)/bin" /usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin
Wenn das Verzeichnis nicht in PATH enthalten ist, liefert dieser Befehl keine Ausgabe:
$ echo $PATH | grep "$(npm prefix -g)/bin"
Keine Ausgabe bedeutet, dass das globale bin-Verzeichnis nicht in PATH enthalten ist, weshalb der pi-Befehl nicht gefunden werden kann.
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Das globale bin-Verzeichnis wurde nicht zu PATH hinzugefügt. | Verwenden Sie den obigen grep-Befehl, um zu prüfen, ob eine Ausgabe vorhanden ist. | halten$(npm prefix -g)/binAnhängen an~/.zshrcoder~/.bashrcin den PATH, dann das Terminal neu starten, damit es wirksam wird. |
| Node-Versionen gewechselt, alter Symlink ist nicht mehr gültig. | Führels $(npm prefix -g)/binaus, um zu prüfen, ob pi noch existiert | Führe die globale Installation erneut unter der aktuellen Node-Version aus. |
Authentifizierungsprobleme
Dieser Abschnitt behandelt Lösungswege für /login-Login- und API-Key-Authentifizierungsfehler.
/login-Login-Fehler
Symptom: Nach Eingabe von /login kann der Browser die Weiterleitung nicht abschließen, oder die Oberfläche bleibt in einem Zustand, in dem auf die Autorisierung gewartet wird.
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Das Abonnement ist nicht in einem gültigen Zustand. | Melde dich auf der offiziellen Website des Anbieters an, um zu bestätigen, ob das Abonnement abgelaufen ist. | Erneuere das Abonnement oder wechsle zu einem anderen Anbieter, um dich anzumelden. |
| Auf den Authentifizierungsserver des Anbieters kann nicht zugegriffen werden. | Öffnen Sie die Website des Anbieters in einem Browser, um die Netzwerkerreichbarkeit zu bestätigen. | Konfigurieren Sie einen Proxy und versuchen Sie es erneut. Siehe den Abschnitt Proxy-Einstellungen unten. |
| Verwendung von /login bei einer SSH-Remoteverbindung | Der Remote-Rechner hat keinen Browser, daher kann der OAuth-Callback nicht übermittelt werden. | Kopieren Sie die Autorisierungs-URL in einen lokalen Browser und fügen Sie dann die Callback-URL manuell ein, um die Anmeldung abzuschließen. |
API-Schlüssel funktioniert nicht
Symptom: Umgebungsvariablen wurden exportiert, aber die App zeigt beim Start weiterhin "not authenticated" an oder verwendet weiterhin alte Anmeldedaten.
Prüfen Sie in der folgenden Reihenfolge:
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Umgebungsvariablen sind nicht korrekt gesetzt. | Führen Sieecho $ANTHROPIC_API_KEYaus, um die Ausgabe anzuzeigen | Wenn die Ausgabe leer ist, fügen Sie export zur Shell-Konfigurationsdatei hinzu und führen Sie anschließend source erneut aus. |
| auth.jsonDoppelte Anmeldeinformationen existieren bereits in [file], mit höherer Priorität als Umgebungsvariablen. | Prüfe~/.pi/agent/auth.json, ob bereits ein Eintrag für diesen Anbieter in [file] existiert. | Führe/logoutaus. Lösche die alten Anmeldeinformationen oder bearbeite auth.json direkt, um den Key zu aktualisieren. |
| Das Format des API Key ist ungültig. | Prüfe, ob der kopierte Inhalt zusätzliche Leerzeichen oder Anführungszeichen enthält. | Kopiere den Key vollständig erneut und konfiguriere neu. |
auth.jsonIn [file] gespeicherte Anmeldeinformationen haben höhere Priorität als Umgebungsvariablen.
Wenn der API Key nicht funktioniert, prüfe zuerst~/.pi/agent/auth.json, konzentriere dich nicht nur auf Umgebungsvariablen.
Modell nicht verfügbar
Symptom: Das erwartete Modell kann nicht in der Modellliste gefunden werden, oder beim Aufruf wird ein Berechtigungsfehler angezeigt.
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Das lokale Modellverzeichnis ist veraltet. | Führepi update --modelsaus, um das Modellverzeichnis zu aktualisieren. | Öffnen Sie nach dem Aktualisieren die Modellauswahl erneut. |
| Unklar, welche Modelle derzeit verfügbar sind. | Führen Siepi --list-modelsaus, um die verfügbare Modellliste anzuzeigen. | Wählen Sie aus der Liste ein Modell aus, das für das aktuelle Konto verfügbar ist. |
| Der API-Schlüssel hat keinen Zugriff auf das entsprechende Modell. | Bestätigen Sie in der Anbieterkonsole den Berechtigungsumfang des Modells für diesen Schlüssel. | Upgraden Sie den Plan, oder wechseln Sie zu einem autorisierten Modell. |
| Das GitHub Copilot-Modell zeigt "nicht unterstützt" an. | Bestätigen Sie, ob das Modell in VS Code aktiviert wurde. | Aktivieren Sie das Modell zuerst in VS Code Copilot Chat und kehren Sie dann zu Pi Agent zurück, um es zu verwenden. |
Probleme mit der Oberfläche
Dieser Abschnitt behandelt drei Arten von Oberflächenanomalien: Terminal-Rendering, Bildanzeige und Tastenkürzel.
Anzeige der Oberfläche fehlerhaft (falsche Farben, verschoben)
Symptom: Farben erscheinen blass oder verzerrt, und die Ränder von Tabellen und Textboxen sind verschoben.
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Das Terminal unterstützt kein True Color. | Führen Sieecho $COLORTERMaus. Wenn die Ausgabe truecolor oder 24bit lautet, bedeutet das, dass es unterstützt wird. | Wechseln Sie zu einem Terminal, das True Color unterstützt (iTerm2, Windows Terminal usw.). |
| VS Code hat den Terminal-Kontrast automatisch angepasst. | Prüfen Sie den Einstellungspunktterminal.integrated.minimumContrastRatio | Setzen Sie diesen Punkt auf 1. |
| Das aktuelle Terminal hat eine schlechte Rendering-Kompatibilität. | Führen Sie es in einem anderen Terminal aus, um zu bestätigen, ob das Problem reproduziert wird. | Wechseln Sie das Terminal; iTerm2 oder Windows Terminal wird empfohlen. |
Bilder können nicht angezeigt werden
Symptom: Nach dem Senden oder Einfügen eines Bildes ist im Terminal nur ein Platzhalter oder leerer Bereich sichtbar.
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Das Terminal unterstützt keine Bildanzeigeprotokolle. | Prüfen Sie, ob das Terminal iTerm2s imgcat oder Kittys icat unterstützt. | Wechseln Sie zu einem Terminal, das Bildprotokolle unterstützt. |
| Die Bildanzeige ist durch die Konfiguration deaktiviert. | Prüfen Sieterminal.showImages, ob es true ist. | Ändern Sie es in true und führen Sie/reloadaus, um die Konfiguration anzuwenden. |
Tastenkürzel funktionieren nicht
Symptom: Das Drücken der in der Dokumentation beschriebenen Tastenkürzel hat keine Wirkung oder löst die eigenen Funktionen des Terminals aus.
| Mögliche Ursachen | Schritte zur Fehlerbehebung | Lösungen |
|---|---|---|
| Das Terminal fängt die Tastenkombination ab. | Prüfen Sie die Liste der Tastenkürzelzuordnungen in den Terminal-Einstellungen. | Ändern oder heben Sie konfliktierende Belegungen im Terminal auf. |
| Sich die aktuellen Tastenkürzel falsch gemerkt. | Führen Sie/hotkeysaus, um alle aktuellen Tastenkürzel-Bindungen anzuzeigen. | Arbeiten Sie gemäß den tatsächlichen Bindungen in der Liste. |
| Muss an persönliche Gewohnheiten angepasst werden. | Bestätigen Sie, ob die Konfigurationsdatei~/.pi/agent/keybindings.jsonexistiert. | Bearbeiten Sie diese Datei, um Tastaturkürzel anzupassen |
Sitzungsprobleme
Dieser Abschnitt behandelt zwei Arten von Problemen: aufgeblähte Sitzungsdateien und die Unfähigkeit, historische Sitzungen zu finden.
Sitzungsdatei zu groß
Symptom: Die Kontextnutzung steigt weiter, Antworten werden langsamer oder die Komprimierung wird frühzeitig ausgelöst.
| Mögliche Ursachen | Methoden zur Fehlerbehebung | Lösungen |
|---|---|---|
| Gesprächsverlauf zu lang | Führe/sessionaus, um Nachrichtenanzahl und Token-Nutzung zu prüfen | Führe/compactaus, um den Konversationsverlauf zu komprimieren |
| Automatische Komprimierung nicht aktiviert | Prüfecompaction.enabled, ob er true ist | Nach dem Setzen auf true starte pi neu, damit es wirksam wird |
| Eine einzelne Sitzung hat sich zu lange angesammelt | Verwende/session, um das Wachstum der Sitzungsdateigröße zu beobachten | Verwende regelmäßig/new, um eine neue Sitzung zu starten, teile Sitzungen nach Aufgabe auf |
Vorherige Sitzung kann nicht gefunden werden
Symptom: Frühere Arbeitsaufzeichnungen sind in der pi -r-Liste nicht zu sehen.
| Mögliche Ursachen | Methoden zur Fehlerbehebung | Lösungen |
|---|---|---|
| Der Resume-Einstiegspunkt wurde nicht verwendet | Führepi -raus oder gib im interaktiven Modus /resume ein, um die Sitzungsliste zu durchsuchen | Wählen Sie die Zielsitzung in der Liste aus, um fortzufahren |
| sessionDirEinstellungen wurden geändert | Prüfen Sie in settings.jsonsessionDirden aktuellen Wert von | Wechseln Sie zurück zum ursprünglichen Verzeichnis oder migrieren Sie Dateien vom ursprünglichen Verzeichnis in das neue Verzeichnis |
| Berechtigungsanomalie im Sitzungsverzeichnis | Führen Siels ~/.pi/agent/sessions/aus. Bestätigen Sie, dass es lesbar und beschreibbar ist. | Führen Siechmod -R u+rw ~/.pi/agent/sessionsaus. Korrigieren Sie die Berechtigungen. |
Leistungsprobleme
Dieser Abschnitt behandelt zwei Arten von Leistungsproblemen: langsame Antworten und Leistungseinbußen bei langem Kontext.
KI-Antworten sind langsam
Symptom: Nach dem Absenden einer Anfrage erfolgt für längere Zeit keine Ausgabe des ersten Wortes, oder die Gesamtzeit ist deutlich höher als üblich.
| Mögliche Ursachen | Methoden zur Fehlerbehebung | Lösungen |
|---|---|---|
| Hohe Netzwerklatenz oder unterbrochene Verbindung | Führen Sieping api.anthropic.comaus, um Latenz und Paketverlust zu prüfen | Wechseln Sie das Netzwerk oder konfigurieren Sie einen Proxy wie in den unten stehenden Proxy-Einstellungen beschrieben |
| Reasoning-Level zu hoch, Denkzeit verlängert | Prüfen Sie das aktuelle Reasoning-Level in der Statusleiste | Drücken Sie Shift+Tab, um das Reasoning-Level zu senken |
| System-Prompt oder Inhalt der Kontextdatei ist zu groß | Prüfen Sie die Größe von Kontextdateien wie AGENTS.md | Kürzen Sie den System-Prompt, verschlanken Sie den Inhalt von AGENTS.md |
| Token-Verbrauch pro Anfrage ist zu hoch | Führen Sie/sessionaus, um die Token-Nutzung und die Verteilung des Zeitverbrauchs anzuzeigen | Führen Sie/compactoder/newaus, um den Kontext zu kürzen, und versuchen Sie es erneut |
Wenn Sie eine Proxy-Umgebung verwenden, wechseln Sie zucurl -x $HTTP_PROXY https://api.anthropic.comzum Testen.
In einer Proxy-Umgebung bedeutet ein Ping-Fehler nicht, dass die API nicht verfügbar ist.
ping verwendet ICMP, während die API HTTPS verwendet; wechseln Sie in diesem Fall zu curl, um die tatsächliche Verbindung zu überprüfen.
Die KI-Leistung verschlechtert sich nach großem Kontext
Symptom: Nach mehreren Gesprächsrunden beginnt die KI, vorherige Vereinbarungen zu vergessen, oder gibt repetitive Antworten.
| Mögliche Ursachen | Methoden zur Fehlerbehebung | Lösungen |
|---|---|---|
| Der Kontext nähert sich dem Fensterlimit, und frühere Inhalte werden wegkomprimiert | Führen Sie/sessionaus, um die aktuelle Token-Nutzung zu prüfen | Führen Sie manuell/compactaus, um den Kontext zu komprimieren |
| Eine große Anzahl ungültiger Versuche ist in die historischen Nachrichten eingemischt | Verwenden Sie/tree, um Verzweigungen und ungültige Konversationen zu prüfen | Verwenden Sie/new, um eine neue Sitzung zu starten und die Schlussfolgerungen in AGENTS.md zu schreiben |
| Der referenzierte Dateiinhalt steht in keinem Zusammenhang mit der aktuellen Aufgabe | Prüfen Sie, ob @-Referenzen und Kontextdateien irrelevanten Inhalt enthalten | Reduziere unnötigen Inhalt der Kontextdatei, behalte nur, was die aktuelle Aufgabe benötigt |
Proxy-Einstellungen
Dieser Abschnitt erklärt, wie man Pi Agent in einer eingeschränkten Netzwerkumgebung normal auf die API zugreifen lässt.
Zugriff auf die API aus China
Konfiguriere einen HTTP-Proxy in settings.json:
{
"httpProxy": "http://127.0.0.1:7890"
}
Oder starten Sie nach dem Festlegen der Umgebungsvariablen:
$ export HTTP_PROXY=http://127.0.0.1:7890 $ export HTTPS_PROXY=http://127.0.0.1:7890 $ piAndere Erweiterungen