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 fichier | Portée | Description |
|---|---|---|
| ~/.pi/agent/settings.json | Global (tous les projets) | Configuration commune applicable à tous les projets |
| .pi/settings.json | Niveau projet | Chargé 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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| defaultProvider | string | Optional | Aucun (défini lors de la première utilisation via /login ou /model) | Fournisseur par défaut, par ex. "anthropic", "openai" |
| defaultModel | string | Optional | Aucun (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" |
| defaultThinkingLevel | string | Optional | Aucun (non fourni par la documentation) | Effort de raisonnement par défaut : off/minimal/low/medium/high/xhigh/max |
| modelThinkingLevels | objet | Optional | Aucune | Définir l'effort de raisonnement au démarrage pour chaque modèle via "provider/modelId" |
| hideThinkingBlock | booléen | Optional | false | Masquer le processus de raisonnement |
| showCacheMissNotices | booléen | Optional | false | Afficher les notifications de cache manqué |
| thinkingBudgets | objet | Optional | Aucun (budget personnalisé non activé) | Personnaliser le budget de tokens pour chaque niveau |
| warnings.anthropicExtraUsage | booléen | Optional | vrai | Rappeler 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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| theme | string | Optional | "dark" | Nom du thème |
| externalEditor | string | Optional | Utilise $VISUAL, puis $EDITOR ; sinon, utilise Notepad sous Windows et nano sur les autres systèmes | Commande de l'éditeur externe (la configuration explicite est prioritaire sur les variables d'environnement) |
| quietStartup | booléen | Optional | false | Masquer l'en-tête de démarrage |
| defaultProjectTrust | string | Optional | "ask" | Comportement par défaut de confiance des projets : "ask" (demande), "always" (confiance automatique), "never" (rejet automatique) ; effectif uniquement dans la configuration globale |
| collapseChangelog | booléen | Optional | false | Réduire le journal des modifications |
| enableInstallTelemetry | booléen | Optional | vrai | Statistiques d'installation anonymes |
| enableAnalytics | booléen | Optional | false | Analyse comportementale des utilisateurs (nécessite un consentement) |
| doubleEscapeAction | string | Optional | "tree" | Action déclenchée par un double appui sur Échap ; ouvre par défaut le navigateur d'arborescence des sessions |
| treeFilterMode | string | Optional | "default" | /tree mode de filtre par défaut : default/no-tools/user-only/labeled-only/all |
| editorPaddingX | nombre | Optional | 0 | Marge horizontale de l'éditeur (0-3) |
| outputPad | nombre | Optional | 1 | Marge intérieure du message (0 ou 1) |
| autocompleteMaxVisible | nombre | Optional | 5 | Nombre 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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| httpProxy | string | Optional | Aucun (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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| compaction.enabled | booléen | Optional | vrai | Compression automatique |
| compaction.reserveTokens | nombre | Optional | 16384 | Jetons réservés pour la réponse LLM |
| compaction.keepRecentTokens | nombre | Optional | 20000 | Jetons 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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| branchSummary.reserveTokens | nombre | Optional | 16384 | Jetons réservés pour le résumé |
| branchSummary.skipPrompt | booléen | Optional | false | Ignorer 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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| retry.enabled | booléen | Optional | vrai | Nouvelle tentative automatique |
| retry.maxRetries | nombre | Optional | 3 | Nombre maximal de nouvelles tentatives |
| retry.baseDelayMs | nombre | Optional | 2000 | Délai de base (ms) |
| retry.provider.timeoutMs | nombre | Optional | Valeur par défaut du SDK | Délai d’attente de la requête |
| retry.provider.maxRetries | nombre | Optional | 0 | Nombre de tentatives au niveau du fournisseur |
| retry.provider.maxRetryDelayMs | nombre | Optional | 60000 | Dé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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| steeringMode | string | Optional | "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) |
| followUpMode | string | Optional | "one-at-a-time" | Politique des messages de suivi |
| transport | string | Optional | "auto" | Protocole de transport : sse / websocket / websocket-cached / auto |
| httpIdleTimeoutMs | nombre | Optional | 300000 | Délai d'inactivité HTTP |
| websocketConnectTimeoutMs | nombre | Optional | 15000 | Dé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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| terminal.showImages | booléen | Optional | vrai | Afficher les images dans le terminal |
| terminal.imageWidthCells | nombre | Optional | 60 | Largeur de l'image (cellules) |
| terminal.clearOnShrink | booléen | Optional | false | Effacer les lignes vides lorsque le contenu rétrécit |
| images.autoResize | booléen | Optional | vrai | Redimensionnement automatique des images |
| images.blockImages | booléen | Optional | false | Empê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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| shellPath | string | Optional | Aucun (utiliser le shell par défaut du système) | Chemin personnalisé du shell |
| shellCommandPrefix | string | Optional | Aucun (aucun préfixe ajouté) | Préfixe de commande |
| npmCommand | string[] | Optional | Aucun (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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| defaultTools | string[] | Optional | Aucun (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 configuration | Type | Requis | Valeur par défaut | Description |
|---|---|---|---|---|
| enabledModels | string[] | Optional | Aucun (tous les modèles disponibles) | Modèles disponibles via Ctrl+P |
| packages | array (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} |
| extensions | string[] | Optional | [] | Chemin de l'extension |
| skills | string[] | Optional | [] | Chemin de la compétence |
| prompts | string[] | Optional | [] | Chemin du gabarit |
| thèmes | string[] | Optional | [] | Chemin du thème |
| enableSkillCommands | booléen | Optional | vrai | Enregistrer la commande /skill:name |
| sessionDir | string | Optional | Aucun (utilise ~/.pi/agent/sessions/) | Répertoire de stockage des sessions |