Installation de Pi et configuration d’OmniProxy

Pi est un petit assistant de terminal, c’est-à-dire un programme avec lequel vous dialoguez directement en ligne de commande et qui peut lire des fichiers et accomplir des tâches. Son invite système est courte et ses outils par défaut sont peu nombreux. Si vous avez besoin d’autres commandes, processus ou interfaces, vous pouvez les ajouter au moyen d’extensions. Une extension est un composant qui ajoute des capacités à Pi et qui peut ensuite être partagé avec d’autres personnes.

Un sous-agent permet de confier une partie d’une tâche à un autre assistant, tandis que le mode planification consiste à organiser les étapes avant de commencer l’exécution. Ces deux fonctions ne sont pas incluses par défaut : vous pouvez demander à Pi de les créer ou installer un paquet partagé par quelqu’un d’autre.

Préparation avant l’installation

Sous macOS et Linux, utilisez le script d’installation, c’est-à-dire une commande qui télécharge et installe automatiquement le programme. Sous Windows, utilisez la commande PowerShell proposée sur la page d’accueil de Pi. PowerShell est l’environnement de ligne de commande intégré à Windows. Vous pouvez également installer Pi dans WSL, l’environnement Linux de Windows.

Si vous choisissez l’installation avec npm, vous devez d’abord disposer de Node.js 22.19 ou d’une version plus récente. npm est le gestionnaire de paquets utilisé avec Node.js et permet d’installer Pi depuis la ligne de commande.

macOS et Linux

install.sh

• Utiliser curl avec le script officiel
• Les dépendances sont verrouillées par le programme d’installation
• Utiliser pi update pour les mises à jour

Windows

install.ps1

• Utiliser la commande PowerShell du site officiel
• Git for Windows fournit Bash
• WSL peut également être utilisé

Node est déjà installé

npm

• Node 22.19+ est requis
• Le paquet s’appelle pi-coding-agent
• Ajouter --ignore-scripts

Installation et premier lancement

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

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

Sous Windows, ouvrez PowerShell, puis exécutez :

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

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

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

Dans un terminal interactif, le script d’installation peut s’interrompre pour poser des questions. Suivez alors les indications affichées. Si une version compatible de Node est déjà installée, cette commande npm ne pose aucune question. Pour installer Pi dans un autre répertoire, ajoutez --prefix /votre/répertoire. Le 2026-10-09, cette méthode a installé Pi 1.1.0.

Une installation npm normale n’a pas besoin des scripts de cycle de vie des dépendances, c’est-à-dire des scripts exécutés automatiquement par les paquets pendant l’installation. Le script d’installation verrouille les dépendances ; utilisez ensuite pi update pour effectuer les mises à jour. Pour une installation npm, la méthode de mise à jour dépend du gestionnaire de paquets utilisé. Les utilisateurs de Nix doivent installer Pi depuis son flake. Un flake est une configuration utilisée par Nix pour décrire un logiciel et ses dépendances ; pi update ne peut pas mettre à jour une installation Nix.

Une fois l’installation terminée, vérifiez d’abord que le terminal trouve Pi :

pi --version

Sous Windows, si vous souhaitez que le modèle exécute des commandes Bash, il est recommandé à la plupart des utilisateurs locaux d’installer Git for Windows. Bash est l’environnement de commande utilisé par Pi pour exécuter certaines commandes. Pi recherche successivement shellPath dans ~/.pi/agent/settings.json, Git Bash dans Program Files, puis bash.exe dans le PATH. shellPath indique l’emplacement de Bash, tandis que le PATH est la liste des répertoires dans lesquels le système recherche les commandes.

Après le lancement, vous pouvez saisir !printf 'Bash is working\n' pour effectuer une vérification. Si vos fichiers et vos outils se trouvent déjà dans WSL, installez Pi dans cet environnement Linux en suivant le Quickstart.

Accédez ensuite au dossier que Pi devra examiner ou traiter, puis lancez-le :

cd /path/to/folder
pi

Ce dossier définit l’espace de travail actuel de Pi. Il sert à détecter les fichiers et la configuration, ainsi qu’à regrouper les sessions.

Obtention des paramètres de connexion depuis OmniProxy

Commencez par récupérer les trois éléments suivants dans OmniProxy :

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copiez l’identifiant complet depuis la liste actuelle des modèles OmniProxy

baseUrl est l’adresse de l’interface à laquelle Pi envoie ses requêtes ; elle doit se terminer par /v1. apiKey est la clé utilisée pour accéder à l’interface. Model ID est le nom du modèle à appeler et doit être copié intégralement depuis la liste actuelle des modèles OmniProxy.

Pour api, saisissez openai-completions, comme dans l’exemple d’interface compatible. Ce champ indique à Pi le format d’interface à utiliser pour envoyer les requêtes.

Copiez l’intégralité de l’ID du modèle, en conservant également les barres obliques de son nom. Le 2026-10-09, les deux ID de référence figurant dans la documentation des fournisseurs étaient gemini-3.8-flash et grok-4.7. Ne recopiez pas un nom qui ne figure pas dans la liste.

Saisie de la configuration de l’outil

La configuration des modèles personnalisés de Pi au niveau utilisateur se trouve dans models.json. Ce fichier est placé dans le répertoire de l’agent, qui est par défaut ~/.pi/agent. Son chemin complet est donc ~/.pi/agent/models.json. Si la variable d’environnement PI_CODING_AGENT_DIR est définie, Pi utilise le répertoire indiqué par cette variable. Une variable d’environnement est une valeur de configuration fournie par le système et lisible par les programmes.

Remplissez le fichier en suivant l’exemple d’interface 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 répertorie les services connectés, tandis que models répertorie les modèles disponibles. Pour chaque modèle, id doit correspondre au Model ID complet figurant dans la liste actuelle d’OmniProxy. input indique ici que le modèle reçoit du texte.

Vous pouvez saisir directement la valeur de apiKey, ou utiliser $NAME ou ${NAME} afin que Pi la lise depuis une variable d’environnement. Une valeur commençant par ! est traitée comme une commande et exécutée à chaque requête. Ne validez jamais une clé réelle dans un dépôt. Si la passerelle ne vérifie pas la clé, vous pouvez saisir une chaîne de remplacement utilisée uniquement en local. Le 2026-10-09, Pi a correctement lu le fichier avec cette configuration.

L’ouverture de /model recharge ce fichier. /model est l’interface de Pi permettant d’afficher et de sélectionner les modèles. Les modèles personnalisés n’apparaissent pas dans /model tant que Pi ne peut pas analyser les identifiants d’accès. Après avoir sélectionné un modèle, appuyez sur Ctrl+S pour l’enregistrer comme modèle par défaut des nouvelles sessions.

Fichier

models.json

• Le répertoire par défaut est ~/.pi/agent
• Ajouter une entrée dans providers
• Définir api sur completions

Adresse

baseUrl

• Terminer par /v1
• apiKey peut contenir une variable
• L’id du modèle doit être exact

Sélection

/model

• Le fichier est rechargé à l’ouverture
• Sélectionner le modèle qui vient d’être ajouté
• Ctrl+S permet de l’enregistrer comme modèle par défaut

Vérification avec une tâche réelle

Une fois la configuration terminée, vous pouvez effectuer un test non interactif dans un répertoire contenant des fichiers. En mode non interactif, Pi n’ouvre pas de dialogue continu et se ferme après avoir terminé cette tâche. Remplacez la valeur après --model par l’ID complet figurant dans la liste actuelle d’OmniProxy :

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Lis la première ligne du fichier indiqué, sans modifier le fichier."

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

Vous pouvez également procéder de manière interactive : accédez au répertoire, exécutez pi, puis sélectionnez le modèle avec /model. L’un des exemples de tâche du Quickstart consiste à demander à Pi d’expliquer l’organisation du dépôt et la manière d’exécuter les vérifications. Vérifiez qu’il lit les fichiers et fournit une explication, puis consultez les journaux d’appels d’OmniProxy pour confirmer la source et l’ID du modèle.

Démarrage

pi se lance

• Utiliser d’abord cd pour accéder au 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

• Demander comment le dépôt est organisé
• Vérifier les fichiers qu’il énumère
• Ne pas se contenter de vérifier que la configuration est enregistrée

Journaux

La passerelle reçoit l’appel

• La source est Pi
• L’ID du modèle correspond
• La clé reste sur la machine locale

Erreurs courantes

• pi est introuvable : rouvrez le terminal, puis réessayez avec pi --version. Pour une installation npm, vérifiez que le répertoire global des exécutables se trouve dans le PATH.
• Le modèle personnalisé n’apparaît pas dans /model : vérifiez que models.json se trouve dans ~/.pi/agent/ et que apiKey peut être analysée, puis rouvrez /model.
• Windows indique que Bash est introuvable : installez Git for Windows ou définissez shellPath dans ~/.pi/agent/settings.json. Dans un fichier JSON, chaque barre oblique inverse doit être doublée.
• La requête est refusée : vérifiez que api vaut openai-completions et que baseUrl se termine par /v1. N’activez pas d’option de compatibilité supplémentaire uniquement parce que le service se présente comme compatible.
• L’ID du modèle n’est pas valide : recopiez-le depuis la liste actuelle d’OmniProxy.

Références officielles

Les commandes d’installation sont disponibles sur le site de Pi et dans le Quickstart. Pour le fichier des modèles, consultez Choose a Model et Configuration. Pour l’environnement de commande sous Windows, consultez Run Pi on Windows. Les ID de modèles utilisés dans les exemples figurent dans la liste des modèles Gemini et sur 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 ↗