Tutoriel pas à pas : une seule clé pour connecter tous les agents et unifier l’accès aux API avec la passerelle API open source magpie (exemples avec Claude Code, Codex, Pi et Hermes)

Note de l’auteur : voici un tutoriel que vous pouvez suivre pas à pas jusqu’au bout. En le lisant et en le mettant en pratique, vous obtiendrez une configuration où « une clé, une adresse de passerelle, autant d’agents que vous en avez installés » suffisent. Par la suite, changer de modèle ou renouveler une clé ne nécessitera de modifier qu’un seul endroit.

Avant de commencer, voyons ce que vous allez faire

• Objectif : faire en sorte que tous les agents de programmation de votre machine utilisent la même clé API et la même adresse en amont. Ce tutoriel prend pour exemple Claude Code, Codex, Pi et Hermes : connectez-en autant que vous en avez installés.
• Durée : environ 30 minutes, sans compter l’inscription ni le téléchargement des ressources.
• Prérequis : un jeton APIYI (ou toute clé officielle ou de service proxy compatible avec OpenAI ou Anthropic), un ordinateur capable d’exécuter des commandes et au moins un agent installé.
• Difficulté : ★★☆☆☆. Il suffit de savoir cliquer quelques fois et copier-coller : vous n’aurez aucune commande à saisir.

Feuille de route du tutoriel

Comprendre en trois minutes ce que magpie fait en coulisses

Si vous voulez simplement « suivre les étapes », vous pouvez passer cette section. Mais prenez trois minutes pour la lire : vous gagnerez du temps lors du dépannage.

Les exigences vis-à-vis du modèle en amont varient beaucoup d’un agent à l’autre. Tout configurer à la main signifie qu’il faut maintenir plusieurs configurations dès qu’on installe quelques outils. Voici quatre des agents les plus courants :

magpie (dépôt github.com/yetone/magpie, slogan « Every agent’s model. One place. ») s’occupe précisément de ça : il centralise dans une même interface le choix du modèle utilisé par chaque agent et de la clé qu’il doit lire, puis modifie les configurations natives de chaque outil.

En bref, les rôles sont répartis ainsi :

• magpie gère la distribution : il détermine quel modèle utiliser avec Claude Code, Codex, etc.
• La passerelle gère les protocoles : elle transmet les requêtes au véritable fournisseur de modèles en convertissant les formats Anthropic, OpenAI ou Gemini.

Votre passerelle en amont devrait donc prendre en charge plusieurs protocoles

L’idéal, c’est que « magpie gère la distribution et la passerelle gère les protocoles ». Si la passerelle ne prend en charge que le format compatible avec OpenAI, il faudra ajouter une couche de conversion de protocole pour Claude Code. Le parcours sera plus long et les formats d’appel des outils risquent davantage de ne pas correspondre.

La solution d’APIYI repose sur un seul jeton compatible avec trois grands protocoles : OpenAI compatible, Anthropic natif et format Gemini peuvent tous être utilisés avec la même clé. (Pour connaître les détails de la prise en charge, consultez les informations de la console.) magpie n’a ainsi besoin que d’une seule connexion en amont pour que tous les agents puissent se connecter, sans gérer séparément les comptes et les factures des fournisseurs.

Comment choisir entre les trois méthodes ?

La configuration manuelle est la méthode la plus directe. Mais avec plusieurs outils, les clés se retrouvent dispersées dans une série de fichiers, ce qui augmente nettement le coût de leur rotation et du dépannage. Un script de variables d’environnement ne nécessite aucune dépendance et tient en quelques dizaines de lignes, mais il ne permet pas d’attribuer un modèle différent à chaque agent. Pour répondre facilement à un besoin comme « Claude Code utilise Claude, Codex utilise GPT et Hermes utilise un modèle moins coûteux », une solution de gestion centralisée comme magpie est la plus adaptée.

Étape 1 : récupérez une clé et copiez-la

1.1 Créez un jeton dans la console APIYI

Rendez-vous dans la console APIYI (apiyi.com) pour créer un jeton, puis copiez-le.

Vous n’avez aucune commande à saisir à cette étape. Pendant tout le processus, cette clé API ne sera utilisée qu’une seule fois : vous la collerez dans le panneau « Fournisseur » de magpie (étape 3). Une fois collée, magpie créera automatiquement les fichiers de configuration de chaque agent. Vous n’aurez pas besoin d’utiliser export pour définir une variable d’environnement ni de modifier des fichiers comme config.toml ou settings.json.

🚀 Vous n’avez pas encore de jeton ? Vous pouvez d’abord vous inscrire sur APIYI, sur apiyi.com, et obtenir un crédit d’essai. Avec un seul jeton, faites fonctionner les outils que vous utilisez régulièrement, puis décidez quels modèles vous souhaitez conserver à long terme.

1.2 Gardez ces deux adresses à portée de main

À l’étape 3, vous devrez choisir l’adresse à renseigner lors de la configuration du fournisseur :

✅ Vérification : le jeton est dans votre presse-papiers et vous savez quelle adresse renseigner à l’étape 3.

Étape 2 : installez magpie et repérez ces deux pages

Pour le code source de magpie, son installation et son format de configuration, référez-vous au README du dépôt officiel (github.com/yetone/magpie). Le projet évolue rapidement : les commandes d’installation et les noms de champs peuvent changer selon les versions. En revanche, les captures d’écran et l’ordre des opérations présentés ci-dessous restent valables.

Après l’installation et le démarrage, une fenêtre avec une barre de navigation à gauche s’affiche. Ce tutoriel utilise seulement deux pages : Agent (qui utilise quel modèle) et Fournisseur (où associer la clé API).

① Dans la navigation de gauche, la page Agent est le panneau de contrôle central de tous vos agents :

Figure 1 · Page Agent : une ligne par outil, un interrupteur à droite pour activer son intégration à magpie, puis un menu déroulant pour choisir le modèle

Sur cette page, repérez ces trois éléments :

② Dans la navigation de gauche, la page Fournisseur permet d’associer la clé API du fournisseur en amont. Nous verrons cela en détail dans la section suivante.

Si vous souhaitez d’abord comprendre la structure des fichiers de configuration de magpie, vous pouvez jeter un œil aux sections providers et agents du README officiel. En résumé, il s’agit de donner un nom au fournisseur en amont, de renseigner son base_url et sa clé API, puis d’attribuer un modèle à chaque agent. Mais pour une utilisation courante, tout se fait dans l’interface : magpie s’occupe d’écrire la configuration native de chaque outil, ce qui est bien plus fiable que de modifier les fichiers YAML à la main.

✅ Vérification : la fenêtre s’ouvre et les options Agent et Fournisseur apparaissent dans la navigation de gauche.

Étape 3 : ajoutez votre clé dans « Fournisseurs »

3.1 Accéder à la page des fournisseurs

Cliquez sur Fournisseurs dans la barre latérale de gauche (① encadré en rouge dans la figure 2), puis, une fois sur la page, cliquez sur + Ajouter un fournisseur en haut à droite (② encadré en rouge) :

Figure 2 · Page des fournisseurs : accédez à « Fournisseurs » dans la barre latérale, puis cliquez sur « + Ajouter un fournisseur » en haut à droite. C’est la seule façon d’ajouter un fournisseur.

Les fournisseurs déjà ajoutés sont répertoriés ici sous forme de cartes. La deuxième ligne de chaque carte affiche son adresse et le nombre de modèles disponibles (par exemple, api.apiyi.com · 11 modèles). Pour vérifier si le fournisseur est opérationnel, regardez d’abord si cette ligne indique un nombre.

3.2 Quel type de fournisseur choisir ?

Cliquez sur « + Ajouter un fournisseur » pour afficher un panneau de sélection organisé en plusieurs groupes (figure 3) :

Figure 3 · Panneau d’ajout de fournisseur : les cinq types de sources — abonnement, fournisseur, proxy, local et magpie sur un autre ordinateur

Les groupes du panneau correspondent à cinq types de clés différents :

Avec APIYI, son point de terminaison compatible avec OpenAI correspond au type de proxy standard : choisissez l’entrée correspondante dans le groupe Proxy. Si vous avez une clé OpenAI ou Anthropic compatible personnalisée, cliquez directement sur + Fournisseur personnalisé, tout en bas (encadré en rouge dans la figure 3), puis renseignez l’adresse et la clé. Saisissez https://api.apiyi.com/v1 comme adresse (pour les requêtes natives Anthropic, saisissez plutôt https://api.apiyi.com).

Voici le panneau de configuration complet d’un fournisseur. Seules quatre lignes vous concernent :

Figure 4 · Page de configuration du fournisseur APIYI : choisissez d’abord le protocole, puis saisissez l’adresse dans Base URL ; ajoutez votre clé dans Accounts et sélectionnez dans Models les modèles à mettre à la disposition des agents.

Cette capture illustre concrètement le principe « un jeton, plusieurs protocoles » évoqué plus haut : l’adresse reste https://api.apiyi.com. Choisissez Anthropic compatible pour obtenir le point de terminaison natif utilisé par Claude Code, OpenAI compatible pour le point de terminaison /v1 utilisé par Codex / Pi / Hermes, ou Gemini compatible pour Gemini. Vous n’avez donc pas besoin de gérer trois fournisseurs et trois clés API.

Après avoir renseigné les champs et enregistré, retournez à la liste des fournisseurs et vérifiez deux choses : le nombre de modèles apparaît sur la deuxième ligne de la carte et l’interrupteur est activé. Si vous voyez · N modèles, cela signifie que la clé et l’adresse fonctionnent. Cette étape sert aussi de vérification : pas besoin d’exécuter une commande supplémentaire.

✅ Vérification de l’étape : votre carte apparaît dans la liste des fournisseurs avec un affichage du type · N modèles, et non « Non configuré ».

Étape 4 : connectez un à un les agents installés

Retournez dans la page Agent et effectuez les trois mêmes actions pour chaque outil que vous avez installé. Cette page répertorie tous les agents que magpie peut connecter (la liste s’allonge régulièrement ; ceux qui ne sont pas installés affichent « CLI introuvable »). Connectez uniquement ceux que vous avez installés. Le tableau ci-dessous présente les quatre plus courants :

1. Activez l’interrupteur à droite (il passe du gris à la couleur).
2. Choisissez un modèle à droite de l’interrupteur (si vous n’en choisissez pas, le modèle par défaut sera utilisé ; le modèle sélectionné sera ajouté à la configuration de l’outil).
3. Redémarrez l’outil lorsque vous y êtes invité (Codex, Claude Code, Pi et Hermes nécessitent généralement un redémarrage du processus pour prendre en compte la nouvelle configuration).

Figure 5 · Ouvrez la liste déroulante des modèles : la première option, « Par défaut », permet à l’agent d’utiliser son propre modèle, sans passer par magpie. Chaque option en dessous porte la mention « Via magpie » : le modèle sélectionné sera celui du fournisseur en amont.

Voici quelques états courants qui indiquent que tout se passe comme prévu :

• Connecté : la configuration est en place ; elle prendra effet au redémarrage de l’outil.
• Non connecté · utilise les paramètres de XXX : l’interrupteur n’est pas activé ou aucun modèle n’a été sélectionné.
• Ne peut utiliser que les modèles de XXX ; connexion à magpie impossible : cet outil (Cursor, par exemple) n’autorise que ses propres modèles. C’est une limite de conception, pas une erreur de configuration.
• CLI introuvable : l’outil n’est pas installé ou ne se trouve pas dans le PATH. Installez-le ou ajoutez-le au PATH, puis réessayez.

💡 Pour attribuer des modèles différents à différents agents (Claude à Claude Code, GPT à Codex et un modèle économique à Hermes), sélectionnez-les séparément à cette étape. C’est aussi le principal avantage de magpie par rapport aux scripts utilisant des variables d’environnement.

✅ Vérification de l’étape : les interrupteurs de tous les outils installés sont activés et leur statut n’indique plus « Non connecté ».

Étape 5 : vérifier chaque agent avec une phrase

La configuration n’est terminée que lorsque tout fonctionne. Dans chaque outil, envoyez une tâche toute simple :

Pour vérifier que les requêtes passent bien par la passerelle, le plus simple est de consulter la console APIYI et les statistiques d’utilisation ou les journaux de ce jeton. Si de nouveaux appels apparaissent, c’est que les requêtes de tous les agents sont bien acheminées vers la même clé.

✅ Validation de cette étape : chaque agent répond correctement et les appels correspondants apparaissent dans la console.

Annexe : quel modèle choisir ? (la réponse par défaut en cas de doute)

💡 Conseil : effectuez la même tâche avec différents agents et modèles. Avec un jeton commun, il suffit de changer le nom du modèle pour comparer les résultats, et le coût de la comparaison reste faible.

Étape 6 (facultative) : quelles configurations magpie écrit-il exactement ?

Cette étape n’a aucune incidence sur le bon fonctionnement et n’est pas obligatoire. Au quotidien, vous n’avez pas besoin de toucher à ces fichiers : dès que vous avez activé l’option à l’étape 4, magpie a déjà écrit les éléments ci-dessous. Nous les présentons ici pour deux raisons : savoir où chercher en cas de problème et pouvoir les recopier directement si vous décidez un jour de ne plus utiliser magpie.

Claude Code : ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Point de terminaison natif d’Anthropic
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# Facultatif : définir le modèle par défaut (consultez la liste des modèles dans la console)
# export ANTHROPIC_MODEL="<nom du modèle Claude>"
claude

Vous pouvez aussi ajouter ces variables au champ env de ~/.claude/settings.json. Elles ne dépendront alors pas de la session du terminal.

Codex : la section provider de ~/.codex/config.toml

# ~/.codex/config.toml
model = "<nom d’un modèle GPT>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # Point de terminaison compatible avec OpenAI
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # Si le modèle sélectionné ne prend pas en charge Responses, remplacez par "chat"

wire_api est le piège le plus courant : les versions récentes de Codex utilisent Responses par défaut. Si, côté passerelle, le modèle ne prend en charge que Chat Completions, vous devez remplacer cette valeur par chat.

Pi et Hermes : déclarer un provider personnalisé compatible avec OpenAI

Le principe est le même : renseignez https://api.apiyi.com/v1 dans base_url et utilisez APIYI_API_KEY pour la clé. La structure varie selon les versions ; consultez la documentation officielle de chaque outil :

// Pi : déclarez le provider dans la configuration des modèles personnalisés (la structure dépend de la documentation officielle de Pi)
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<nom du modèle>" }]
    }
  }
}

# Hermes : lancez hermes model, puis sélectionnez un point de terminaison personnalisé compatible avec OpenAI.
# Saisissez les informations suivantes lorsque vous y êtes invité (ou ajoutez-les au fichier .env / à la configuration du répertoire Hermes)
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <nom du modèle>

#!/usr/bin/env bash
# agents-env.sh — solution de secours sans magpie : une seule clé pour tous les agents
# Utilisation : source agents-env.sh
: "${APIYI_API_KEY:?Veuillez d’abord définir APIYI_API_KEY avec export}"

# Claude Code (protocole Anthropic)
export ANTHROPIC_BASE_URL="https://api.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"

# Variables génériques pour les outils compatibles avec OpenAI, comme Codex, Pi et Hermes
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# Vérifier la connectivité
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ Tous les agents pointent vers la même passerelle"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-你的令牌" | head -c 300

En cas de problème : quatre erreurs fréquentes

Procédez toujours au diagnostic de bas en haut : vérifiez d’abord que la passerelle et la clé fonctionnent (la fiche du fournisseur affiche-t-elle · N modèles ?), puis contrôlez la configuration native de chaque agent, et enfin la couche de correspondance de magpie. Ces trois étapes suffisent à déterminer si le problème vient du service en amont, de l’outil lui-même ou de la configuration centralisée.

FAQ : questions fréquentes

Récapitulatif en cinq minutes

• Répartition des rôles : magpie gère la correspondance entre les modèles, la passerelle leur transmission selon les protocoles. Chacun s’occupe d’une seule tâche.
• Un seul jeton : choisissez un fournisseur amont compatible avec plusieurs protocoles pour que tous les agents partagent une seule clé et une seule facture.
• Ordre de configuration : créez un jeton dans la console → collez-le dans « Fournisseurs » → activez l’option de l’agent → vérifiez chaque agent l’un après l’autre. Tout se fait en cliquant dans les fenêtres, sans commande à saisir.
• Ordre de dépannage : passerelle → configuration native de l’agent → couche de correspondance de magpie, en remontant depuis le bas.
• À retenir pour Claude Code : utilisez ANTHROPIC_AUTH_TOKEN et ne terminez pas base_url par /v1.
• À retenir pour Codex : wire_api doit correspondre au protocole pris en charge par le modèle.
• Solution de secours : un script utilisant une variable d’environnement (agents-env.sh) permet aussi à tous les agents de partager une seule clé.

Si vous utilisez plus de trois agents, consacrez une demi-heure à configurer cette solution : par la suite, changer de modèle ou renouveler une clé ne nécessitera qu’une seule modification. Vous pouvez obtenir un crédit d’essai sur APIYI, apiyi.com, pour commencer par tester les outils que vous utilisez le plus, puis affiner la répartition des modèles entre les agents selon les tâches.

Pour aller plus loin : articles connexes

• 📘 Workbuddy prend-il en charge les appels au format natif de Claude ? 3 raisons et tests pratiques pour résoudre 6 types d’erreurs de contenu : pour comprendre les différences entre le format natif d’Anthropic et le format compatible avec OpenAI, consultez cet article. Vous y trouverez aussi pourquoi, à l’étape 2 de cet article, Claude Code doit utiliser un endpoint natif.
• 📊 claude-sonnet-5-5 ou claude-opus-5-5 : Opus est plus rapide, Sonnet est-il simplement moins cher ? 6 séries de données pour choisir la meilleure combinaison pour les agents d’entreprise avec un long contexte : avant de choisir un modèle pour chaque agent à l’étape 4, lisez cet article pour décider lesquels utiliser avec Opus et lesquels peuvent se contenter d’un modèle moins cher.
• ⚠️ Quel est le niveau de concurrence de gemini-4-argon dans AI Studio ? 5 causes fréquentes des erreurs 429 et 6 solutions : si plusieurs agents utilisent la même clé et déclenchent la limite de débit, suivez ces 6 étapes de diagnostic.
• 🧭 Erreur OpenAI « model not found » ? GPT-5.5 a été retiré de ChatGPT le 14 octobre : 5 étapes de diagnostic et solutions de remplacement : si le test de l’étape 5 indique que le modèle est introuvable, vérifiez d’abord que son nom est toujours valide.

📚 Références

1. GitHub – magpie : dépôt officiel du projet
2. Lien : github.com/yetone/magpie
3. À noter : référez-vous au README pour les instructions d’installation, le format de configuration et les mises à jour de version.
4. Documentation officielle de Claude Code : variables d’environnement et configuration des paramètres
5. Lien : docs.anthropic.com/en/docs/claude-code
6. À noter : documentation officielle sur des variables comme ANTHROPIC_BASE_URL.
7. Dépôt OpenAI Codex CLI : configuration de config.toml et de model_providers
8. Lien : github.com/openai/codex
9. À noter : informations sur les fournisseurs personnalisés et le paramètre wire_api.
10. Centre de documentation APIYI : endpoints multiprotocoles et liste des modèles
11. Lien : docs.apiyi.com
12. À noter : instructions de connexion aux endpoints utilisant les protocoles OpenAI, Anthropic et autres.

Auteur : équipe technique APIYI
Échanges techniques : partagez votre expérience de configuration de magpie dans les commentaires. Pour consulter d’autres ressources de connexion, rendez-vous dans le centre de documentation APIYI, à l’adresse docs.apiyi.com.