Manuel de référence de configuration de Pi Agent

Voici un tableau de référence rapide pour les éléments de configuration de Pi Agent settings.json.

Ce tableau comprend les éléments de configuration courants ; quelques clés avancées spécifiques à JSON (telles que tuiMode, la série fullscreen, terminal.hyperlinks, markdown.mermaid, etc.) ne sont pas répertoriées individuellement.


Emplacement du fichier de configuration

La configuration est divisée en deux niveaux : global et projet. La configuration du projet n'est chargée qu'après approbation du projet.

Chemin du fichierPortéeDescription
~/.pi/agent/settings.jsonGlobal (tous les projets)Configuration commune applicable à tous les projets
.pi/settings.jsonNiveau projetChargé uniquement après approbation du projet ; remplace les clés du même nom dans la configuration globale.

Modèle et raisonnement

La configuration de cette section détermine le fournisseur, le modèle et l'effort de raisonnement par défaut.

Élément de configurationTypeRequisValeur par défautDescription
defaultProviderstringOptionalAucun (défini lors de la première utilisation via /login ou /model)Fournisseur par défaut, par ex. "anthropic", "openai"
defaultModelstringOptionalAucun (défini lors de la première utilisation via /login ou /model)ID du modèle par défaut, par ex. "claude-sonnet-4-20250514"
defaultThinkingLevelstringOptionalAucun (non fourni par la documentation)Effort de raisonnement par défaut : off/minimal/low/medium/high/xhigh/max
modelThinkingLevelsobjetOptionalAucuneDéfinir l'effort de raisonnement au démarrage pour chaque modèle via "provider/modelId"
hideThinkingBlockbooléenOptionalfalseMasquer le processus de raisonnement
showCacheMissNoticesbooléenOptionalfalseAfficher les notifications de cache manqué
thinkingBudgetsobjetOptionalAucun (budget personnalisé non activé)Personnaliser le budget de tokens pour chaque niveau
warnings.anthropicExtraUsagebooléenOptionalvraiRappeler lorsque l'abonnement Anthropic peut entraîner une utilisation payante supplémentaire

Interface utilisateur et affichage

La configuration de cette section contrôle l'apparence de l'interface, l'éditeur externe et la densité d'affichage.

Élément de configurationTypeRequisValeur par défautDescription
themestringOptional"dark"Nom du thème
externalEditorstringOptionalUtilise $VISUAL, puis $EDITOR ; sinon, utilise Notepad sous Windows et nano sur les autres systèmesCommande de l'éditeur externe (la configuration explicite est prioritaire sur les variables d'environnement)
quietStartupbooléenOptionalfalseMasquer l'en-tête de démarrage
defaultProjectTruststringOptional"ask"Comportement par défaut de confiance des projets : "ask" (demande), "always" (confiance automatique), "never" (rejet automatique) ; effectif uniquement dans la configuration globale
collapseChangelogbooléenOptionalfalseRéduire le journal des modifications
enableInstallTelemetrybooléenOptionalvraiStatistiques d'installation anonymes
enableAnalyticsbooléenOptionalfalseAnalyse comportementale des utilisateurs (nécessite un consentement)
doubleEscapeActionstringOptional"tree"Action déclenchée par un double appui sur Échap ; ouvre par défaut le navigateur d'arborescence des sessions
treeFilterModestringOptional"default"/tree mode de filtre par défaut : default/no-tools/user-only/labeled-only/all
editorPaddingXnombreOptional0Marge horizontale de l'éditeur (0-3)
outputPadnombreOptional1Marge intérieure du message (0 ou 1)
autocompleteMaxVisiblenombreOptional5Nombre maximal d'entrées d'autocomplétion (3-20)

Réseau

La configuration de cette section est utilisée pour l'accès par proxy dans les environnements réseau restreints.

Élément de configurationTypeRequisValeur par défautDescription
httpProxystringOptionalAucun (aucun proxy utilisé)Proxy HTTP (global uniquement)

httpProxyUniquement effectif dans la configuration globale ; il est ignoré s'il est écrit dans la configuration au niveau du projet.

Lorsqu'un proxy est nécessaire, écrivez-le dans la configuration globale.~/.pi/agent/settings.json。


Compression

La configuration de cette section contrôle la politique de déclenchement et de conservation de la compression automatique du contexte.

Élément de configurationTypeRequisValeur par défautDescription
compaction.enabledbooléenOptionalvraiCompression automatique
compaction.reserveTokensnombreOptional16384Jetons réservés pour la réponse LLM
compaction.keepRecentTokensnombreOptional20000Jetons récents à conserver

Résumé de branche

La configuration de cette section contrôle s'il faut générer un résumé des branches abandonnées lors du passage entre arbres de session.

Élément de configurationTypeRequisValeur par défautDescription
branchSummary.reserveTokensnombreOptional16384Jetons réservés pour le résumé
branchSummary.skipPromptbooléenOptionalfalseIgnorer l'invite de résumé

Réessayer

La configuration de cette section contrôle le comportement de nouvelle tentative automatique après les échecs de requêtes.

Élément de configurationTypeRequisValeur par défautDescription
retry.enabledbooléenOptionalvraiNouvelle tentative automatique
retry.maxRetriesnombreOptional3Nombre maximal de nouvelles tentatives
retry.baseDelayMsnombreOptional2000Délai de base (ms)
retry.provider.timeoutMsnombreOptionalValeur par défaut du SDKDélai d’attente de la requête
retry.provider.maxRetriesnombreOptional0Nombre de tentatives au niveau du fournisseur
retry.provider.maxRetryDelayMsnombreOptional60000Délai maximal avant nouvelle tentative

Passage de messages

La configuration de cette section détermine comment les messages de directive et de suivi sont insérés, ainsi que le protocole de transport utilisé.

Élément de configurationTypeRequisValeur par défautDescription
steeringModestringOptional"one-at-a-time"Politique des messages de directive : "all" (insérer tous les messages de directive immédiatement) ou "one-at-a-time" (insérer un par un)
followUpModestringOptional"one-at-a-time"Politique des messages de suivi
transportstringOptional"auto"Protocole de transport : sse / websocket / websocket-cached / auto
httpIdleTimeoutMsnombreOptional300000Délai d'inactivité HTTP
websocketConnectTimeoutMsnombreOptional15000Délai de connexion WebSocket

Terminal et images

La configuration de cette section contrôle la taille d'affichage et le comportement d'envoi des images dans le terminal.

Élément de configurationTypeRequisValeur par défautDescription
terminal.showImagesbooléenOptionalvraiAfficher les images dans le terminal
terminal.imageWidthCellsnombreOptional60Largeur de l'image (cellules)
terminal.clearOnShrinkbooléenOptionalfalseEffacer les lignes vides lorsque le contenu rétrécit
images.autoResizebooléenOptionalvraiRedimensionnement automatique des images
images.blockImagesbooléenOptionalfalseEmpêcher l'envoi d'images au LLM

Tri de Shell

La configuration de cette section est utilisée pour personnaliser le shell et le wrapper npm lors de l'exécution des commandes.

Élément de configurationTypeRequisValeur par défautDescription
shellPathstringOptionalAucun (utiliser le shell par défaut du système)Chemin personnalisé du shell
shellCommandPrefixstringOptionalAucun (aucun préfixe ajouté)Préfixe de commande
npmCommandstring[]OptionalAucun (invoquer npm directement)Enveloppe de commande npm

Outils intégrés

La configuration de cette section contrôle l'ensemble des outils intégrés activés par défaut au démarrage.

Élément de configurationTypeRequisValeur par défautDescription
defaultToolsstring[]OptionalAucun (utiliser l'ensemble d'outils par défaut intégré)Outils intégrés activés initialement, valeurs facultatives : read/bash/powershell/edit/write/grep/find/ls, où powershell n'est disponible que sous Windows

Cette configuration affecte uniquement les outils intégrés ; les outils personnalisés enregistrés par les extensions et le SDK ne sont pas affectés.

Le tableau defaultTools au niveau du projet remplace complètement le tableau global.


Boucle de modèle et ressources

Cette section configure la portée de la boucle de modèle Ctrl+P, ainsi que les chemins de chargement des ressources telles que les extensions et les Skills.

Élément de configurationTypeRequisValeur par défautDescription
enabledModelsstring[]OptionalAucun (tous les modèles disponibles)Modèles disponibles via Ctrl+P
packagesarray (chaînes ou objets mixtes)Optional[]Source du package ; la forme chaîne charge toutes les ressources, la forme objet filtre à l'aide de champs tels que {source, skills, extensions}
extensionsstring[]Optional[]Chemin de l'extension
skillsstring[]Optional[]Chemin de la compétence
promptsstring[]Optional[]Chemin du gabarit
thèmesstring[]Optional[]Chemin du thème
enableSkillCommandsbooléenOptionalvraiEnregistrer la commande /skill:name
sessionDirstringOptionalAucun (utilise ~/.pi/agent/sessions/)Répertoire de stockage des sessions
Autres extensions