Pi Agent Konfigurationsreferenzhandbuch
Das Folgende ist eine Schnellreferenztabelle für die Konfigurationselemente von Pi Agent in settings.json.
Diese Tabelle enthält gängige Konfigurationselemente; einige JSON-spezifische erweiterte Schlüssel (wie tuiMode, Fullscreen-Serie, terminal.hyperlinks, markdown.mermaid usw.) sind nicht einzeln aufgeführt.
Speicherort der Konfigurationsdatei
Die Konfiguration ist in zwei Ebenen unterteilt: global und projektbezogen. Die Projektkonfiguration wird erst geladen, nachdem das Projekt als vertrauenswürdig eingestuft wurde.
| Dateipfad | Geltungsbereich | Beschreibung |
|---|---|---|
| ~/.pi/agent/settings.json | Global (alle Projekte) | Gemeinsame Konfiguration, die für alle Projekte gilt |
| .pi/settings.json | Projektebene | Wird erst geladen, nachdem das Projekt als vertrauenswürdig eingestuft wurde; überschreibt Schlüssel mit demselben Namen in der globalen Konfiguration. |
Modell und Reasoning
Die Konfiguration in diesem Abschnitt bestimmt den Standardanbieter, das Standardmodell und den Reasoning-Aufwand.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| defaultProvider | string | Optional | Keine (wird bei der ersten Verwendung über /login oder /model festgelegt) | Standardanbieter, z. B. "anthropic", "openai" |
| defaultModel | string | Optional | Keine (wird bei der ersten Verwendung über /login oder /model festgelegt) | Standardmodell-ID, z. B. "claude-sonnet-4-20250514" |
| defaultThinkingLevel | string | Optional | Keine (nicht von der Dokumentation bereitgestellt) | Standardmäßiger Denkaufwand: off/minimal/low/medium/high/xhigh/max |
| modelThinkingLevels | Objekt | Optional | Keine | Start-Denkaufwand für jedes Modell über "provider/modelId" festlegen |
| hideThinkingBlock | boolesch | Optional | false | Denkprozess ausblenden |
| showCacheMissNotices | boolesch | Optional | false | Cache-Miss-Benachrichtigungen anzeigen |
| thinkingBudgets | Objekt | Optional | Keine (benutzerdefiniertes Budget nicht aktiviert) | Token-Budget für jede Stufe anpassen |
| warnings.anthropicExtraUsage | boolesch | Optional | wahr | Erinnern, wenn beim Anthropic-Abonnement kostenpflichtige Zusatznutzung anfallen kann |
UI und Anzeige
Die Konfiguration in diesem Abschnitt steuert das Erscheinungsbild der Oberfläche, den externen Editor und die Anzeigedichte.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| theme | string | Optional | "dark" | Theme-Name |
| externalEditor | string | Optional | Verwendet $VISUAL, dann $EDITOR; andernfalls wird Notepad unter Windows und nano auf anderen Systemen verwendet | Befehl für externen Editor (explizite Konfiguration hat Vorrang vor Umgebungsvariablen) |
| quietStartup | boolesch | Optional | false | Startup-Header ausblenden |
| defaultProjectTrust | string | Optional | "ask" | Standardverhalten für Projektvertrauen: "ask" (Abfrage), "always" (automatisch vertrauen), "never" (automatisch ablehnen); nur in der globalen Konfiguration wirksam |
| collapseChangelog | boolesch | Optional | false | Changelog einklappen |
| enableInstallTelemetry | boolesch | Optional | wahr | Anonyme Installationsstatistiken |
| enableAnalytics | boolesch | Optional | false | Analyse des Nutzerverhaltens (erfordert Opt-in) |
| doubleEscapeAction | string | Optional | "tree" | Aktion, die durch doppeltes Drücken von Escape ausgelöst wird; standardmäßig wird der Sitzungsbaum-Browser geöffnet |
| treeFilterMode | string | Optional | "default" | /tree Standardfiltermodus: default/no-tools/user-only/labeled-only/all |
| editorPaddingX | number | Optional | 0 | Horizontaler Innenabstand des Editors (0-3) |
| outputPad | number | Optional | 1 | Nachrichten-Padding (0 oder 1) |
| autocompleteMaxVisible | number | Optional | 5 | Maximale Autovervollständigungseinträge (3-20) |
Netzwerk
Die Konfiguration in diesem Abschnitt wird für den Proxy-Zugriff in eingeschränkten Netzwerkumgebungen verwendet.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| httpProxy | string | Optional | Keine (kein Proxy verwendet) | HTTP-Proxy (nur global) |
httpProxyNur in der globalen Konfiguration wirksam; sie wird ignoriert, wenn sie in der Projektkonfiguration angegeben wird.
Wenn ein Proxy benötigt wird, schreibe ihn in die globale Konfiguration.~/.pi/agent/settings.json。
Komprimierung
Die Konfiguration in diesem Abschnitt steuert die Auslöse- und Aufbewahrungsrichtlinie der automatischen Kontextkomprimierung.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| compaction.enabled | boolesch | Optional | wahr | Automatische Komprimierung |
| compaction.reserveTokens | number | Optional | 16384 | Reservierte Tokens für LLM-Antwort |
| compaction.keepRecentTokens | number | Optional | 20000 | Aktuelle Tokens, die beibehalten werden |
Branch-Zusammenfassung
Die Konfiguration in diesem Abschnitt steuert, ob beim Wechseln zwischen Sitzungsbäumen eine Zusammenfassung aufgegebener Branches erstellt wird.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| branchSummary.reserveTokens | number | Optional | 16384 | Reservierte Token für die Zusammenfassung |
| branchSummary.skipPrompt | boolesch | Optional | false | Zusammenfassungs-Prompt überspringen |
Wiederholen
Die Konfiguration in diesem Abschnitt steuert das automatische Wiederholungsverhalten nach fehlgeschlagenen Anfragen.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| retry.enabled | boolesch | Optional | wahr | Automatische Wiederholung |
| retry.maxRetries | number | Optional | 3 | Maximale Anzahl der Wiederholungsversuche |
| retry.baseDelayMs | number | Optional | 2000 | Basisverzögerung (ms) |
| retry.provider.timeoutMs | number | Optional | SDK-Standard | Anfrage-Timeout |
| retry.provider.maxRetries | number | Optional | 0 | Anzahl der Wiederholungsversuche auf Provider-Ebene |
| retry.provider.maxRetryDelayMs | number | Optional | 60000 | Maximale Wiederholungsverzögerung |
Nachrichtenübermittlung
Die Konfiguration in diesem Abschnitt bestimmt, wie Direktiven- und Folge-Nachrichten eingefügt werden, sowie das verwendete Transportprotokoll.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| steeringMode | string | Optional | "one-at-a-time" | Richtlinie für Direktivennachrichten: "all" (alle Direktivennachrichten sofort einfügen) oder "one-at-a-time" (einzeln nacheinander einfügen) |
| followUpMode | string | Optional | "one-at-a-time" | Richtlinie für Follow-up-Nachrichten |
| transport | string | Optional | "auto" | Transportprotokoll: sse / websocket / websocket-cached / auto |
| httpIdleTimeoutMs | number | Optional | 300000 | HTTP-Leerlaufzeitüberschreitung |
| websocketConnectTimeoutMs | number | Optional | 15000 | WebSocket-Verbindungszeitüberschreitung |
Terminal und Bilder
Die Konfiguration in diesem Abschnitt steuert die Anzeigegröße und das Sendeverhalten von Bildern im Terminal.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| terminal.showImages | boolesch | Optional | wahr | Bilder im Terminal anzeigen |
| terminal.imageWidthCells | number | Optional | 60 | Bildbreite (Zellen) |
| terminal.clearOnShrink | boolesch | Optional | false | Leere Zeilen entfernen, wenn der Inhalt schrumpft |
| images.autoResize | boolesch | Optional | wahr | Automatische Bildskalierung |
| images.blockImages | boolesch | Optional | false | Verhindern, dass Bilder an LLM gesendet werden |
Shell
Die Konfiguration in diesem Abschnitt wird verwendet, um die Shell und den npm-Wrapper beim Ausführen von Befehlen anzupassen.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| shellPath | string | Optional | Keine (Standard-Shell des Systems verwenden) | Benutzerdefinierter Shell-Pfad |
| shellCommandPrefix | string | Optional | Keiner (kein Präfix hinzugefügt) | Befehlspräfix |
| npmCommand | string[] | Optional | Keine (npm direkt aufrufen) | npm-Befehlswrapper |
Integrierte Tools
Die Konfiguration in diesem Abschnitt steuert die Menge der integrierten Tools, die beim Start standardmäßig aktiviert sind.
| Konfigurationselement | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| defaultTools | string[] | Optional | Keine (das integrierte Standard-Toolset verwenden) | Anfänglich aktivierte integrierte Tools, optionale Werte: read/bash/powershell/edit/write/grep/find/ls, wobei powershell nur unter Windows verfügbar ist |
Diese Konfiguration betrifft nur integrierte Tools; benutzerdefinierte Tools, die von Erweiterungen und dem SDK registriert werden, sind nicht betroffen.
Das defaultTools-Array auf Projektebene ersetzt das globale Array vollständig.
Modellschleife und Ressourcen
Dieser Abschnitt konfiguriert den Geltungsbereich der Ctrl+P-Modellschleife sowie die Ladepfade für Ressourcen wie Erweiterungen und Skills.
| Konfigurationseintrag | Type | Erforderlich | Standardwert | Beschreibung |
|---|---|---|---|---|
| enabledModels | string[] | Optional | Keine (alle verfügbaren Modelle) | Verfügbare Modelle mit Ctrl+P |
| packages | Array (gemischte Strings oder Objekte) | Optional | [] | Paketquelle; String-Form lädt alle Ressourcen, Objekt-Form filtert anhand von Feldern wie {source, skills, extensions} |
| extensions | string[] | Optional | [] | Erweiterungspfad |
| skills | string[] | Optional | [] | Skill-Pfad |
| prompts | string[] | Optional | [] | Vorlagenpfad |
| Themes | string[] | Optional | [] | Theme-Pfad |
| enableSkillCommands | boolesch | Optional | wahr | Befehl /skill:name registrieren |
| sessionDir | string | Optional | Keine (verwendet ~/.pi/agent/sessions/) | Sitzungsspeicherverzeichnis |