Configuración de modelos de Pi Coding Agent: /login, models.json y proveedores personalizados

La configuración de modelos del agente de programación Pi tiene tres niveles: inicia sesión en los proveedores integrados con /login (suscripción o clave de API) o define variables de entorno; los endpoints que Pi no integra pero son compatibles con las API de OpenAI, Anthropic o Google se escriben en ~/.pi/agent/models.json; los servicios que requieren autenticación o protocolos especiales necesitan una extensión. Después de elegir, cambia de modelo con /model.Este artículo explica cómo configurar cada nivel, el orden de lectura de las claves (que cambió tras la revisión), tres valores predeterminados de los modelos personalizados que pueden causar errores silenciosos y un ejemplo completo para conectar un endpoint compatible con OpenAI, basándose en la documentación de Pi revisada el 22 de septiembre de 2026 y en el código fuente v0.99.2 publicado el 30 de septiembre de 2026.

Primero confirma qué Pi estás usando. Esta página trata del agente de código para terminal publicado por Earendil en pi.dev, cuyo repositorio es earendil-works/pi (antes badlogic/pi-mono), con licencia MIT. No es el chatbot Pi de Inflection (pi.ai), la moneda Pi Network, Raspberry Pi ni Oh My Pi de otro autor.

Elige primero el método de conexión

La documentación de modelos de Pi empieza precisamente con esta tabla comparativa:

Pi incluye un catálogo de modelos y puede añadir datos más recientes desde pi.dev; cuando está sin conexión utiliza la caché. Para forzar una actualización, ejecuta pi update --models. Solo necesitas una configuración de modelo personalizada cuando Pi no incluya el proveedor o endpoint que quieres.

Seleccionar un modelo en Pi

• /model: busca y selecciona un modelo. Solo muestra modelos para los que el proveedor tiene credenciales disponibles.
• Pulsa Ctrl+S sobre un modelo: guárdalo como modelo predeterminado de las nuevas sesiones.
• /thinking: selecciona el nivel de razonamiento del modelo actual. Pi solo muestra los niveles compatibles con ese modelo; también puedes pulsar Ctrl+S para guardarlo como predeterminado de inicio.
• Ctrl+P: alterna entre los modelos disponibles; /scoped-models controla y guarda la lista de alternancia.

La sesión registra los cambios de modelo y de nivel de razonamiento y los restaura al reanudarla, pero no modifica los valores predeterminados de las nuevas sesiones.

Orden de lectura de las claves (cambió tras la revisión)

Cuando se configuran varias fuentes de claves a la vez, la documentación de Pi indica este orden: --api-key en tiempo de ejecución → credenciales guardadas en auth.json → apiKey de models.json → variables de entorno del proveedor (o credenciales de entorno de la plataforma en la nube). Por eso una clave antigua guardada con /login sobrescribe la que acabas de escribir en el archivo; es la causa más habitual de que «cambies la configuración pero siga usando la cuenta antigua». /logout puede eliminar las credenciales guardadas. Ten en cuenta que antes de la revisión del 22 de septiembre la documentación colocaba las variables de entorno antes de models.json; los tutoriales antiguos de Internet pueden mostrar todavía el orden anterior.

Otro malentendido habitual: si un modelo no aparece en /model, normalmente es un problema de autenticación y no un error de JSON. La documentación dice que los modelos personalizados pueden cargarse desde models.json, pero permanecen «no disponibles» hasta que Pi resuelve las credenciales.

models.json: ejemplo completo para conectar un endpoint compatible con OpenAI

El ejemplo propio de Pi usa Ollama local; la clave ficticia solo hace que el modelo aparezca como disponible, ya que Ollama no la comprueba:

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

Para conectar un endpoint que requiere autenticación, como Kunavo, hazlo así:

{
  "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 y api son obligatorios. Se pueden escribir en el nivel del proveedor o del modelo; según el código fuente de v0.99.2, si falta cualquiera de los dos, Pi no carga el modelo.
• api no es una selección entre cuatro opciones. Antes de la revisión del 22 de septiembre, la documentación de Pi enumeraba cuatro valores para proveedores personalizados: openai-completions, openai-responses, anthropic-messages y google-generative-ai. Después de la revisión dejó de enumerarlos; solo indica en la tabla anterior «endpoints compatibles con OpenAI, Anthropic o Google» y el ejemplo usa únicamente openai-completions. El código fuente de v0.99.2 define api como una cadena arbitraria y la entrega a la implementación correspondiente entre diez implementaciones integradas: las cuatro anteriores, además de openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream y pi-messages. Solo las cuatro primeras se documentaron como uso para proveedores personalizados; las otras seis no se han probado aquí y esta página no afirma que puedan conectarse a endpoints de terceros.
• La baseUrl de openai-completions debe incluir /v1. La documentación no lo exige en una sola frase, pero todos los ejemplos de endpoints compatibles incluyen la ruta de versión. Si falta /v1, obtendrás un 404 y no un error de autenticación.
• No escribas la clave directamente. apiKey y los valores de los encabezados pueden referenciar variables de entorno con $NAME o ${NAME}, contener un valor literal o ejecutar !指令 para obtenerlo. La documentación indica que el comando de models.json se ejecuta en cada solicitud y no se almacena en caché. Mantén en secreto auth.json y cualquier comando que obtenga claves.
• No es necesario reiniciar después de editar. El archivo se vuelve a leer al abrir /model. Los elementos con el mismo ID en models añaden o sustituyen los modelos de ese proveedor; para modificar los metadatos de un modelo integrado sin sustituir toda la lista, usa modelOverrides.

Tres valores predeterminados que causan errores silenciosos

La revisión de la documentación del 22 de septiembre eliminó la tabla de campos, pero los valores predeterminados siguen en el código fuente (en provider-composer.ts de v0.99.2). En los modelos personalizados, los campos que se dejen sin especificar tomarán estos valores predeterminados:

Además, reasoning tiene false como valor predeterminado y input solo admite texto de forma predeterminada. El ejemplo de Kunavo anterior ya completa el contexto y el límite de salida según la tabla de precios y no incluye cost, porque escribir los precios directamente en el archivo quedaría obsoleto rápidamente. Si quieres que la parte inferior muestre el coste, introduce tú mismo el precio por millón de tokens conforme a la tabla de precios. Pi también admite promptCache (declara en segundos cuánto tiempo permanece viva la caché del proveedor para calentarla); la documentación recomienda elegir el extremo conservador dentro del rango público.

anthropic-messages: se puede conectar, pero no hay una conclusión sobre baseUrl

anthropic-messages es uno de los cuatro valores que la documentación anterior a la revisión enumeraba para proveedores personalizados, y Kunavo también ofrece una interfaz Anthropic Messages, por lo que api: "anthropic-messages" es una vía posible. Sin embargo, la documentación de Pi nunca ha aclarado si el baseUrl de este tipo debe incluir /v1: antes de la revisión, un ejemplo mostraba https://proxy.example.com/v1 y otro mostraba https://proxy.example.com sin ruta; después, ambos ejemplos eliminaron la ruta y la cuestión sigue sin resolverse. Si eliges esta vía, prueba primero una opción y, si la primera solicitud devuelve 404 (en lugar de 401), cambia esta línea. compat también incluye varios interruptores diseñados para endpoints que no son del fabricante original (por ejemplo, supportsEagerToolInputStreaming y supportsStrictTools), pero la documentación advierte que la configuración de compatibilidad debe describir «diferencias de comportamiento verificadas» y no activarse solo porque el endpoint declare compatibilidad con OpenAI o Anthropic. El ejemplo de openai-completions anterior evita estos problemas; esa es la verdadera razón para empezar por él, no que sea más rápido.

Explicación sincera y pagos

La referencia de configuración anterior se ha recopilado leyendo la documentación y el código fuente de Pi. Kunavo no ha ejecutado realmente sus endpoints con Pi: no se han probado sesiones, streaming ni intercambios de herramientas, y tampoco se ha confirmado en qué modelo termina cada solicitud. Conserva la ruta que ya funciona y prueba con Pi una tarea que lea y escriba archivos reales; como Pi depende casi en cada paso de llamadas a herramientas, esa primera ejecución es la mejor manera de detectar incompatibilidades de streaming o del formato de herramientas. La página completa de configuración en inglés está en Pi integration guide; la comparación de las distintas opciones de pago (incluido el gateway Radius de Earendil) está en Pi coding agent pricing.

Kunavo funciona con saldo prepago y cargos por token, sin cuota mensual. La recarga mínima es de $10; el checkout se realiza mediante Stripe y en Taiwán se aceptan tarjetas de crédito (Visa, Mastercard, American Express, JCB y UnionPay), Apple Pay, Google Pay y Link. JkoPay y LINE Pay no están en la lista de métodos disponibles. Consulte Información de facturación; cuando esté listo, puede crear una cuenta y generar una clave.

Preguntas frecuentes

Verificado el 1 de octubre de 2026: las páginas pi.dev/docs/latest/models (Choose a Model) y providers, los archivos src/core/model-config.ts y provider-composer.ts de la etiqueta v0.99.2 de earendil-works/pi y la información de versiones de la API de GitHub. El mismo día se verificó por separado el campo api: qué valores muestra actualmente la página de modelos (solo openai-completions en el ejemplo de Ollama), el tipo de api en model-config.ts de v0.99.2 (cadena arbitraria, líneas 191 y 233), la distribución de modelos personalizados en provider-composer.ts (línea 579) y BUILTIN_APIS de packages/ai/src/compat.ts (línea 180, diez tipos en total). Kunavo no ha ejecutado realmente sus endpoints con Pi.