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 fichierPortéeDescription
~/.pi/agent/settings.jsonGlobal (tous les projets)Configuration générale applicable à tous les projets
.pi/settings.jsonNiveau projetNe 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 configurationTypeValeur par défautDescription
defaultProviderstring-Fournisseur par défaut, par ex. "anthropic", "openai"
defaultModelstring-ID du modèle par défaut
defaultThinkingLevelstring-Niveau de raisonnement par défaut, options : off / minimal / low / medium / high / xhigh / max
hideThinkingBlockbooléenfalseMasquer le processus de raisonnement de l'IA par défaut
showCacheMissNoticesbooléenfalseAfficher les notifications de défaut de cache
thinkingBudgetsobjet-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 :

NiveauScénario applicableBudget d'exemple
minimalPresque aucun raisonnement, visant la réponse la plus rapide1024
lowQuestions-réponses simples et petites modifications4096
moyenChoix par défaut pour les tâches de codage quotidiennes10240
élevéRefactorisation complexe et résolution de problèmes difficiles32768

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 configurationTypeValeur par défautDescription
themestring"dark"Nom du thème
externalEditorstringSélectionné automatiquement en fonction du systèmeCommande de l'éditeur externe ouverte avec Ctrl+G
quietStartupbooléenfalseMasquer les informations d'en-tête au démarrage
collapseChangelogbooléenfalseIndique s'il faut afficher un journal des modifications replié après les mises à jour
editorPaddingXnombre0Marge horizontale de l'éditeur (0-3)
outputPadnombre1Marge intérieure horizontale de la zone de messages (0 ou 1)
autocompleteMaxVisiblenombre5Nombre 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 configurationTypeValeur par défautDescription
httpProxystring-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 configurationTypeValeur par défautDescription
compaction.enabledbooléenvraiActiver la compression automatique
compaction.reserveTokensnombre16384Tokens réservés pour la réponse du LLM
compaction.keepRecentTokensnombre20000Nombre 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 configurationTypeValeur par défautDescription
retry.enabledbooléenvraiActiver le réessai automatique
retry.maxRetriesnombre3Nombre maximal de tentatives
retry.baseDelayMsnombre2000Délai de nouvelle tentative de base (millisecondes), backoff exponentiel : 2s, 4s, 8s
retry.provider.timeoutMsnombreValeur par défaut du SDKDélai d'expiration de la requête (millisecondes)
retry.provider.maxRetriesnombre0Nombre 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 configurationTypeValeur par défautDescription
steeringModestring"one-at-a-time"Stratégie d'envoi des messages de pilotage : "all" ou "one-at-a-time"
followUpModestring"one-at-a-time"Stratégie d'envoi des messages de suivi
transportstring"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 configurationTypeValeur par défautDescription
terminal.showImagesbooléenvraiAfficher les images dans le terminal
terminal.imageWidthCellsnombre60Largeur de l'image en ligne (cellules du terminal)
images.autoResizebooléenvraiRéduire les images pour qu'elles tiennent dans 2000x2000
images.blockImagesbooléenfalseBloquer 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 configurationTypeValeur par défautDescription
shellPathstring-Chemin personnalisé du shell
shellCommandPrefixstring-Préfixe pour chaque commande bash
npmCommandstring[]-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 configurationTypeValeur par défautDescription
enabledModelsstring[]-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