Configuration de Pi Agent expliquée
Pi Agent utilise des fichiers de configuration au format JSON, prenant en charge à la fois la configuration globale et la configuration au niveau du projet.
Emplacement du fichier de configuration
Pi Agent lit la configuration à partir de deux chemins fixes, et les deux ont des priorités différentes.
| Chemin du fichier | Portée | Description |
|---|---|---|
| ~/.pi/agent/settings.json | Global (tous les projets) | Configuration générale applicable à tous les projets |
| .pi/settings.json | Niveau projet | Ne prend effet que pour le projet actuel et remplace la configuration globale |
Vous pouvez modifier directement le fichier JSON, ou utiliser la commande/settingsdu mode interactif pour modifier les options courantes.
Configuration du modèle et du raisonnement
Les éléments de configuration suivants contrôlent quel fournisseur et quel modèle sont utilisés par défaut, ainsi que la manière dont le budget de raisonnement est alloué.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| defaultProvider | string | - | Fournisseur par défaut, par ex. "anthropic", "openai" |
| defaultModel | string | - | ID du modèle par défaut |
| defaultThinkingLevel | string | - | Niveau de raisonnement par défaut, options : off / minimal / low / medium / high / xhigh / max |
| hideThinkingBlock | booléen | false | Masquer le processus de raisonnement de l'IA par défaut |
| showCacheMissNotices | booléen | false | Afficher les notifications de défaut de cache |
| thinkingBudgets | objet | - | Personnaliser le budget de tokens pour chaque niveau |
Exemple de budget de raisonnement personnalisé :
Exemple
"thinkingBudgets": {
"minimal": 1024,
"low": 4096,
"medium": 10240,
"high": 32768
}
}
Il convient de noter que les valeurs ci-dessous sont uniquement à titre de démonstration et non les valeurs par défaut officielles.
La signification de chaque niveau et son budget d'exemple correspondant est la suivante :
| Niveau | Scénario applicable | Budget d'exemple |
|---|---|---|
| minimal | Presque aucun raisonnement, visant la réponse la plus rapide | 1024 |
| low | Questions-réponses simples et petites modifications | 4096 |
| moyen | Choix par défaut pour les tâches de codage quotidiennes | 10240 |
| élevé | Refactorisation complexe et résolution de problèmes difficiles | 32768 |
Configuration de l'interface et de l'affichage
Les éléments de configuration suivants contrôlent l'apparence du thème, la disposition de l'éditeur et le comportement au démarrage.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| theme | string | "dark" | Nom du thème |
| externalEditor | string | Sélectionné automatiquement en fonction du système | Commande de l'éditeur externe ouverte avec Ctrl+G |
| quietStartup | booléen | false | Masquer les informations d'en-tête au démarrage |
| collapseChangelog | booléen | false | Indique s'il faut afficher un journal des modifications replié après les mises à jour |
| editorPaddingX | nombre | 0 | Marge horizontale de l'éditeur (0-3) |
| outputPad | nombre | 1 | Marge intérieure horizontale de la zone de messages (0 ou 1) |
| autocompleteMaxVisible | nombre | 5 | Nombre maximal d'entrées d'autocomplétion visibles (3-20) |
Configuration recommandée de l'éditeur externe pour les utilisateurs de VS Code :
Exemple
"externalEditor": "code --wait"
}
--waitLe paramètre garantit que Pi Agent ne reprend qu'après la fermeture du fichier par VS Code ; sinon, Pi Agent continue son exécution immédiatement après l'ouverture de l'éditeur.
Configuration réseau
Les éléments de configuration suivants contrôlent le proxy que Pi Agent utilise lors de l'accès aux API de modèles.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| httpProxy | string | - | URL du proxy HTTP (configuration globale uniquement) |
Configuration d’un proxy (pour des environnements tels que la Chine continentale où un proxy est nécessaire pour accéder aux API) :
Exemple
"httpProxy": "http://127.0.0.1:7890"
}
Configuration de la compression du contexte
Lorsque le contexte approche de sa limite, Pi Agent compresse automatiquement les messages historiques. Ces paramètres contrôlent quand la compression est déclenchée et ce qui est conservé.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| compaction.enabled | booléen | vrai | Activer la compression automatique |
| compaction.reserveTokens | nombre | 16384 | Tokens réservés pour la réponse du LLM |
| compaction.keepRecentTokens | nombre | 20000 | Nombre de tokens récents conservés non compressés |
Configuration des réessais
Les éléments de configuration suivants déterminent le comportement de réessai automatique après l’échec des requêtes, y compris le nombre de tentatives et l’intervalle de temporisation.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| retry.enabled | booléen | vrai | Activer le réessai automatique |
| retry.maxRetries | nombre | 3 | Nombre maximal de tentatives |
| retry.baseDelayMs | nombre | 2000 | Délai de nouvelle tentative de base (millisecondes), backoff exponentiel : 2s, 4s, 8s |
| retry.provider.timeoutMs | nombre | Valeur par défaut du SDK | Délai d'expiration de la requête (millisecondes) |
| retry.provider.maxRetries | nombre | 0 | Nombre de tentatives au niveau du fournisseur |
Il est recommandé de garderretry.provider.maxRetriesà 0, sauf si vous avez vraiment besoin de nouvelles tentatives au niveau du fournisseur.
Le fait de le définir à une valeur supérieure à 0 peut amener les nouvelles tentatives au niveau du SDK à bloquer Pi Agent lorsque les limites d'utilisation sont dépassées, au lieu de laisser le mécanisme de nouvelle tentative de Pi Agent gérer cela.
Configuration de remise des messages
Les éléments de configuration suivants contrôlent quand et comment les messages que vous insérez dans la conversation sont envoyés au modèle.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| steeringMode | string | "one-at-a-time" | Stratégie d'envoi des messages de pilotage : "all" ou "one-at-a-time" |
| followUpMode | string | "one-at-a-time" | Stratégie d'envoi des messages de suivi |
| transport | string | "auto" | Protocole de transport : "sse", "websocket", "websocket-cached", "auto" |
Configuration du terminal et des images
Les éléments de configuration suivants contrôlent comment les images sont affichées dans le terminal et comment elles sont traitées avant d'être envoyées au modèle.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| terminal.showImages | booléen | vrai | Afficher les images dans le terminal |
| terminal.imageWidthCells | nombre | 60 | Largeur de l'image en ligne (cellules du terminal) |
| images.autoResize | booléen | vrai | Réduire les images pour qu'elles tiennent dans 2000x2000 |
| images.blockImages | booléen | false | Bloquer l'envoi de toutes les images au LLM |
Configuration du shell
Les éléments de configuration suivants contrôlent le shell et le préfixe de commande utilisés lorsque Pi Agent exécute des commandes bash.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| shellPath | string | - | Chemin personnalisé du shell |
| shellCommandPrefix | string | - | Préfixe pour chaque commande bash |
| npmCommand | string[] | - | Commande personnalisée pour les opérations sur les paquets npm |
Exemple d'utilisation d'outils tels que mise ou asdf pour gérer la version de Node.js :
Exemple
"npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}
Configuration de la rotation des modèles
Les éléments de configuration suivants contrôlent les modèles visibles lors de la rotation entre les modèles avec Ctrl+P.
| Élément de configuration | Type | Valeur par défaut | Description |
|---|---|---|---|
| enabledModels | string[] | - | Liste des modèles disponibles lors de la rotation avec Ctrl+P, prend en charge les caractères génériques |
Exemple
"enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}
Règles de fusion de configuration
La configuration du projet (.pi/settings.json) surcharge la configuration globale (~/.pi/agent/settings.json).
Les objets imbriqués utilisentune fusionplutôt qu'un remplacement. L'exemple suivant l'illustre.
Fichier de configuration global ~/.pi/agent/settings.json :
Exemple
"theme": "dark",
"compaction": { "enabled": true, "reserveTokens": 16384 }
}
Fichier de configuration du projet .pi/settings.json :
Exemple
"compaction": { "reserveTokens": 8192 }
}
Dans la configuration effective après la fusion, theme prend la valeur globale dark, compaction.enabled prend la valeur globale true, et compaction.reserveTokens est surchargé à 8192 par la configuration du projet.
En d'autres termes, la configuration du projet ne surcharge que les champs qu'elle déclare explicitement, et tous les autres champs continuent d'utiliser la configuration globale.
Exemple de configuration complète
Voici un fichier de configuration global typique :
Exemple
"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 est un booléen, dont la valeur par défaut est true.
Il fournit un rappel lorsque l'authentification de l'abonnement Anthropic peut entraîner une utilisation payante supplémentaire.
packages est une configuration de filtre de paquets installés, utilisée pour déclarer quels paquets charger.
Autres extensions