Pi Agent – Häufige Probleme und Fehlerbehebung

Die folgenden sind häufige Probleme und Lösungen, die bei der Verwendung von Pi Agent auftreten.

Pi Agent 启动异常排查决策树


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 UrsachenSchritte zur FehlerbehebungLö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üfenVerwende 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 UrsachenSchritte zur FehlerbehebungLö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 existiertFü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 UrsachenSchritte zur FehlerbehebungLö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-RemoteverbindungDer 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 UrsachenSchritte zur FehlerbehebungLösungen
Umgebungsvariablen sind nicht korrekt gesetzt.Führen Sieecho $ANTHROPIC_API_KEYaus, um die Ausgabe anzuzeigenWenn 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 UrsachenSchritte zur FehlerbehebungLö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 UrsachenSchritte zur FehlerbehebungLö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.minimumContrastRatioSetzen 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 UrsachenSchritte zur FehlerbehebungLö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 UrsachenSchritte zur FehlerbehebungLö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 UrsachenMethoden zur FehlerbehebungLösungen
Gesprächsverlauf zu langFühre/sessionaus, um Nachrichtenanzahl und Token-Nutzung zu prüfenFühre/compactaus, um den Konversationsverlauf zu komprimieren
Automatische Komprimierung nicht aktiviertPrüfecompaction.enabled, ob er true istNach dem Setzen auf true starte pi neu, damit es wirksam wird
Eine einzelne Sitzung hat sich zu lange angesammeltVerwende/session, um das Wachstum der Sitzungsdateigröße zu beobachtenVerwende 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 UrsachenMethoden zur FehlerbehebungLösungen
Der Resume-Einstiegspunkt wurde nicht verwendetFührepi -raus oder gib im interaktiven Modus /resume ein, um die Sitzungsliste zu durchsuchenWählen Sie die Zielsitzung in der Liste aus, um fortzufahren
sessionDirEinstellungen wurden geändertPrüfen Sie in settings.jsonsessionDirden aktuellen Wert vonWechseln Sie zurück zum ursprünglichen Verzeichnis oder migrieren Sie Dateien vom ursprünglichen Verzeichnis in das neue Verzeichnis
Berechtigungsanomalie im SitzungsverzeichnisFü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 UrsachenMethoden zur FehlerbehebungLösungen
Hohe Netzwerklatenz oder unterbrochene VerbindungFühren Sieping api.anthropic.comaus, um Latenz und Paketverlust zu prüfenWechseln Sie das Netzwerk oder konfigurieren Sie einen Proxy wie in den unten stehenden Proxy-Einstellungen beschrieben
Reasoning-Level zu hoch, Denkzeit verlängertPrüfen Sie das aktuelle Reasoning-Level in der StatusleisteDrü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.mdKürzen Sie den System-Prompt, verschlanken Sie den Inhalt von AGENTS.md
Token-Verbrauch pro Anfrage ist zu hochFühren Sie/sessionaus, um die Token-Nutzung und die Verteilung des Zeitverbrauchs anzuzeigenFü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 UrsachenMethoden zur FehlerbehebungLösungen
Der Kontext nähert sich dem Fensterlimit, und frühere Inhalte werden wegkomprimiertFühren Sie/sessionaus, um die aktuelle Token-Nutzung zu prüfenFühren Sie manuell/compactaus, um den Kontext zu komprimieren
Eine große Anzahl ungültiger Versuche ist in die historischen Nachrichten eingemischtVerwenden Sie/tree, um Verzweigungen und ungültige Konversationen zu prüfenVerwenden 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 AufgabePrüfen Sie, ob @-Referenzen und Kontextdateien irrelevanten Inhalt enthaltenReduziere 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
$ pi
Andere Erweiterungen