Installation de Pi et configuration d'OmniProxy

Pi est un petit assistant de terminal — un programme qui discute avec vous directement dans la ligne de commande, lit des fichiers et termine des tâches. Il a une courte invite système et seulement quelques outils par défaut. Si vous avez besoin d’autres commandes, flux de travail ou interfaces, vous pouvez les ajouter plus tard via des extensions. Les extensions sont des composants qui ajoutent des capacités à Pi, et vous pouvez les partager avec d’autres après les avoir créées.

Les sous-agents délèguent une partie d’une tâche à un autre assistant, tandis que le mode plan organise les étapes avant que l’exécution ne commence. Aucune de ces fonctionnalités n’est incluse par défaut, mais vous pouvez demander à Pi de les construire ou d’installer des paquets partagés par d’autres.

Avant de commencer

macOS et Linux utilisent un script d’installation — une commande unique qui télécharge et installe automatiquement Pi. Sur Windows, utilisez la commande PowerShell fournie sur la page d’accueil de Pi. PowerShell est l’environnement de ligne de commande inclus avec Windows. Vous pouvez également installer Pi dans WSL, l’environnement Linux disponible au sein de Windows.

Si vous choisissez d’installer avec npm, vous avez besoin de Node.js 22.19 ou une version ultérieure. npm est le gestionnaire de paquets utilisé avec Node.js et peut installer Pi depuis la ligne de commande.

macOS Linux

install.sh

curl le script officiel
L'installateur épingle les dépendances
Mise à jour avec pi update

Windows

install.ps1

Commande PowerShell officielle
Git for Windows fournit Bash
Vous pouvez également utiliser WSL

Node déjà installé

npm

Nécessite Node 22.19+
Le nom du paquet est pi-coding-agent
Ajoutez --ignore-scripts

Le script d'installation épingle les dépendances. L'installation npm n'épingle pas les dépendances transitives et nécessite --ignore-scripts.

Installation et lancement de Pi pour la première fois

Sur macOS ou Linux, ouvrez un terminal et exécutez :

curl -fsSL https://pi.dev/install.sh | sh

Sur Windows, ouvrez PowerShell et exécutez :

powershell -c "irm https://pi.dev/install.ps1 | iex"

Si Node.js 22.19 ou une version ultérieure est déjà installé, vous pouvez également utiliser la commande alternative du Quickstart :

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Le script d’installation peut faire une pause pour poser des questions dans un terminal interactif. Suivez les invites à l’écran pour continuer. Si vous avez déjà une version compatible de Node, cette commande npm ne posera pas de questions. Pour installer Pi dans un autre répertoire, ajoutez --prefix /your/directory. Le 09/10/2026, cela a installé Pi 1.1.0.

Une installation npm normale ne nécessite pas de scripts de cycle de vie de dépendance, qui sont des scripts que les paquets exécutent automatiquement lors de l’installation. Le script d’installation épingle les dépendances ; ensuite, mettez à jour Pi avec pi update. Pour une installation npm, utilisez la méthode de mise à jour fournie par votre gestionnaire de paquets. Les utilisateurs de Nix doivent installer à partir du flake de Pi. Un flake est une configuration Nix qui décrit le logiciel et ses dépendances, et pi update ne peut pas mettre à jour une installation Nix.

Après l’installation, confirmez d’abord que votre terminal peut trouver Pi :

pi --version

Sur Windows, si vous voulez que les modèles exécutent des commandes Bash, l’installation de Git for Windows est recommandée pour la plupart des utilisateurs locaux. Bash est l’environnement de commande que Pi utilise pour exécuter certaines commandes. Pi vérifie le shellPath paramètre dans ~/.pi/agent/settings.json, Git Bash sous Program Files, puis bash.exe sur PATH, dans cet ordre. shellPath spécifie l’emplacement de Bash, tandis que PATH est la liste des répertoires que le système recherche pour les commandes.

Après avoir démarré Pi, vous pouvez entrer !printf 'Bash is working\n' pour le vérifier. Si vos fichiers et outils sont déjà dans WSL, installez Pi dans cet environnement Linux en suivant le Quickstart.

Ensuite, entrez dans le dossier que vous voulez que Pi inspecte ou sur lequel il travaille, puis démarrez-le :

cd /path/to/folder
pi

Ce dossier devient la portée de travail actuelle de Pi. Pi l’utilise pour découvrir les fichiers et la configuration et pour regrouper les sessions.

Obtenir les valeurs de connexion depuis OmniProxy

Obtenez d’abord ces trois valeurs depuis OmniProxy :

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy the full ID from the current OmniProxy model list

baseUrl est le point de terminaison API auquel Pi envoie des requêtes, et il doit inclure /v1. apiKey est la clé utilisée pour accéder à l’API. Model ID est le nom du modèle à appeler et doit être copié en entier depuis la liste actuelle des modèles OmniProxy.

Définissez api sur openai-completions, comme indiqué dans l’exemple d’API compatible. Ce champ indique à Pi quel format d’API utiliser lors de l’envoi de requêtes.

Copiez l’ID complet du modèle, y compris les barres obliques dans le nom. Le 09/10/2026, les deux ID de référence dans la documentation du fournisseur étaient gemini-3.8-flash et grok-4.7. Ne copiez pas un nom qui n’est pas présent dans la liste.

Saisir la configuration de l’outil

La configuration du modèle personnalisé au niveau de l’utilisateur de Pi est stockée dans models.json. Ce fichier est situé dans le répertoire de l’agent, qui est par défaut ~/.pi/agent, donc son chemin complet est ~/.pi/agent/models.json. Si la variable d’environnement PI_CODING_AGENT_DIR est définie, Pi utilise le répertoire spécifié par cette variable à la place. Une variable d’environnement est une valeur de configuration fournie par le système pour que les programmes puissent la lire.

Entrez la configuration comme indiqué dans l’exemple d’API compatible :

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers liste les services connectés, tandis que models liste les modèles qui peuvent être sélectionnés. Chaque id du modèle doit correspondre à l’ID complet du modèle dans la liste actuelle des modèles OmniProxy. input indique que le modèle est configuré ici pour l’entrée de texte.

apiKey peut être saisi comme une valeur littérale, ou comme $NAME ou ${NAME} pour que Pi le lise à partir d’une variable d’environnement. Une valeur commençant par ! est traitée comme une commande et exécutée pour chaque requête. Ne validez pas une vraie clé dans un dépôt. Si la passerelle ne valide pas les clés, vous pouvez entrer une chaîne de caractères générique utilisée uniquement sur votre machine locale. Le 09/10/2026, Pi a lu avec succès le fichier avec cette configuration.

Ouvrir /model recharge ce fichier. /model est l’interface dans Pi pour visualiser et sélectionner les modèles. Les modèles personnalisés n’apparaissent pas dans /model tant que Pi ne peut pas résoudre leurs justificatifs. Après avoir sélectionné un modèle, appuyez sur Ctrl+S pour l’enregistrer comme modèle par défaut pour les nouvelles sessions.

Fichier

models.json

Répertoire par défaut : ~/.pi/agent
Ajoutez une entrée sous providers
Définir api sur completions

Adresse

baseUrl

Inclure /v1
apiKey peut référencer une variable
L'id du modèle doit être exact

Sélectionner

/model

L'ouvrir recharge le fichier
Sélectionnez le modèle que vous venez d'ajouter
Ctrl+S l'enregistre comme défaut

Après avoir modifié le fichier, ouvrez /model dans Pi et confirmez que les modèles apparaissent.

Vérifier avec une tâche réelle

Après avoir terminé la configuration, vous pouvez effectuer une vérification non interactive dans un répertoire contenant des fichiers. Le mode non interactif signifie que Pi termine cette tâche unique puis quitte au lieu d’entrer dans une conversation continue. Remplacez la valeur après --model par l’ID complet de la liste actuelle d’OmniProxy :

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Read the first line of the file you specify. Do not modify the file."

Ici, --tools read active uniquement l’outil de lecture, et la tâche demande également explicitement à Pi de ne pas modifier le fichier. Le 09/10/2026, Pi 1.1.0 a lu le contenu du fichier avec succès. La première réponse a pris environ deux minutes.

Vous pouvez également utiliser le mode interactif : entrez dans le répertoire, exécutez pi, puis sélectionnez un modèle avec /model. Un exemple de tâche dans le Quickstart demande à Pi d’expliquer comment le dépôt est organisé et comment exécuter ses vérifications. Observez s’il lit les fichiers et fournit une explication, puis confirmez la source et l’ID du modèle dans les journaux de requêtes d’OmniProxy.

Lancement

pi se lance

D'abord cd vers le dossier
pi --version produit une sortie
Le nom du modèle apparaît en bas de l'interface

Tâche

Il a lu le répertoire

Demandez comment le dépôt est organisé
Examinez les fichiers qu'il liste
Ne vous fiez pas uniquement à un enregistrement de configuration réussi

Journaux

Visible dans la passerelle

La source est Pi
L'ID du modèle correspond
Gardez la clé sur la machine locale

Une fois que le nom du modèle apparaît en bas de l'interface, effectuez également une tâche réelle.

Erreurs courantes

pi ne peut pas être trouvé : Rouvrez le terminal et réessayez pi --version à nouveau. Pour une installation npm, confirmez que le répertoire bin global est sur PATH.
Les modèles personnalisés n’apparaissent pas dans /model: Confirmez que models.json est dans ~/.pi/agent/, vérifiez que apiKey peut être résolu, puis rouvrez /model.
Windows signale que Bash ne peut pas être trouvé : Installez Git for Windows, ou définissez shellPath dans ~/.pi/agent/settings.json. Les barres obliques inverses dans JSON doivent être écrites deux fois.
La requête est rejetée : Vérifiez que api est openai-completions et que baseUrl se termine par /v1. N’activez pas d’options de compatibilité supplémentaires simplement parce que le service se décrit comme compatible.
L’ID du modèle est invalide : Copiez-le à nouveau depuis la liste actuelle d’OmniProxy.

Références officielles

Pour les commandes d’installation, voir le site web de Pi et le Quickstart. Pour le fichier de modèle, voir Choose a Model et Configuration. Pour l’environnement de commande Windows, voir Run Pi on Windows. Pour les ID de modèle utilisés dans les exemples, voir la Gemini model list et la page des modèles xAI.

Remplacez chaque espace réservé par des valeurs de votre propre configuration OmniProxy. Ne publiez jamais une vraie clé.

Un résultat sauvegardé ou un HTTP 200 seul ne prouve pas une compatibilité complète de l'Agent. Vérifiez la source et le modèle dans l'enregistrement d'appel d'OmniProxy.

Sources officielles · Pi ↗