Autoalojar la pasarela de IA Magpie: cambia de modelo libremente en Claude Code, Codex y otros agentes

Claude Code llama por defecto a los modelos de Anthropic, y Codex a los de OpenAI. Para probar DeepSeek en Claude Code, o pasar a otro proveedor cuando uno agota su cuota, tienes que cambiar direcciones y claves en los archivos de configuración de cada herramienta.

Magpie es una pasarela de IA de código abierto (MIT) pensada para esto. Conectas tus proveedores a Magpie y tus agentes solo necesitan la dirección de Magpie. Habla los formatos OpenAI Chat, OpenAI Responses, Anthropic Messages y Gemini, y traduce entre ellos, así que Claude Code puede usar modelos que no son de Anthropic. Además ofrece:

• Conmutación por error y grupos de enrutamiento: cuando un modelo falla o agota su cuota, Magpie pasa a un modelo de respaldo o a otra cuenta, y el agente no llega a ver el error.
• Uso y coste: tokens, tasa de aciertos de caché y coste estimado, por modelo y por cliente.
• Claves de pasarela: una clave propia para cada cliente, con sus propios límites y modelos.

Magpie suele ejecutarse en tu propio ordenador. Este artículo usa la plantilla de Magpie de Zenavo para ejecutarlo en un servidor, de modo que tu portátil, tu ordenador de sobremesa y los de tu equipo compartan una misma configuración. Si lo que necesitas son claves de API y cuotas para todo un equipo, consulta también New API: New API sirve para gestionar en un solo sitio las claves de API de un equipo; Magpie, para que cada agente elija el modelo que quiera.

El servidor, Zenavo y las API de los modelos se facturan por separado. Magpie reenvía y contabiliza las peticiones; no abarata las llamadas a los modelos.

Despliega Magpie

Primero conecta un servidor Linux a Zenavo, abre la plantilla de Magpie, elige el servidor y despliega.

La plantilla configura actualmente:

Ajuste	Valor o propósito
Imagen	ghcr.io/yetone/magpie:latest
Comando	web --addr 0.0.0.0:3430 --no-open, que ejecuta la interfaz web
Puerto HTTP	3430, tanto para la interfaz web como para la API que llaman tus agentes
Volumen	/config, que guarda proveedores, claves de pasarela, inicios de sesión y uso
MAGPIE_WEB_KEY	Se genera al crear el proyecto; es la clave para entrar en la interfaz web
Memoria	Se recomiendan 512 MB

latest sigue a la versión de upstream. Antes de depender de ella, cambia la etiqueta en Source, dentro de los Settings del servicio, por una versión que hayas probado, o por stable, el canal semanal de Magpie.

Añade un dominio e inicia sesión

En la pestaña Networking del servicio magpie, añade un dominio para el puerto 3430, por ejemplo magpie.example.com. Crea un registro DNS A que apunte a tu servidor y espera a que HTTPS esté activo. Los pasos están en Dominios.

Después copia el valor de MAGPIE_WEB_KEY de la pestaña Variable del servicio, abre https://magpie.example.com y pega la clave donde la página la pide. El navegador mantiene la sesión iniciada.

Esta clave es la contraseña de administrador de Magpie. Quien la tenga puede cambiar cualquier ajuste y ver las claves de los proveedores que añadas. Por eso:

• No se la des a quien solo necesita llamar a modelos. Esa persona necesita una clave de pasarela, que se explica más abajo.
• No la incluyas en capturas de pantalla, chats ni repositorios.
• Si crees que se ha filtrado, cámbiala en Variable por un valor aleatorio nuevo (16 caracteres o más: letras, dígitos o - . _ ~), guarda y reinicia el servicio.

La documentación de Magpie recomienda mantener la interfaz web en tu propio equipo o en una VPN. En un dominio público, esta clave es lo único que la protege, así que guárdala como se indica arriba.

Configura la dirección pública

En Variable, añade MAGPIE_PUBLIC_URL con el valor https://magpie.example.com, guarda y reinicia. Magpie se ejecuta en un contenedor y solo ve la dirección interna de este; con esta variable, las direcciones y los ejemplos de configuración que muestra usan tu dominio.

Añade proveedores

Añade proveedores en la página Providers de la interfaz web. Magpie incluye ajustes predefinidos para Anthropic, OpenAI, Google Gemini, DeepSeek, Kimi, Zhipu GLM, Qwen, Mistral, xAI, OpenRouter y otros, y acepta cualquier URL compatible con OpenAI o con Anthropic. Introduce la clave de API del proveedor, guarda y comprueba que sus modelos aparecen en la lista.

En Magpie, los nombres de modelo tienen la forma proveedor/modelo, por ejemplo deepseek/deepseek-v4-pro. También puedes crear grupos de enrutamiento: un conjunto de modelos que recibe las peticiones por orden, por turnos o según el uso, y pasa al siguiente cuando uno falla. Los agentes usan el nombre del grupo como modelo.

Magpie también puede usar suscripciones como Claude o ChatGPT como proveedores. Iniciar sesión en ellas desde un servidor requiere pasos adicionales, descritos en la documentación de Docker de Magpie. Lee antes las condiciones de cada proveedor: una suscripción personal suele ser solo para ti, así que no la compartas con otras personas a través de la pasarela.

Reparte claves de pasarela

Magpie en un servidor solo acepta peticiones que lleven una clave de pasarela activa; las demás reciben un 401. En la interfaz web, abre Gateway → Gateway keys, crea una clave para cada ordenador o persona y cópiala. La clave completa solo se muestra al crearla.

Cada clave puede tener su propio:

• Límite: tokens y coste estimado por día, semana, mes o en total;
• Modelos: por ejemplo, solo deepseek/*;
• Estado: si una clave se filtra, desactívala o rótala sin afectar a otros clientes ni rotar las claves de tus proveedores.

Quien tenga una clave de pasarela puede abrir https://magpie.example.com/me, introducir su clave y ver sus propios límites, su uso, sus modelos y la configuración lista para copiar en Claude Code y Codex. No ve nada de otras claves ni de los proveedores.

Conecta Claude Code

En tu ordenador, configura:

export ANTHROPIC_BASE_URL="https://magpie.example.com"
export ANTHROPIC_AUTH_TOKEN="tu clave de pasarela de Magpie"
export ANTHROPIC_MODEL="deepseek/deepseek-v4-pro"
claude

ANTHROPIC_BASE_URL es solo el dominio, sin /v1; Claude Code añade /v1/messages por su cuenta. Pon en ANTHROPIC_MODEL un modelo o grupo de enrutamiento que veas en Magpie, o cambia con /model dentro de Claude Code. Si además quieres revisar registros, desplegar y revertir servicios de Zenavo directamente desde Claude Code mediante MCP y Skills, consulta Desplegar y depurar proyectos de Zenavo desde Claude Code.

Conecta Codex CLI

Codex CLI define proveedores personalizados en ~/.codex/config.toml:

model = "deepseek/deepseek-v4-pro"
model_provider = "magpie"

[model_providers.magpie]
name = "magpie"
base_url = "https://magpie.example.com/v1"
model_catalog_url = "https://magpie.example.com/v1/codex/models"
env_key = "MAGPIE_API_KEY"
wire_api = "responses"
supports_websockets = false

Luego ejecuta export MAGPIE_API_KEY="tu clave de pasarela" e inicia codex. Aquí base_url sí incluye /v1, a diferencia de Claude Code. model_catalog_url permite que Codex lea de Magpie los modelos que esta clave puede usar.

Para cualquier otra interfaz web o cliente compatible con OpenAI (como Open WebUI o LobeHub autoalojados), usa https://magpie.example.com/v1 como URL base y una clave de pasarela como clave de API.

Copias de seguridad y actualizaciones

El volumen /config guarda las claves de API de tus proveedores, los inicios de sesión de las suscripciones y las claves de pasarela, así que protege sus copias de seguridad como protegerías las propias claves.

En una ventana de mantenimiento, detén el proyecto, haz una copia del volumen desde la pestaña Backup & Restore del servicio magpie, vuelve a iniciar el proyecto y descarga una copia para guardarla. Antes de actualizar, lee las notas de la versión de Magpie y haz una copia antes de cambiar la versión de la imagen.

Preguntas frecuentes

Mi agente recibe un 401. La petición no lleva clave de pasarela, o la clave está desactivada. Magpie en un servidor no acepta la clave de relleno magpie que sí acepta una instalación local. Comprueba también que usas una clave de pasarela y no MAGPIE_WEB_KEY.

Claude Code devuelve 404 o no conecta. Comprueba si ANTHROPIC_BASE_URL termina con un /v1 de más.

Un modelo no existe o se rechaza (403). Usa la forma proveedor/modelo y asegúrate de que el modelo es uno que esta clave de pasarela puede usar. Pide https://magpie.example.com/v1/models con la clave para ver todos los modelos que puede usar.

¿Quién ve mi código? Las peticiones siguen llegando a los proveedores que elijas; tener la pasarela en tu propio servidor no hace que los datos se queden en él. Magpie tiene un enmascaramiento de privacidad opcional que sustituye claves, contraseñas y direcciones de correo por marcadores antes de que salga la petición; actívalo en Settings → Privacy. Magpie envía estadísticas anónimas una vez al día (sin prompts, claves ni uso), que puedes desactivar en la misma página o con DO_NOT_TRACK=1 en Variable.

¿Basta con un servidor pequeño? Magpie es ligero; la plantilla recomienda 512 MB de memoria. La carga viene de las peticiones en streaming simultáneas, así que vigila la memoria y el ancho de banda cuando varias personas lo usen a la vez.

Empieza con la plantilla de Magpie: añade un dominio y guarda bien la clave de acceso, añade proveedores, reparte claves de pasarela y apunta Claude Code y Codex hacia ella.