Configuración de Magpie

Esta guía muestra cómo agregar Aiberm como proveedor en magpie. Después de agregarlo una vez, Claude Code, Codex, Gemini CLI, OpenCode y los demás agentes compatibles con magpie pueden elegir modelos de Aiberm.

magpie es un gateway de código abierto que se ejecuta en tu equipo (de forma predeterminada en 127.0.0.1:3425). Habla las API de OpenAI, Anthropic y Gemini y traduce entre ellas, incluidos el streaming y las llamadas a herramientas. Los agentes solo hablan con magpie. Tu clave de API de Aiberm se queda en magpie; los archivos de configuración de los agentes reciben en su lugar la dirección del gateway local y un token local.

Requisitos previos

• Una cuenta de Aiberm (regístrate)
• Una clave de API de Aiberm (crea una)
• magpie 0.1.8 o posterior (los enlaces de importación lo requieren)

Las descargas para macOS, Windows y Linux están en la página de descargas. En macOS o Linux también puedes instalarlo desde una terminal:

curl -fsSL https://usemagpie.ai/install.sh | sh

En Linux, el script instala la app de escritorio si están presentes GTK 3 y WebKitGTK 4.1, y la versión de terminal en caso contrario. Si la descarga no puede llegar a GitHub, pasa un proxy: curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890.

Endpoints de Aiberm

Rellena tanto la URL de Chat como la de Anthropic. Las solicitudes de Claude Code van sin cambios a la URL de Anthropic, y magpie también envía allí las solicitudes de otros agentes a modelos Claude. Las demás solicitudes van a la URL de Chat, traducidas cuando el agente habla otra API. Aiberm acepta ambos protocolos para sus modelos de chat.

Deja vacías las URL de Responses y Gemini. Los endpoints Responses (/v1/responses) y Gemini (/v1beta) de Aiberm no sirven todos los modelos; por ejemplo, los modelos Claude no están disponibles a través de ellos. Sin esas URL, magpie traduce por su cuenta las solicitudes Responses de Codex y las solicitudes de Gemini CLI, así que Codex y Gemini CLI pueden usar cualquier modelo de Aiberm.

Opción 1: enlace de importación (recomendado)

En un equipo con magpie instalado, abre el enlace de abajo. magpie muestra un diálogo de confirmación con el nombre del proveedor, sus endpoints y un campo para tu clave de API, y te avisa a qué hosts se enviarán tus prompts y tu clave. No se guarda nada hasta que pulses Add.

Agregar a magpie

El enlace no incluye ninguna clave de API a propósito. Una página pública nunca debe llevar un secreto; pega tu propia clave en el diálogo. La clave se guarda solo en ~/.config/magpie/providers.json en tu equipo, y solo tu usuario puede leerla. El enlace web lleva sus parámetros después de #, y los navegadores nunca envían esa parte al servidor.

Sin escritorio (por ejemplo, por SSH), pasa los mismos parámetros a la versión de terminal. Muestra el mismo resumen y pregunta antes de agregar el proveedor:

magpie import 'magpie://import?name=Aiberm&id=aiberm&chat=https%3A%2F%2Faiberm.com%2Fv1&anthropic=https%3A%2F%2Faiberm.com&website=https%3A%2F%2Faiberm.com&keys=https%3A%2F%2Faiberm.com%2Fconsole%2Ftoken'

Opción 2: agregarlo en la app

1. Abre magpie, ve a Providers y pulsa ＋ Add provider.
2. Elige Custom (cualquier URL compatible). magpie no tiene un preset para Aiberm.
3. Rellena el formulario:

4. Guarda. magpie solicita https://aiberm.com/v1/models y ofrece los modelos devueltos en el selector de cada agente. Antes de guardar, Fetch models te permite elegir cuáles ven los agentes, y Test models comprueba la clave y las URL.

Con Models vacío, la lista sale de /v1/models, así que los modelos que Aiberm agregue más adelante aparecen cuando vuelvas a obtener los modelos (o ejecutes magpie provider refresh aiberm). La lista incluye todos los modelos que tu clave puede usar, entre ellos modelos de imagen, voz y embeddings que los agentes de programación no pueden usar; elige solo los que necesites. Define una lista separada por comas solo cuando la lista automática sea incorrecta. Los ids de modelo aparecen en la página de precios y en la Lista de modelos, por ejemplo claude-sonnet-5-5, gpt-5.6-sol o google/gemini-3.1-pro.

Elige un modelo para cada agente

Abre Agents. Cada fila es un agente instalado o configurado en este equipo. Haz clic en el modelo, elige uno bajo aiberm o escribe aiberm/ seguido de un id de modelo.

magpie claude aiberm/claude-sonnet-5-5
magpie codex aiberm/gpt-5.6-sol
magpie opencode aiberm/claude-sonnet-5-5
magpie gemini aiberm/google/gemini-3.1-pro

magpie solo modifica las claves de configuración que le pertenecen. Los comentarios, el orden y la sangría de la configuración del agente se quedan como están. Una sesión que ya está en curso conserva el modelo con el que empezó. Inicia una sesión nueva para que se aplique el cambio. En Codex, reinicia también la app de Codex, porque construye su lista de modelos al arrancar.

Para volver atrás, elige uno de los modelos propios del agente o ejecuta magpie claude default (sustituye claude por el nombre del agente). magpie elimina lo que escribió y restaura los valores que reemplazó.

Si ya conectaste un agente directamente a Aiberm

No necesitas exportar ANTHROPIC_BASE_URL ni OPENAI_BASE_URL para magpie; magpie escribe la dirección del gateway en la configuración propia de cada agente.

• Claude Code o Codex configurado en su archivo de configuración (como en las guías Configuración de Claude Code y Configuración de Codex CLI): no tienes que hacer nada. magpie reemplaza solo los valores que necesita, y magpie <agent> default vuelve a poner los tuyos.
• Claude Code configurado con export, setx o variables de entorno de usuario de Windows: puedes dejarlas. Claude Code da prioridad a los valores de ~/.claude/settings.json, así que la configuración de magpie prevalece mientras lo usas. Después de magpie claude default, Claude Code vuelve a usar tus variables y habla directamente con Aiberm.

Mientras lo usas

• magpie tiene que estar en ejecución. Al cerrar la ventana, sigue en la barra de menús o en la bandeja del sistema. magpie tray inicia solo el icono, y magpie serve ejecuta solo el gateway. Para que arranque al iniciar sesión sin ventana, ejecuta magpie daemon install en macOS o Linux, o magpie autostart on en Windows.

• Agrega la clave solo en magpie. magpie no lee claves de API del entorno de tu shell.

• Una app de proxy (Clash, Surge, mihomo y herramientas similares, con el proxy del sistema, TUN o el modo mejorado activados) puede interceptar el tráfico hacia 127.0.0.1:3425. Si un agente devuelve 502 y la solicitud nunca aparece en la pestaña Routing de magpie, agrega reglas que envíen las direcciones locales en directo, antes de tus demás reglas:

  IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  IP-CIDR6,::1/128,DIRECT,no-resolve

  En una configuración de Clash o mihomo, pon las mismas líneas bajo rules:, cada una empezando con - .

• La pestaña Usage solo cuenta las llamadas que pasan por el gateway. Las llamadas que un agente hace directamente a Aiberm no se incluyen. A menos que definas tus propios precios o una tarifa de precio para el proveedor, magpie estima el costo con los precios de lista de los fabricantes de los modelos, que pueden estar muy por encima de lo que cobra Aiberm. Tu factura real está en la consola de Aiberm.

Opcional: varias claves o un respaldo

Todas las claves de API de una misma cuenta de Aiberm consumen el mismo saldo. Cuando el saldo se agota, todas las claves de esa cuenta fallan a la vez, así que tener más claves de la misma cuenta no sirve de respaldo cuando se acaba el crédito. Varias claves sirven cuando provienen de cuentas de Aiberm distintas, o cuando una clave tiene su propio límite de cuota configurado en la consola y quieres que la siguiente clave tome el relevo cuando se agote.

Para usar varias claves, pégalas en el campo API key del proveedor Aiberm, separadas por comas, espacios o saltos de línea. Primero se prueba la primera clave. Luego elige cómo se reparten las solicitudes:

magpie pasa a la siguiente clave ante errores como 401, 403, 429 y 5xx, siempre que todavía no se haya enviado nada al agente. Least used first y Weekly pace están pensados sobre todo para suscripciones; con claves solo comparan el uso reciente de tokens. Todos los modos excepto Smart provienen del plugin integrado rotation de magpie; si solo se ofrece Smart, activa ese plugin.

Una configuración más común es un respaldo entre proveedores: usar primero una suscripción y Aiberm cuando se agote. En la pestaña Routing, crea un grupo con el modelo de tu suscripción en primer lugar y el modelo de Aiberm en segundo, por ejemplo un modelo de un plan de Claude seguido de aiberm/claude-sonnet-5-5, y apunta el agente a group/<id>. Cuando el primer miembro se queda sin cuota, alcanza el límite de tasa o no está disponible, magpie envía el turno al siguiente miembro antes de que el error llegue al agente. magpie también crea group/auto-<model> por su cuenta cuando dos de tus proveedores sirven el mismo modelo.

Recuperación y solución de problemas

Para otros códigos de error, consulta Manejo de errores. La documentación propia de magpie está en Get started y Add to magpie.