Pi Agent-Konfiguration erklärt
Pi Agent verwendet Konfigurationsdateien im JSON-Format und unterstützt sowohl globale Konfiguration als auch Konfiguration auf Projektebene.
Speicherort der Konfigurationsdatei
Pi Agent liest die Konfiguration aus zwei festen Pfaden, und die beiden haben unterschiedliche Prioritäten.
| Dateipfad | Geltungsbereich | Beschreibung |
|---|---|---|
| ~/.pi/agent/settings.json | Global (alle Projekte) | Allgemeine Konfiguration, die für alle Projekte gilt |
| .pi/settings.json | Projektebene | Gilt nur für das aktuelle Projekt und überschreibt die globale Konfiguration |
Du kannst die JSON-Datei direkt bearbeiten oder den Befehl/settingsdes interaktiven Modus verwenden, um gängige Optionen zu ändern.
Modell- und Reasoning-Konfiguration
Die folgenden Konfigurationselemente steuern, welcher Anbieter und welches Modell standardmäßig verwendet werden und wie das Reasoning-Budget zugewiesen wird.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| defaultProvider | string | - | Standardanbieter, z. B. "anthropic", "openai" |
| defaultModel | string | - | Standardmodell-ID |
| defaultThinkingLevel | string | - | Standard-Reasoning-Level, Optionen: off / minimal / low / medium / high / xhigh / max |
| hideThinkingBlock | boolesch | false | KI-Reasoning-Prozess standardmäßig ausblenden |
| showCacheMissNotices | boolesch | false | Cache-Miss-Benachrichtigungen anzeigen |
| thinkingBudgets | Objekt | - | Token-Budget für jede Stufe anpassen |
Beispiel für benutzerdefiniertes Reasoning-Budget:
Beispiel
"thinkingBudgets": {
"minimal": 1024,
"low": 4096,
"medium": 10240,
"high": 32768
}
}
Es ist zu beachten, dass die unten stehenden Werte nur Demonstrationszwecken dienen und keine offiziellen Standardwerte sind.
Die Bedeutung jeder Stufe und ihr entsprechendes Beispielbudget ist wie folgt:
| Stufe | Anwendungsfall | Beispielbudget |
|---|---|---|
| minimal | Nahezu kein Reasoning, schnellste Antwort angestrebt | 1024 |
| low | Einfache Fragen und Antworten sowie kleine Änderungen | 4096 |
| mittel | Standardwahl für alltägliche Programmieraufgaben | 10240 |
| hoch | Komplexes Refactoring und Fehlerbehebung bei schwierigen Problemen | 32768 |
UI- und Anzeigekonfiguration
Die folgenden Konfigurationselemente steuern das Erscheinungsbild des Themes, das Editor-Layout und das Startverhalten.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| theme | string | "dark" | Theme-Name |
| externalEditor | string | Automatisch basierend auf dem System ausgewählt | Externer Editor-Befehl, geöffnet mit Ctrl+G |
| quietStartup | boolesch | false | Start-Header-Informationen ausblenden |
| collapseChangelog | boolesch | false | Ob nach Updates ein eingeklapptes Changelog angezeigt werden soll |
| editorPaddingX | number | 0 | Horizontaler Innenabstand des Editors (0-3) |
| outputPad | number | 1 | Horizontaler Innenabstand des Nachrichtenbereichs (0 oder 1) |
| autocompleteMaxVisible | number | 5 | Maximal sichtbare Autovervollständigungseinträge (3-20) |
Empfohlene Konfiguration des externen Editors für VS Code-Nutzer:
Beispiel
"externalEditor": "code --wait"
}
--waitDer Parameter stellt sicher, dass Pi Agent erst fortgesetzt wird, nachdem VS Code die Datei geschlossen hat; andernfalls führt Pi Agent die Ausführung sofort nach dem Öffnen des Editors fort.
Netzwerkkonfiguration
Die folgenden Konfigurationselemente steuern den Proxy, den Pi Agent beim Zugriff auf Modell-APIs verwendet.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| httpProxy | string | - | HTTP-Proxy-URL (nur globale Konfiguration) |
Einrichten eines Proxys (für Umgebungen wie das chinesische Festland, in denen ein Proxy für den Zugriff auf APIs erforderlich ist):
Beispiel
"httpProxy": "http://127.0.0.1:7890"
}
Konfiguration der Kontextkomprimierung
Wenn sich der Kontext seinem Limit nähert, komprimiert Pi Agent automatisch historische Nachrichten. Diese Einstellungen steuern, wann die Komprimierung ausgelöst wird und was beibehalten wird.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| compaction.enabled | boolesch | wahr | Automatische Komprimierung aktivieren |
| compaction.reserveTokens | number | 16384 | Für die LLM-Antwort reservierte Tokens |
| compaction.keepRecentTokens | number | 20000 | Anzahl der neuesten Tokens, die unkomprimiert beibehalten werden |
Konfiguration für Wiederholungsversuche
Die folgenden Konfigurationselemente bestimmen das automatische Wiederholungsverhalten nach Anfragefehlern, einschließlich der Anzahl der Wiederholungsversuche und des Backoff-Intervalls.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| retry.enabled | boolesch | wahr | Automatische Wiederholung aktivieren |
| retry.maxRetries | number | 3 | Maximale Anzahl der Wiederholungsversuche |
| retry.baseDelayMs | number | 2000 | Basisverzögerung für Wiederholungsversuche (Millisekunden), exponentielles Backoff: 2s, 4s, 8s |
| retry.provider.timeoutMs | number | SDK-Standard | Anfrage-Timeout (Millisekunden) |
| retry.provider.maxRetries | number | 0 | Anzahl der Wiederholungsversuche auf Provider-Ebene |
Es wird empfohlen,retry.provider.maxRetrieses bei 0 zu belassen, es sei denn, Sie benötigen wirklich Wiederholungsversuche auf Anbieterebene.
Wenn Sie es auf größer als 0 setzen, kann dies dazu führen, dass Wiederholungsversuche auf SDK-Ebene Pi Agent blockieren, wenn Nutzungslimits überschritten werden, anstatt dass der Wiederholungsmechanismus von Pi Agent dies übernimmt.
Konfiguration der Nachrichtenzustellung
Die folgenden Konfigurationselemente steuern, wann und wie Nachrichten, die Sie in die Unterhaltung einfügen, an das Modell gesendet werden.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| steeringMode | string | "one-at-a-time" | Sendestrategie für Steuerungsnachrichten: "all" oder "one-at-a-time" |
| followUpMode | string | "one-at-a-time" | Sendestrategie für Follow-up-Nachrichten |
| transport | string | "auto" | Transportprotokoll: "sse", "websocket", "websocket-cached", "auto" |
Terminal- und Bildkonfiguration
Die folgenden Konfigurationselemente steuern, wie Bilder im Terminal angezeigt werden und wie sie verarbeitet werden, bevor sie an das Modell gesendet werden.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| terminal.showImages | boolesch | wahr | Bilder im Terminal anzeigen |
| terminal.imageWidthCells | number | 60 | Inline-Bildbreite (Terminalzellen) |
| images.autoResize | boolesch | wahr | Bilder auf maximal 2000x2000 herunterskalieren |
| images.blockImages | boolesch | false | Blockiere das Senden aller Bilder an das LLM |
Shell-Konfiguration
Die folgenden Konfigurationselemente steuern die Shell und das Befehlspräfix, die verwendet werden, wenn Pi Agent Bash-Befehle ausführt.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| shellPath | string | - | Benutzerdefinierter Shell-Pfad |
| shellCommandPrefix | string | - | Präfix für jeden Bash-Befehl |
| npmCommand | string[] | - | Benutzerdefinierter Befehl für npm-Paketoperationen |
Beispiel für die Verwendung von Tools wie mise oder asdf zur Verwaltung der Node.js-Version:
Beispiel
"npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
Modellwechsel-Konfiguration
Die folgenden Konfigurationselemente steuern, welche Modelle sichtbar sind, wenn mit Ctrl+P durch die Modelle gewechselt wird.
| Konfigurationselement | Type | Standardwert | Beschreibung |
|---|---|---|---|
| enabledModels | string[] | - | Liste der Modelle, die beim Wechseln mit Ctrl+P verfügbar sind, unterstützt Wildcards |
Beispiel
"enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}
Regeln zum Zusammenführen der Konfiguration
Projektkonfiguration (.pi/settings.json) überschreibt die globale Konfiguration (~/.pi/agent/settings.json).
Verschachtelte Objekte verwendenZusammenführenstatt Ersetzung. Das folgende Beispiel veranschaulicht dies.
Globale Konfigurationsdatei ~/.pi/agent/settings.json:
Beispiel
"theme": "dark",
"compaction": { "enabled": true, "reserveTokens": 16384 }
}
Projektkonfigurationsdatei .pi/settings.json:
Beispiel
"compaction": { "reserveTokens": 8192 }
}
In der effektiven Konfiguration nach dem Zusammenführen übernimmt theme den globalen Wert dark, compaction.enabled übernimmt den globalen Wert true, und compaction.reserveTokens wird durch die Projektkonfiguration auf 8192 überschrieben.
Mit anderen Worten, die Projektkonfiguration überschreibt nur die Felder, die sie explizit deklariert, und alle anderen Felder verwenden weiterhin die globale Konfiguration.
Vollständiges Konfigurationsbeispiel
Das Folgende ist eine typische globale Konfigurationsdatei:
Beispiel
"defaultProvider": "anthropic",
"defaultModel": "claude-sonnet-4-20250514",
"defaultThinkingLevel": "medium",
"theme": "dark",
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
},
"retry": {
"enabled": true,
"maxRetries": 3
},
"enabledModels": ["claude-*", "gpt-4o"],
"warnings": {
"anthropicExtraUsage": true
},
"packages": ["pi-skills"]
}
warnings.anthropicExtraUsage ist ein Boolean mit dem Standardwert true.
Es gibt einen Hinweis, wenn die Authentifizierung des Anthropic-Abonnements zu zusätzlicher kostenpflichtiger Nutzung führen kann.
packages ist eine Filterkonfiguration für installierte Pakete, mit der festgelegt wird, welche Pakete geladen werden sollen.
Andere Erweiterungen