Configuration des modèles de Pi Coding Agent : /login, models.json et fournisseurs personnalisés

La configuration des modèles de l’agent de programmation Pi comporte trois niveaux : pour les fournisseurs intégrés, connectez-vous avec /login (abonnement ou clé API) ou définissez une variable d’environnement ; pour les points de terminaison compatibles avec les API OpenAI, Anthropic ou Google mais non intégrés à Pi, ajoutez-les dans ~/.pi/agent/models.json ; seuls les services nécessitant une authentification ou un protocole particulier nécessitent d’écrire une extension. Une fois le modèle choisi, utilisez /model pour passer à celui-ci. Cet article explique, conformément à la documentation de Pi après sa refonte du 22 septembre 2026 et au code source de v0.99.2 publié le 30 septembre 2026, comment configurer chaque niveau, l’ordre de lecture des clés (modifié après la refonte), les trois valeurs par défaut des modèles personnalisés qui provoquent des erreurs silencieuses et un exemple complet de connexion à un point de terminaison compatible OpenAI.

Commencez par vérifier de quel Pi il s’agit. Cette page concerne l’agent de code en terminal publié par la société Earendil sur pi.dev, dont le dépôt est earendil-works/pi (anciennement badlogic/pi-mono), sous licence MIT. Il ne s’agit ni du chatbot Pi d’Inflection (pi.ai), ni de la cryptomonnaie Pi Network, ni de Raspberry Pi, ni du Oh My Pi d’un autre auteur.

Choisissez d’abord le mode de connexion

La documentation des modèles de Pi commence par ce tableau de correspondance :

Pi intègre un catalogue de modèles et peut y superposer des données plus récentes provenant de pi.dev ; hors ligne, il utilise le cache. Pour forcer une mise à jour, exécutez pi update --models. Une configuration de modèle personnalisée n’est nécessaire que lorsque Pi ne propose pas le fournisseur ou le point de terminaison souhaité.

Sélectionner un modèle dans Pi

• /model : rechercher et sélectionner un modèle. Seuls les modèles des fournisseurs disposant déjà d’une authentification utilisable sont affichés.
• Appuyer sur Ctrl+S sur un modèle : l’enregistrer comme modèle par défaut des nouvelles sessions.
• /thinking : sélectionner le niveau de réflexion du modèle actuel. Pi n’affiche que les niveaux pris en charge par ce modèle ; appuyez de même sur Ctrl+S pour l’enregistrer comme valeur par défaut au démarrage.
• Ctrl+P : alterner entre les modèles disponibles ; /scoped-models contrôle et enregistre la liste de rotation.

La session enregistre les changements de modèle et de niveau de réflexion et les restaure lors de sa reprise, sans modifier les valeurs par défaut des nouvelles sessions.

Ordre de lecture des clés (modifié après la refonte)

Lorsque plusieurs sources de clés sont configurées, la documentation de Pi indique l’ordre suivant : --api-key fourni à l’exécution → identifiants enregistrés dans auth.json → apiKey dans models.json → variable d’environnement du fournisseur (ou identifiants d’environnement de la plateforme cloud). Une ancienne clé enregistrée avec /login remplace donc celle que vous venez d’écrire dans le fichier ; c’est la cause la plus fréquente de la situation où l’ancien compte est toujours utilisé malgré la modification de la configuration. /logout permet de supprimer les identifiants enregistrés. Attention : avant la refonte du 22 septembre, la documentation plaçait les variables d’environnement avant models.json ; les anciens tutoriels en ligne peuvent encore présenter cet ordre.

Autre malentendu fréquent : lorsqu’un modèle n’apparaît pas dans /model, il s’agit généralement d’un problème d’authentification, pas d’une erreur JSON. La documentation indique que les modèles personnalisés peuvent être chargés depuis models.json, mais ils restent « indisponibles » tant que Pi n’a pas résolu les identifiants.

models.json : exemple complet pour connecter un point de terminaison compatible OpenAI

L’exemple de Pi utilise Ollama en local — la clé factice sert uniquement à rendre le modèle disponible ; Ollama lui-même ne la vérifie pas :

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

Pour connecter un point de terminaison nécessitant une authentification, comme Kunavo, procédez ainsi :

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

• baseUrl et api sont obligatoires. Ils peuvent être définis au niveau du fournisseur ou du modèle ; selon le code source de v0.99.2, si l’un des deux manque, Pi ne charge pas le modèle.
• api ne correspond pas à un choix parmi quatre. Avant la refonte du 22 septembre, la documentation de Pi listait quatre valeurs pour les fournisseurs personnalisés : openai-completions, openai-responses, anthropic-messages, google-generative-ai. Après la refonte, elle ne fournit plus de liste et indique seulement dans le tableau ci-dessus « point de terminaison compatible avec OpenAI, Anthropic ou Google » ; l’exemple n’utilise que openai-completions. Le code source de v0.99.2 définit api comme une chaîne arbitraire et la transmet à l’implémentation intégrée correspondante parmi dix — les quatre précédentes, plus openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream, pi-messages. Seules les quatre premières ont été documentées comme usages de fournisseurs personnalisés ; les six autres n’ont pas été testées ici et cette page ne prétend pas qu’elles permettent de connecter des points de terminaison tiers.
• openai-completions de baseUrl doit inclure /v1. La documentation ne l’impose pas en une phrase, mais tous les exemples de points de terminaison compatibles comportent un chemin de version. Sans /v1, vous obtiendrez une 404 et non une erreur d’authentification.
• Ne codez pas la clé en dur.apiKey et les valeurs d’en-tête peuvent référencer une variable d’environnement avec $NAME ou ${NAME}, contenir une valeur directe, ou utiliser !指令 pour l’obtenir ; la documentation précise que la commande dans models.json est exécutée à chaque requête et n’est pas mise en cache. Gardez auth.json et toute commande qui récupère une clé confidentiels.
• Il n’est pas nécessaire de redémarrer après la modification. Le fichier est relu lors de l’ouverture de /model. Dans models, une entrée portant le même ID ajoute ou remplace le modèle de ce fournisseur ; pour modifier les métadonnées d’un modèle intégré sans remplacer toute la liste, utilisez modelOverrides.

Trois valeurs par défaut qui provoquent des erreurs silencieuses

La refonte documentaire du 22 septembre a supprimé le tableau des champs, mais les valeurs par défaut figurent toujours dans le code source (v0.99.2, provider-composer.ts). Si elles ne sont pas renseignées, les modèles personnalisés utilisent :

Par ailleurs, reasoning vaut false par défaut et input ne prend en charge que le texte par défaut. L’exemple Kunavo ci-dessus renseigne le contexte et la limite de sortie selon la grille tarifaire, mais n’inclut pas cost, car inscrire les prix en dur dans le fichier les rendrait rapidement obsolètes. Pour afficher les coûts en bas, renseignez vous-même les prix par million de tokens selon la grille tarifaire. Pi prend également en charge promptCache (déclarer en secondes la durée de vie du cache du fournisseur, pour le préchauffage du cache) ; la documentation recommande une valeur prudente dans la plage publique.

anthropic-messages : compatible, mais baseUrl reste indéterminé

anthropic-messages est l’une des quatre valeurs que la documentation avant sa révision indiquait pour un fournisseur personnalisé. Kunavo propose également une interface Anthropic Messages : la voie api: "anthropic-messages" existe donc bien. Mais la documentation de Pi n’a jamais précisé clairement si, pour ce type, baseUrl devait inclure /v1 : avant la révision, un exemple indiquait https://proxy.example.com/v1 et un autre indiquait https://proxy.example.com sans chemin. Après la révision, les deux exemples ont été supprimés, sans que la question soit tranchée. Si vous choisissez cette voie, essayez d’abord l’une des deux variantes ; si la première requête renvoie 404 (et non 401), modifiez cette ligne. compat contient aussi quelques options conçues spécifiquement pour les points de terminaison tiers (par exemple supportsEagerToolInputStreaming et supportsStrictTools), mais la documentation rappelle que les paramètres de compatibilité doivent décrire des « différences de comportement vérifiées » : ne les activez pas simplement parce qu’un point de terminaison se déclare compatible avec OpenAI ou Anthropic. L’exemple openai-completions ci-dessus évite ces problèmes : c’est la véritable raison pour laquelle il est recommandé de commencer par cet exemple, et non parce qu’il serait plus rapide.

Transparence et paiement

Les références de configuration ci-dessus sont issues de la documentation et du code source de Pi. Kunavo n’a pas exécuté Pi avec son propre point de terminaison : nous n’avons pas exécuté de session, de streaming ou d’allers-retours d’outils, ni vérifié sur quel modèle la requête aboutit finalement. Conservez la voie qui fonctionne actuellement et donnez à Pi une tâche qui lit et écrit de vrais fichiers ; Pi s’appuie presque à chaque étape sur des appels d’outils, ce qui rend ce premier essai particulièrement révélateur des problèmes de format du streaming ou des outils. La page complète de configuration en anglais est le guide d’intégration Pi ; les différentes options payantes, dont la passerelle Radius d’Earendil, sont comparées dans Tarifs de l’agent de code Pi.

Kunavo fonctionne en prépaiement, avec une facturation au token et sans abonnement mensuel. Le rechargement minimum est de $10 ; le paiement passe par Stripe, avec les cartes disponibles à Taïwan (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay et Link. JKO Pay et LINE Pay ne figurent pas dans la liste des moyens acceptés. Voir les informations de facturation, puis créer un compte et générer une clé.

Questions fréquentes

Vérifié le 1er octobre 2026 : les pages pi.dev/docs/latest/models (Choose a Model) et providers, les fichiers src/core/model-config.ts et provider-composer.ts du dépôt earendil-works/pi au tag v0.99.2, ainsi que les informations de version de l’API GitHub. Le champ api a également fait l’objet de vérifications supplémentaires le même jour : les valeurs actuellement listées sur la page models (uniquement openai-completions, dans l’exemple Ollama), le type de api dans model-config.ts de v0.99.2 (chaîne arbitraire, lignes 191 et 233), l’aiguillage des modèles personnalisés dans provider-composer.ts (ligne 579) et BUILTIN_APIS dans packages/ai/src/compat.ts (ligne 180, dix types au total). Kunavo n’a pas testé son propre point de terminaison en l’utilisant réellement avec Pi.