Tutorial paso a paso: conecta todos los agentes con una sola clave y usa magpie, de código abierto, para unificar el acceso a la pasarela de API (con Claude Code, Codex, Pi y Hermes como ejemplos)

Nota del autor: este es un tutorial práctico que puedes seguir paso a paso. Al terminar de leerlo y ponerlo en práctica, tendrás una configuración en la que «una clave y una dirección de gateway sirven para todos los agentes que instales». En adelante, para cambiar de modelo o rotar la clave, solo tendrás que modificar un sitio.

Antes de empezar, ten claro qué vas a hacer

• Objetivo: que todos los agentes de programación de tu equipo compartan la misma clave API y la misma dirección del proveedor ascendente. En este artículo usaremos Claude Code, Codex, Pi y Hermes como ejemplos; conecta los que tengas instalados.
• Duración: unos 30 minutos (sin contar el registro ni las descargas).
• Requisitos previos: un token de APIYI (también puedes usar cualquier servicio proxy de API compatible con OpenAI o Anthropic, o una clave oficial), un equipo que pueda ejecutar comandos y al menos un agente instalado.
• Dificultad: ★★☆☆☆. Basta con saber hacer clic y copiar y pegar; no tendrás que escribir ningún comando durante el proceso.

Guía del tutorial

Entiéndelo en tres minutos: qué hace magpie exactamente

Si solo quieres «seguir los pasos y listo», puedes saltarte esta sección. Pero dedicar tres minutos a leerla te ahorrará tiempo cuando tengas que resolver problemas más adelante.

Cada Agent tiene requisitos distintos para conectarse a los modelos de backend. Si configuras todo a mano, tendrás que mantener una configuración diferente por cada herramienta que instales. Veamos cuatro de las más habituales:

magpie (repositorio github.com/yetone/magpie, con el lema «Every agent’s model. One place.») resuelve precisamente esto: centraliza en una sola interfaz qué modelo usa cada Agent y qué clave lee, y después adapta la configuración nativa de cada herramienta.

En pocas palabras, cada uno se encarga de una cosa:

• magpie gestiona el enrutamiento: decide qué modelo usan Claude Code y Codex
• La pasarela gestiona los protocolos: reenvía las solicitudes en formato Anthropic, OpenAI o Gemini al proveedor del modelo correspondiente

Por eso, lo ideal es que la pasarela de backend admita varios protocolos

La combinación ideal es «magpie gestiona el enrutamiento y la pasarela, los protocolos». Si la pasarela solo admite formatos compatibles con OpenAI, Claude Code necesitará una capa adicional para convertir los protocolos. Esto alarga la cadena y aumenta las posibilidades de que haya incompatibilidades en el formato de las llamadas a herramientas.

La solución de APIYI es usar un solo token compatible con los tres protocolos principales: puedes hacer llamadas con la misma clave usando formatos compatibles con OpenAI, el formato nativo de Anthropic y el formato de Gemini (consulta en la consola el alcance concreto de la compatibilidad). Así, magpie solo necesita una conexión de backend para que todos los Agents se conecten directamente, sin tener que gestionar por separado las cuentas y facturas de los distintos proveedores.

Cómo elegir entre las tres opciones

La configuración manual es la opción más directa, pero cuando se acumulan las herramientas, las claves quedan repartidas en muchos archivos y aumentan notablemente los costes de rotación y diagnóstico. Un script de variables de entorno no requiere dependencias y se puede resolver en unas pocas decenas de líneas, pero no permite asignar modelos distintos a cada Agent. Para casos como «Claude Code con Claude, Codex con GPT y Hermes con un modelo económico», resulta mucho más práctico usar una solución de gestión centralizada como magpie.

Paso 1: Consigue una clave y cópiala

1.1 Crea un token en la consola de APIYI

Ve a la consola de APIYI (apiyi.com), crea un token y cópialo.

En este paso no tienes que escribir ningún comando. Durante todo el proceso, esta clave solo se usa una vez: pégala en el panel «Proveedor» de magpie (paso 3). Después, magpie escribirá automáticamente los archivos de configuración de cada Agent. No necesitas usar export para definir variables de entorno ni modificar archivos como config.toml o settings.json.

🚀 ¿Todavía no tienes un token? Puedes registrarte en APIYI apiyi.com y obtener crédito de prueba. Usa un token para poner en marcha las herramientas que utilizas habitualmente y luego decide qué modelos quieres seguir usando.

1.2 Ten a mano estas dos direcciones

En el paso 3, tendrás que elegir cuál de estas direcciones usar al configurar el proveedor:

✅ Comprobación de este paso: tienes el token en el portapapeles y sabes qué dirección debes usar en el paso 3.

Paso 2: Instala magpie y familiarízate con estas dos pantallas

Consulta el README del repositorio oficial de magpie para ver el código fuente, los métodos de instalación y el formato de configuración (github.com/yetone/magpie). El proyecto cambia con bastante rapidez, así que los comandos de instalación y los nombres de los campos pueden variar según la versión. Lo que se mantiene vigente a largo plazo son las capturas de pantalla y el orden de los pasos que aparecen a continuación.

Cuando termines la instalación y lo abras, verás una ventana con un menú de navegación a la izquierda. En este tutorial solo usaremos dos pantallas: Agent (qué modelo usa cada uno) y Proveedor (dónde se configura la clave).

① Agent, en el menú de navegación de la izquierda, es el panel de control general de todos tus Agent:

Figura 1 · Página Agent: cada herramienta aparece en una fila. El interruptor de la derecha controla si se conecta a magpie; junto a él está el menú desplegable de modelos.

En esta pantalla, fíjate en estos tres elementos:

② Proveedor, en el menú de navegación de la izquierda, es donde se configura la clave del proveedor (lo veremos con más detalle en la siguiente sección).

Si primero quieres hacerte una idea de cómo son los archivos de configuración de magpie, echa un vistazo a las secciones providers y agents del README oficial. En esencia, se trata de «dar un nombre al proveedor, indicar base_url y la clave, y asignar un modelo a cada Agent». Pero para el uso diario basta con hacer clic en la ventana: magpie se encarga de escribir la configuración nativa de cada herramienta, lo que es mucho más fiable que editar YAML a mano.

✅ Comprobación de este paso: puedes abrir la ventana y ves las opciones Agent y Proveedor en el menú de la izquierda.

Paso 3: Añade tu clave API en «Proveedores»

3.1 Entra en la página de proveedores

Haz clic en Proveedores, en el menú de la izquierda (recuadro rojo ① de la figura 2). Cuando se abra la página, haz clic en + Añadir proveedor, en la esquina superior derecha (recuadro rojo ②):

Figura 2 · Página de proveedores: entra en «Proveedores» desde el menú lateral. El botón «+ Añadir proveedor», arriba a la derecha, es el único acceso.

Los proveedores que ya hayas añadido aparecerán aquí en forma de tarjetas. En la segunda línea de cada tarjeta verás su dirección y el número de modelos disponibles (por ejemplo, api.apiyi.com · 11 modelos). Para confirmar si realmente está listo para usarse, comprueba que esa línea muestre un número.

3.2 Qué tipo de proveedor elegir

Al hacer clic en «+ Añadir proveedor», verás un panel de selección con varios grupos (figura 3):

Figura 3 · Panel para añadir proveedores: cinco tipos de origen: suscripción, proveedor, proxy, equipo local y magpie en otro equipo

Los grupos del panel corresponden a cinco tipos distintos de claves:

Si usas APIYI, su endpoint compatible con OpenAI tiene el formato estándar de un proxy. Elige la opción correspondiente en el grupo Proxy. Si tienes una clave API personalizada compatible con OpenAI o Anthropic, haz clic en + Proveedor personalizado, al final del panel (recuadro rojo de la figura 3), e introduce la dirección y la clave. Para la dirección, usa https://api.apiyi.com/v1 (si las solicitudes son nativas de Anthropic, usa https://api.apiyi.com).

Este es el panel de configuración completo de un proveedor. Solo tienes que fijarte en cuatro filas:

Figura 4 · Página de configuración del proveedor APIYI: en Base URL, elige primero el protocolo y luego introduce la dirección; en Accounts, añade la clave API; en Models, selecciona los modelos que estarán disponibles para los Agent.

Esta imagen muestra cómo poner en práctica lo de «un token, varios protocolos»: todas las direcciones son https://api.apiyi.com. Si eliges Compatible con Anthropic, tendrás el endpoint nativo que necesita Claude Code; si eliges Compatible con OpenAI, usarás el endpoint /v1 de Codex, Pi o Hermes. Con Compatible con Gemini ocurre lo mismo. Así no tienes que mantener tres proveedores y tres claves API.

Cuando termines, guarda los cambios y vuelve a la lista de proveedores para comprobar dos cosas: que la segunda línea de la tarjeta muestre el número de modelos y que el interruptor esté activado. Si aparece · N modelos, significa que la clave API y la dirección funcionan. Esta comprobación ya sirve como diagnóstico; no hace falta ejecutar ningún comando adicional.

✅ Verificación de este paso: tu tarjeta aparece en la lista de proveedores y muestra algo como · N modelos, no «Sin configurar».

Paso 4: Conecta uno por uno los Agent que hayas instalado

Vuelve a la página Agent y repite estas tres acciones para cada herramienta que hayas instalado. En esta página aparecen todos los Agent con los que magpie puede conectarse (la lista sigue creciendo; los que no tengas instalados mostrarán «CLI no encontrado»). Conecta todos los que hayas instalado. La tabla de abajo solo incluye cuatro ejemplos habituales:

1. Activa el interruptor de la derecha (pasará de gris a iluminado).
2. Elige un modelo a la derecha del interruptor (si no eliges ninguno, se usará el modelo predeterminado; el que selecciones se guardará en la configuración de esa herramienta).
3. Reinicia la herramienta cuando se te indique (Codex, Claude Code, Pi y Hermes suelen necesitar que reinicies el proceso para cargar la nueva configuración).

Figura 5 · Abre el menú desplegable de modelos. La primera opción, «Predeterminado», hace que el Agent use su propio modelo, sin pasar por magpie. Las opciones siguientes muestran «A través de magpie»; el modelo que selecciones usará ese modelo del proveedor conectado.

Estos son algunos estados habituales. Si ves alguno, vas por buen camino:

• Conectado: la configuración ya está escrita; surtirá efecto al reiniciar la herramienta.
• Sin conectar · Usa la configuración de XXX: el interruptor está desactivado o todavía no has seleccionado un modelo.
• Solo puede usar sus propios modelos; magpie no puede conectarse: esta herramienta (por ejemplo, Cursor) solo permite usar sus propios modelos. Es una limitación de diseño, no un error de configuración.
• CLI no encontrado: la herramienta no está instalada o no se encuentra en PATH. Instálala o actualiza PATH y vuelve a intentarlo.

💡 ¿Quieres asignar modelos distintos a cada Agent? Por ejemplo, Claude para Claude Code, GPT para Codex y uno más económico para Hermes. Elige el modelo correspondiente para cada uno en este paso. Esta es una de las principales ventajas de magpie frente a los scripts de variables de entorno.

✅ Verificación de este paso: los interruptores de las herramientas instaladas están activados y la línea de estado ya no muestra «Sin conectar».

Paso 5: verifica cada Agent con una frase

No basta con terminar la configuración: hay que comprobar que funciona. Envía la tarea más sencilla a cada herramienta:

Para confirmar que las solicitudes pasan realmente por la pasarela, lo más sencillo es revisar en la consola de APIYI el uso y los registros de esta clave: si aparecen nuevas llamadas, significa que las solicitudes de todos los Agent se están enviando a la misma clave.

✅ Verificación de este paso: todos los Agent responden correctamente y la consola muestra los registros de las llamadas correspondientes.

Anexo: cómo elegir un modelo (la opción predeterminada si tienes dudas)

💡 Te recomendamos ejecutar la misma tarea en distintos Agent y modelos: con una clave unificada, basta con cambiar el nombre del modelo para comparar, así que el costo es bajo.

Paso 6 (opcional): qué configuración escribe magpie por ti

Esta sección no afecta a que todo funcione ni es un paso obligatorio. En el uso diario no necesitas tocar estos archivos: en cuanto activas la opción en el paso 4, magpie ya ha escrito todo lo que aparece a continuación. La incluimos por dos motivos: para que sepas qué revisar si algo falla y para que puedas copiar la configuración directamente si algún día decides dejar de usar magpie.

Claude Code: ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN

export ANTHROPIC_BASE_URL="https://api.apiyi.com"   # Endpoint nativo de Anthropic
export ANTHROPIC_AUTH_TOKEN="$APIYI_API_KEY"
# Opcional: especificar el modelo predeterminado (consulta la lista de modelos en la consola)
# export ANTHROPIC_MODEL="<nombre del modelo Claude>"
claude

También puedes añadirlo al campo env de ~/.claude/settings.json para que no dependa de la sesión de terminal.

Codex: sección del proveedor en ~/.codex/config.toml

# ~/.codex/config.toml
model = "<nombre de un modelo de la serie GPT>"
model_provider = "apiyi"

[model_providers.apiyi]
name = "APIYI"
base_url = "https://api.apiyi.com/v1"   # Endpoint compatible con OpenAI
env_key = "APIYI_API_KEY"
wire_api = "responses"                   # Si el modelo seleccionado no admite Responses, cambia a "chat"

wire_api es el punto donde es más fácil equivocarse: las versiones recientes de Codex usan el protocolo Responses de forma predeterminada. Si el modelo solo admite Chat Completions en la pasarela, debes cambiarlo a chat.

Pi y Hermes: declarar un proveedor personalizado compatible con OpenAI

La idea es la misma: establece base_url en https://api.apiyi.com/v1 y haz que la clave use la variable APIYI_API_KEY. La estructura varía según la versión; consulta la documentación oficial de cada herramienta:

// Pi: declara el proveedor en la configuración de modelos personalizados (la estructura depende de la documentación oficial de Pi)
{
  "providers": {
    "apiyi": {
      "baseUrl": "https://api.apiyi.com/v1",
      "api": "openai-completions",
      "apiKey": "APIYI_API_KEY",
      "models": [{ "id": "<nombre del modelo>" }]
    }
  }
}

# Hermes: ejecuta hermes model y selecciona un endpoint personalizado compatible con OpenAI.
# Introduce la siguiente información cuando se te solicite (o añádela al archivo .env o a la configuración de Hermes):
#   Base URL : https://api.apiyi.com/v1
#   API Key  : $APIYI_API_KEY
#   Model    : <nombre del modelo>

#!/usr/bin/env bash
# agents-env.sh —— Alternativa sin magpie: una clave para todos los agentes
# Uso: source agents-env.sh
: "${APIYI_API_KEY:?Primero ejecuta export APIYI_API_KEY}"

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

# Variables genéricas para herramientas compatibles con OpenAI, como Codex / Pi / Hermes
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
export OPENAI_API_KEY="$APIYI_API_KEY"

# Comprobar la conectividad
curl -s "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $APIYI_API_KEY" | head -c 300 && echo
echo "✅ Todos los agentes apuntan a la misma pasarela"

curl -s "https://api.apiyi.com/v1/models" \
  -H "Authorization: Bearer sk-tu-token" | head -c 300

Si algo falla, empieza por aquí: cuatro errores frecuentes

Sigue siempre este orden, de abajo arriba: primero confirma que la pasarela y el token funcionan (comprueba si la tarjeta del proveedor muestra · N modelos); después revisa la configuración nativa del agente; y, por último, comprueba la capa de asignación de magpie. Así, en tres pasos podrás determinar si el problema está en el servicio ascendente, en la propia herramienta o en la capa de configuración centralizada.

Preguntas frecuentes

Consulta rápida en cinco minutos

• Reparto de funciones: magpie gestiona la asignación de modelos y la puerta de enlace, el reenvío según el protocolo. Cada uno se ocupa de una sola cosa.
• Un solo token: elige un proveedor ascendente que admita varios protocolos para que todos los agentes compartan una clave y una sola factura.
• Orden para empezar: crea un token en el panel de control → pégalo en «Proveedor» → activa el interruptor del agente → comprueba uno por uno que todo funcione (todo se hace desde la ventana, sin comandos).
• Orden para solucionar problemas: puerta de enlace → configuración nativa del agente → capa de asignación de magpie, de abajo arriba.
• Punto clave para Claude Code: usa ANTHROPIC_AUTH_TOKEN y no añadas /v1 a base_url.
• Punto clave para Codex: wire_api debe coincidir con el protocolo que admite el modelo.
• Alternativa: un script con variables de entorno (agents-env.sh) también permite que todos los agentes compartan una clave.

Si usas tres agentes o más, merece la pena dedicar media hora a configurar todo esto. A partir de entonces, para cambiar de modelo o rotar la clave solo tendrás que modificar un lugar. Te recomendamos obtener crédito de prueba a través de APIYI apiyi.com, comprobar primero que funcionen las herramientas que usas habitualmente y, después, ajustar la asignación de modelos de cada agente según la tarea.

Lecturas relacionadas

• 📘 ¿Workbuddy admite llamadas en el formato nativo de Claude? Pruebas prácticas: 3 motivos y cómo diagnosticar 6 tipos de errores de content: Si quieres entender las diferencias entre el formato nativo de Anthropic y el formato compatible con OpenAI, lee este artículo. También explica por qué, en el paso 2 de este artículo, Claude Code debe usar el endpoint nativo.
• 📊 claude-sonnet-5-5 frente a claude-opus-5-5: ¿Opus es más rápido y Sonnet solo más barato? 6 conjuntos de datos explican la mejor combinación para agentes empresariales con contextos largos: Antes de asignar modelos a distintos agentes en el paso 4, lee este artículo para decidir cuáles usarán Opus y cuáles un modelo más económico.
• ⚠️ ¿Cuál es la concurrencia de gemini-4-argon en AI Studio? 5 causas de los frecuentes errores 429 y 6 pasos para solucionarlos: Si varios agentes alcanzan el límite de solicitudes al usar la misma clave, sigue estos 6 pasos para diagnosticar el problema.
• 🧭 ¿OpenAI muestra el error «model not found»? GPT-5.5 dejó de estar disponible en ChatGPT el 14 de octubre: 5 pasos para diagnosticarlo y alternativas: Si en la verificación del paso 5 aparece el error «modelo no encontrado», primero confirma que el nombre del modelo siga siendo válido.

📚 Referencias

1. GitHub – magpie: repositorio oficial del proyecto
2. Enlace: github.com/yetone/magpie
3. Nota: consulta el README para conocer los métodos de instalación, el formato de configuración y las actualizaciones de versión.
4. Documentación oficial de Claude Code: variables de entorno y configuración de settings
5. Enlace: docs.anthropic.com/en/docs/claude-code
6. Nota: documentación oficial de variables como ANTHROPIC_BASE_URL.
7. Repositorio de OpenAI Codex CLI: configuración de config.toml y model_providers
8. Enlace: github.com/openai/codex
9. Nota: información sobre proveedores personalizados y el parámetro wire_api.
10. Centro de documentación de APIYI: endpoints para distintos protocolos y lista de modelos
11. Enlace: docs.apiyi.com
12. Nota: instrucciones para conectar mediante endpoints de protocolos como OpenAI y Anthropic.

Autor: equipo técnico de APIYI
Intercambio técnico: Comparte tu experiencia con la configuración de magpie en los comentarios. Encontrarás más información de integración en el centro de documentación de APIYI: docs.apiyi.com.