Documentación

Pi

Pi, el agente de programación para terminal de Earendil —no el chatbot de Inflection ni la criptomoneda—, admite un proveedor personalizado en un único bloque de models.json: una baseUrl, un api, una key y los identificadores de modelos que quieras. Cuatro campos y ya puedes hablar con Claude y GPT usando una sola clave.

Un bloque de proveedor personalizado en ~/.pi/agent/models.json — baseUrl, api e IDs de modelo — coloca el agente de programación de terminal Pi de Earendil sobre Claude y GPT con una sola clave.

~/.pi/agent/models.json

{
  "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
        }
      ]
    }
  }
}

Incluye /v1 en un proveedor openai-completions. El ejemplo de endpoint compatible de la página de modelos de Pi combina ese valor con http://localhost:11434/v1 y, antes de que se reescribiera la documentación el 22 de septiembre, sus ejemplos de OpenRouter, Vercel AI Gateway y llama.cpp incluían la misma ruta de versión. Ninguna frase enuncia la regla directamente, así que los ejemplos son los que la confirman. Si falta el sufijo de la URL base, el resultado es un 404, no un error de autenticación.

El campo cost de un modelo personalizado tiene todos los valores a cero de forma predeterminada: ese valor predeterminado está en el código fuente de Pi (v0.99.2), pero la documentación ya no lo especifica. Por eso, el proveedor que acabas de añadir muestra $0 en el pie de página y en /session hasta que introduzcas las tarifas manualmente. Los otros dos valores predeterminados silenciosos tienen un efecto más grave: contextWindow recurre a 128000 y maxTokens a 16384. Así, si dejas un modelo sin configurar, se compacta y se trunca mucho antes de alcanzar su capacidad real. El bloque de arriba establece ambos valores a partir del catálogo; haz lo mismo con cualquier identificador que añadas desde la tabla de abajo.

Dónde busca Pi la clave y en qué orden. La página de modelos de Pi indica que, cuando se configuran varias fuentes, usa «primero un --api-key en tiempo de ejecución, luego una credencial auth.json guardada, un apiKey de models.json y, por último, las variables de entorno del proveedor». Por tanto, una clave obsoleta guardada por /login prevalece sobre la del archivo, que suele ser el motivo de que un bloque recién editado siga autenticándose como otra cosa. La misma página añade que los modelos personalizados «se pueden cargar desde models.json, pero no están disponibles en /model hasta que Pi pueda resolver las credenciales». Si un modelo no aparece en el selector, el problema son las credenciales, no la sintaxis.

Este bloque se tomó de la propia documentación de Pi en la fecha indicada abajo, y lo que esa documentación dejó de especificar el 22 de septiembre —los nombres de los campos, los valores predeterminados de los modelos personalizados y los valores de api— se obtuvo del código fuente de Pi en v0.99.2, ese mismo día. Kunavo no ha ejecutado Pi contra su endpoint: ni una sesión, ni un turno en streaming, ni un ciclo completo de herramientas, ni una comprobación del modelo al que acabó dirigiéndose una solicitud. Una página de configuración publicada es una referencia de configuración, no una prueba de compatibilidad, y nada de lo que aparece aquí debe interpretarse como tal. El curl que aparece abajo es lo que puedes confirmar en diez segundos; el comportamiento del cliente debes comprobarlo con Pi.

¿Aún no tienes una clave? Crea una cuenta de Kunavo, genera una clave (empieza por sk-kn-) y añade crédito desde $10; las llamadas se pagan con ese saldo y las llamadas fallidas no se facturan. El panel se abre entonces en la configuración de Pi.

Paso a paso

Cree una clave en /app/keys y cópiela: se muestra una sola vez.
Añádela al entorno como KUNAVO_API_KEY. Pi resuelve "$NAME" o "${NAME}" en el campo apiKey, además de aceptar un valor literal o uno precedido por !command. Usa la forma con llaves cuando después del nombre de la variable haya texto literal.
Crea o edita ~/.pi/agent/models.json y pega el bloque de arriba. Un proveedor que no esté integrado necesita baseUrl y un valor api en el nivel del proveedor o del modelo; el código fuente de Pi se niega a cargar el modelo si faltan. Todo lo demás es opcional. Al abrir /model, se vuelve a cargar el archivo.
Inicia pi, ejecuta /model y elige uno de los identificadores que declaraste. Si no aparecen en la lista, comprueba primero la clave antes de revisar el JSON; consulta la nota sobre el orden de resolución de arriba.
Asígnale una tarea que lea y edite un archivo real. Pi depende de las llamadas a herramientas para casi todo lo que hace, así que una primera ejecución que interactúe con el sistema de archivos te dirá mucho más que un saludo. Además, esa ejecución podría revelar una incompatibilidad de streaming o del esquema de herramientas, precisamente el tipo de incompatibilidad que Kunavo no ha probado por ti.

Comprobado con Documentación de Pi: Choose a Model el 1 de octubre de 2026. La configuración de terceros puede cambiar; si el nombre de un campo ya no coincide con lo que ves, esa página es la autoridad, no esta.

Esta es la versión breve. El tutorial completo —elección del modelo, coste de una sesión real y modos de fallo— está en cuánto cuesta realmente ejecutar Pi, ruta por ruta.

Verifica antes de depurar el cliente

Una solicitud determina si el fallo está en el endpoint, la clave o el archivo de configuración. Si devuelve JSON, la misma URL base y la misma clave funcionan en Pi.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qué ID de modelo introducir en el campo

Todos los modelos de texto están disponibles mediante un ID de modelo; la lista activa está en GET /v1/models, y el catálogo con precios está en la página de modelos. Las tarifas son USD por 1M de tokens, entrada / salida.

ID de modelo	Entrada / salida de Kunavo	Dónde encaja en Pi
`claude-sonnet-5`	$1.40 / $7.00	el modelo de trabajo predeterminado para sesiones que modifican archivos
`claude-opus-5`	$3.50 / $17.50	planificar un cambio en el que un error sería costoso
`claude-haiku-4-5`	$0.70 / $3.50	turnos económicos: triaje, resúmenes y el ciclo que funciona todo el día
`gpt-5-6-sol`	$2.00 / $12.00	una segunda opinión de otra familia, con la misma clave y el mismo baseUrl

La facturación es por token desde un saldo prepago, sin cuota mensual; consulta facturación. Con contexto repetido —que constituye la mayor parte de lo que envía un editor o cliente de chat—, la caché de indicaciones cambia más la factura que la elección del modelo.

La otra opción: `anthropic-messages`

Hasta la actualización de su documentación del 22 de septiembre de 2026, Pi documentaba cuatro valores para api de un proveedor personalizado: openai-completions, openai-responses, anthropic-messages y google-generative-ai. La página actualizada de modelos no enumera ninguno: muestra openai-completions en un ejemplo y describe el caso como «Un endpoint compatible con OpenAI, Anthropic o Google». En v0.99.2, el código fuente de Pi tipa el campo como una cadena de texto libre y lo dirige a la implementación integrada que corresponda entre diez opciones: las cuatro anteriores más openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream y pi-messages. Solo las cuatro primeras se documentaron para proveedores personalizados, y ninguna de las otras seis se probó aquí; nada en esta página afirma que alguna funcione con un endpoint de terceros.

anthropic-messages es uno de los cuatro valores documentados, y Kunavo responde tanto a la interfaz Anthropic Messages como a la compatible con OpenAI. Por tanto, se puede configurar esa ruta. Lo que esta página no hará es incluir una URL base para ella en un bloque listo para pegar: la documentación de Pi nunca ha definido ese campo para esta api. Hasta el 22 de septiembre, lo mostraba de dos formas: https://proxy.example.com/v1 en un ejemplo y un https://proxy.example.com sin más en otro. Ese día, la actualización de la documentación eliminó ambos ejemplos en vez de elegir uno. Si eliges esta ruta, prueba una de las dos opciones; si la primera llamada devuelve 404 en lugar de 401, cambia esa línea.

Conviene conocer tres campos del esquema compat de Pi para esta api antes de llegar a ese punto (código fuente, v0.99.2). Primero, vale la pena citar la única regla de la documentación que se aplica a los tres: los ajustes de compatibilidad «deben describir diferencias verificadas en el comportamiento de solicitud o respuesta del endpoint. No los actives basándote únicamente en que un endpoint anuncie compatibilidad con OpenAI o Anthropic».

compat.supportsEagerToolInputStreaming: para un backend que rechaza el envío anticipado de entradas por herramienta.
compat.supportsStrictTools: indica si el endpoint acepta definiciones de herramientas con esquemas JSON estrictos; un modelo personalizado no hereda lo que declare un modelo integrado de Anthropic.
compat.supportsMidConvoEffort: permite cambiar el nivel de razonamiento durante una conversación. Determinar si este endpoint cumple los requisitos depende del comportamiento en tiempo de ejecución, y Kunavo no lo ha comprobado ejecutándolo.

El bloque openai-completions al principio de esta página evita los tres ajustes; esa es la razón sincera para empezar por ahí, no una afirmación de que funcione mejor.

Preguntas frecuentes

¿Cómo conecto el agente de programación Pi a un proveedor de API personalizado?

Añade un bloque de proveedor a ~/.pi/agent/models.json. La página de modelos de Pi dice que se use models.json «cuando un endpoint utiliza una API que Pi ya admite», y su esquema (código fuente, v0.99.2) acepta baseUrl, apiKey, api, headers, authHeader, models y modelOverrides en el nivel del proveedor. Un proveedor que no esté integrado necesita baseUrl y un valor api en el nivel del proveedor o del modelo. El esquema tipa api como una cadena de texto libre, no como una lista: hasta la actualización de la documentación de Pi del 22 de septiembre de 2026, se documentaban cuatro valores para proveedores personalizados: openai-completions, openai-responses, anthropic-messages y google-generative-ai. En v0.99.2, su código fuente dirige el campo a cualquiera de diez implementaciones integradas; las otras seis nunca se documentaron para este uso y no se probaron aquí. Para un endpoint compatible con OpenAI, openai-completions es el valor que la documentación actualizada aún muestra. Cada entrada de models necesita al menos un id, que se envía directamente al endpoint; por eso, el mismo formato sirve para una pasarela, un servidor local de Ollama o vLLM, y cualquier otro host compatible.

¿De dónde obtiene su clave de API el agente de programación Pi?

De uno de cuatro lugares, y la página de modelos de Pi publica el orden: primero, un valor de --api-key en tiempo de ejecución; después, una credencial guardada en auth.json; luego, un apiKey de models.json; y, por último, las variables de entorno del proveedor. Por eso, una clave guardada anteriormente con /login tiene prioridad sobre la que acabas de editar en models.json. El campo apiKey admite interpolación de variables de entorno ("$NAME" o "${NAME}"), un valor literal o la salida de un comando de shell precedido por "!", así que no es necesario dejar el secreto en el archivo. Si no hay credenciales válidas, la documentación indica que los modelos personalizados se cargan desde models.json, pero no están disponibles en /model.

¿La baseUrl de Pi debe terminar en /v1?

Para un proveedor openai-completions, sí. La documentación de Pi nunca formula esta regla en una frase, pero su ejemplo de endpoint compatible usa http://localhost:11434/v1 para Ollama, y antes de la actualización del 22 de septiembre de 2026, sus ejemplos de OpenRouter, Vercel AI Gateway y llama.cpp también incluían esa ruta de versión. Por tanto, para un endpoint compatible con OpenAI, el valor es la raíz /v1; por ejemplo, https://api.kunavo.com/v1. El caso anthropic-messages sigue sin resolverse: la documentación anterior lo mostraba tanto con /v1 como sin él, y la actualización eliminó ambos ejemplos sin elegir.

¿Por qué mi proveedor personalizado de Pi muestra $0 en el pie de página?

Porque, de forma predeterminada, Pi asigna valores de cero a todos los campos de costo de un modelo personalizado (código fuente, v0.99.2), y el pie de página muestra lo que indica el catálogo, no lo que cobra el endpoint. Nada es gratis; esa cifra simplemente no tiene una fuente hasta que completes las tarifas por millón de tokens de entrada, salida, cacheRead y cacheWrite, además de los tramos que correspondan, según la lista de precios de tu proveedor. Mientras estés en el archivo, presta atención también a dos valores predeterminados cercanos: contextWindow pasa a 128000 y maxTokens a 16384. Por eso, un modelo con una ventana mayor se compacta antes y sus respuestas se cortan, a menos que configures explícitamente ambos valores.

¿Kunavo ha probado el agente de programación Pi?

No. La configuración de esta página se obtuvo de la propia documentación de Pi y, cuando la actualización del 22 de septiembre eliminó algún detalle, de una versión publicada de su código fuente, en la fecha indicada. Sin embargo, no se ha ejecutado ninguna sesión, turno en streaming, ciclo completo de herramientas ni comprobación de enrutamiento de modelos contra este endpoint con este cliente; lo mismo ocurre con todos los clientes de esta sección. Considera el bloque de configuración una referencia de lo que acepta el esquema de Pi, verifica el endpoint y la clave con el comando curl de arriba y conserva una ruta que ya funcione mientras pruebas esta.