Instalación de Pi y configuración de OmniProxy

Pi es un pequeño asistente para el terminal, es decir, un programa que conversa contigo directamente desde la línea de comandos, lee archivos y realiza tareas. Su prompt del sistema es breve y sus herramientas predeterminadas son pocas; si necesitas otros comandos, flujos de trabajo o interfaces, puedes añadirlos mediante extensiones. Las extensiones son componentes que incorporan capacidades a Pi y, una vez creadas, también pueden compartirse con otras personas.

Los subagentes permiten delegar una parte de una tarea a otro asistente, mientras que el modo de planificación organiza primero los pasos y comienza a ejecutarlos después. Estas dos funciones no vienen incluidas de forma predeterminada, pero puedes pedirle a Pi que las cree o instalar paquetes compartidos por otras personas.

Preparativos antes de la instalación

En macOS y Linux se utiliza un script de instalación, es decir, un comando que descarga e instala todo automáticamente. En Windows se utiliza el comando de PowerShell disponible en la página principal de Pi; PowerShell es el entorno de línea de comandos incluido con Windows. También puedes instalar Pi dentro de WSL, el entorno Linux de Windows.

Si eliges instalarlo con npm, primero necesitas Node.js 22.19 o una versión posterior. npm es el gestor de paquetes utilizado con Node.js y permite instalar Pi desde la línea de comandos.

macOS Linux

install.sh

• Usa curl con el script oficial
• El instalador fija las dependencias
• Actualiza con pi update

Windows

install.ps1

• Usa el comando de PowerShell del sitio oficial
• Git for Windows proporciona Bash
• También puedes usar WSL

Si ya tienes Node

npm

• Requiere Node 22.19+
• El nombre del paquete es pi-coding-agent
• Añade --ignore-scripts

Instalación y primer inicio

En macOS o Linux, abre el terminal y ejecuta:

curl -fsSL https://pi.dev/install.sh | sh

En Windows, abre PowerShell y ejecuta:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Si ya tienes instalado Node.js 22.19 o una versión posterior, también puedes utilizar el comando alternativo de Quickstart:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

El script de instalación puede detenerse para hacer preguntas cuando se ejecuta en un terminal interactivo; sigue las instrucciones que aparezcan en pantalla. Si ya tienes una versión compatible de Node, este comando de npm no hará preguntas. Para instalarlo en otro directorio, añade --prefix /tu/directorio. El 2026-10-09, este método instaló Pi 1.1.0.

Una instalación normal con npm no necesita los scripts del ciclo de vida de las dependencias, es decir, los scripts que los paquetes ejecutan automáticamente durante la instalación. El script de instalación fija las dependencias y permite actualizar posteriormente con pi update. Si instalaste Pi con npm, el método de actualización dependerá del gestor de paquetes utilizado. Los usuarios de Nix deben instalarlo desde el flake de Pi; un flake es una configuración que Nix utiliza para describir software y dependencias, y pi update no puede actualizar una instalación realizada con Nix.

Cuando termine la instalación, confirma primero que el terminal puede encontrar Pi:

pi --version

En Windows, si quieres que el modelo ejecute comandos Bash, se recomienda que la mayoría de los usuarios con una instalación local instalen Git for Windows. Bash es el entorno de comandos que Pi utiliza para ejecutar determinados comandos. Pi buscará, en este orden, el valor shellPath de ~/.pi/agent/settings.json, Git Bash en Program Files y bash.exe en PATH. shellPath especifica la ubicación de Bash, mientras que PATH es la lista de directorios que el sistema utiliza para buscar comandos.

Después de iniciar Pi, puedes introducir !printf 'Bash is working\n' para comprobarlo. Si tus archivos y herramientas ya están dentro de WSL, instala Pi en ese entorno Linux siguiendo Quickstart.

A continuación, entra en la carpeta que quieres que Pi examine o procese e inícialo:

cd /path/to/folder
pi

Esta carpeta será el ámbito de trabajo actual de Pi. Se utilizará para descubrir archivos y configuraciones, así como para agrupar las sesiones.

Obtener los parámetros de conexión de OmniProxy

Primero, prepara estos tres valores en OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copia el ID completo de la lista actual de modelos de OmniProxy

baseUrl es la dirección de la API a la que Pi enviará las solicitudes y debe llegar hasta /v1. apiKey es la clave utilizada para acceder a la API. Model ID es el nombre del modelo que se utilizará y debe copiarse completo de la lista actual de modelos de OmniProxy.

En api, introduce openai-completions, como en el ejemplo de una interfaz compatible. Este campo indica a Pi qué formato de API debe utilizar para enviar las solicitudes.

Copia el ID del modelo completo y conserva también las barras que contenga el nombre. El 2026-10-09, los dos ID de referencia incluidos en la documentación de los proveedores eran gemini-3.8-flash y grok-4.7. No copies nombres que no aparezcan en la lista.

Completar la configuración de la herramienta

La configuración personalizada de modelos de Pi para el usuario se guarda en models.json. Este archivo se encuentra en el directorio del agente, cuyo valor predeterminado es ~/.pi/agent; por tanto, la ruta completa es ~/.pi/agent/models.json. Si se establece la variable de entorno PI_CODING_AGENT_DIR, Pi utilizará el directorio indicado por esa variable. Una variable de entorno es un valor de configuración que el sistema pone a disposición de los programas.

Completa el archivo como en el ejemplo de una interfaz compatible:

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers enumera los servicios conectados y models enumera los modelos disponibles para seleccionar. El id de cada modelo debe corresponder al Model ID completo de la lista actual de OmniProxy, mientras que input indica que esta configuración utiliza entrada de texto.

apiKey puede escribirse directamente como un valor literal o como $NAME o ${NAME} para que Pi lo lea de una variable de entorno. Los valores que comiencen con ! se tratarán como comandos y se ejecutarán en cada solicitud. No incluyas una clave real en un repositorio. Si la puerta de enlace no valida la clave, puedes introducir una cadena de marcador de posición que solo utilices localmente. El 2026-10-09, Pi pudo leer así el archivo.

Al abrir /model, Pi vuelve a cargar este archivo. /model es la interfaz de Pi para consultar y seleccionar modelos. Los modelos personalizados no aparecerán en /model hasta que Pi pueda interpretar las credenciales. Después de seleccionar un modelo, pulsa Ctrl+S para guardarlo como modelo predeterminado de las sesiones nuevas.

Archivo

models.json

• El directorio predeterminado es ~/.pi/agent
• Añade una entrada en providers
• Usa completions para api

Dirección

baseUrl

• Incluye /v1
• apiKey puede usar una variable
• El id del modelo debe ser exacto

Selección

/model

• Al abrirlo, se volverá a cargar el archivo
• Selecciona el modelo que acabas de añadir
• Ctrl+S permite guardarlo como predeterminado

Verificar una tarea real

Después de completar la configuración, puedes realizar una comprobación no interactiva en un directorio que contenga archivos. «No interactiva» significa que no se inicia una conversación continua: Pi termina después de completar esta única tarea. Sustituye el valor que aparece después de --model por el ID completo de la lista actual de OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Lee la primera línea del archivo que indiques y no modifiques el archivo."

Aquí, --tools read habilita únicamente la herramienta de lectura, y la propia tarea indica de forma explícita que el archivo no debe modificarse. El 2026-10-09, Pi 1.1.0 leyó correctamente el contenido del archivo. La primera respuesta tardó aproximadamente dos minutos.

También puedes utilizar el modo interactivo: entra en el directorio, ejecuta pi y selecciona el modelo mediante /model. Una de las tareas de ejemplo de Quickstart consiste en pedirle a Pi que explique cómo está organizado el repositorio y cómo se ejecutan las comprobaciones. Comprueba si lee los archivos y proporciona la explicación; después, confirma el origen y el ID del modelo en el registro de llamadas de OmniProxy.

Inicio

pi puede iniciarse

• Primero haz cd a la carpeta
• pi --version muestra una salida
• El nombre del modelo aparece en la parte inferior de la interfaz

Tarea

Ha leído el directorio

• Pregunta cómo está organizado el repositorio
• Revisa los archivos que enumera
• No te limites a comprobar que la configuración se guardó

Registro

Es visible en la puerta de enlace

• El origen es Pi
• El ID del modelo coincide
• La clave permanece en el equipo local

Errores frecuentes

• No se encuentra pi: vuelve a abrir el terminal e intenta ejecutar pi --version. Si realizaste la instalación con npm, confirma que el directorio bin global esté incluido en PATH.
• El modelo personalizado no aparece en /model: confirma que models.json esté en ~/.pi/agent/ y que apiKey pueda interpretarse; después, vuelve a abrir /model.
• Windows indica que no encuentra Bash: instala Git for Windows o establece shellPath en ~/.pi/agent/settings.json. En JSON, las barras invertidas deben escribirse por duplicado.
• Se rechaza la solicitud: comprueba que api sea openai-completions y que baseUrl termine en /v1. No actives opciones de compatibilidad adicionales únicamente porque el otro servicio afirme ser compatible.
• El ID del modelo no es válido: vuelve a copiarlo de la lista actual de OmniProxy.

Referencias oficiales

Los comandos de instalación están disponibles en el sitio web de Pi y en Quickstart. La información sobre el archivo de modelos se encuentra en Choose a Model y Configuration. La información sobre el entorno de comandos de Windows se encuentra en Run Pi on Windows. Los ID de modelo utilizados en los ejemplos pueden consultarse en la lista de modelos de Gemini y en la página de modelos de xAI.

Reemplaza cada marcador de posición con valores de tu propia configuración de OmniProxy. Nunca publiques una clave real.

Un resultado guardado o HTTP 200 por sí solo no demuestra compatibilidad total con el Agente. Verifica el origen y el modelo en el registro de llamadas de OmniProxy.

Fuentes oficiales · Pi ↗