Instalación de Pi y configuración de OmniProxy

Pi es un pequeño asistente de terminal: un programa que habla contigo directamente en la línea de comandos, lee archivos y completa tareas. Tiene un prompt de sistema corto y solo unas pocas herramientas por defecto. Si necesitas otros comandos, flujos de trabajo o interfaces, puedes añadirlos más tarde a través de extensiones. Las extensiones son componentes que añaden capacidades a Pi, y puedes compartirlas con otros después de crearlas.

Los subagentes delegan parte de una tarea a otro asistente, mientras que el modo plan organiza los pasos antes de que comience la ejecución. Ninguna de estas funciones está incluida por defecto, pero puedes pedirle a Pi que las construya o instalar paquetes compartidos por otros.

Antes de comenzar

macOS y Linux usan un script de instalación (un comando único que descarga e instala Pi automáticamente). En Windows, usa el comando de PowerShell proporcionado en la página de inicio de Pi. PowerShell es el entorno de línea de comandos incluido con Windows. También puedes instalar Pi en WSL, el entorno Linux disponible dentro de Windows.

Si eliges instalar con npm, necesitas Node.js 22.19 o posterior. npm es el gestor de paquetes utilizado con Node.js y puede instalar Pi desde la línea de comandos.

macOS Linux

install.sh

curl el script oficial
El instalador fija las dependencias
Actualizar con pi update

Windows

install.ps1

Comando oficial de PowerShell
Git for Windows proporciona Bash
También puedes usar WSL

Node ya instalado

npm

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

El script de instalación fija las dependencias. La instalación de npm no fija las dependencias transitivas y requiere --ignore-scripts.

Instalación y primer inicio de Pi

En macOS o Linux, abre una 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 Node.js 22.19 o posterior ya está instalado, también puedes usar el comando alternativo del Inicio rápido:

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

El script de instalación puede pausarse para hacer preguntas en una terminal interactiva. Sigue las instrucciones en pantalla para continuar. Si ya tienes una versión compatible de Node, este comando npm no hará preguntas. Para instalar Pi en otro directorio, añade --prefix /your/directory. El 09-10-2026, esto instaló Pi 1.1.0.

Una instalación normal de npm no requiere scripts de ciclo de vida de dependencias, que son scripts que los paquetes ejecutan automáticamente durante la instalación. El script de instalación fija las dependencias; después, actualiza Pi con pi update. Para una instalación de npm, usa el método de actualización proporcionado por tu gestor de paquetes. Los usuarios de Nix deben instalar desde el flake de Pi. Un flake es una configuración de Nix que describe el software y sus dependencias, y pi update no puede actualizar una instalación de Nix.

Después de la instalación, confirma primero que tu terminal pueda encontrar Pi:

pi --version

En Windows, si quieres que los modelos ejecuten comandos Bash, se recomienda instalar Git for Windows para la mayoría de los usuarios locales. Bash es el entorno de comandos que Pi utiliza para ejecutar algunos comandos. Pi comprueba el ajuste shellPath en ~/.pi/agent/settings.json, Git Bash bajo Program Files, y luego bash.exe en PATH, en ese orden. shellPath especifica la ubicación de Bash, mientras que PATH es la lista de directorios que el sistema busca para encontrar comandos.

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

A continuación, ingresa a la carpeta que quieres que Pi inspeccione o en la que trabaje, y luego inícialo:

cd /path/to/folder
pi

Esta carpeta se convierte en el ámbito de trabajo actual de Pi. Pi la utiliza para descubrir archivos y configuraciones y para agrupar sesiones.

Obtener valores de conexión de OmniProxy

Primero, obtén estos tres valores de OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy the full ID from the current OmniProxy model list

baseUrl es el endpoint de la API al que Pi envía solicitudes, y debe incluir /v1. apiKey es la clave utilizada para acceder a la API. Model ID es el nombre del modelo a llamar y debe copiarse en su totalidad de la lista de modelos actual de OmniProxy.

Establece api en openai-completions, como se muestra en el ejemplo de API compatible. Este campo le dice a Pi qué formato de API usar al enviar solicitudes.

Copia el ID completo del modelo, incluyendo cualquier barra diagonal en el nombre. El 09-10-2026, los dos IDs de referencia en la documentación del proveedor eran gemini-3.8-flash y grok-4.7. No copies un nombre que no esté presente en la lista.

Ingresar la configuración de la herramienta

La configuración de modelo personalizado a nivel de usuario de Pi se almacena en models.json. Este archivo se encuentra en el directorio del agente, que por defecto es ~/.pi/agent, por lo que su ruta completa es ~/.pi/agent/models.json. Si la variable de entorno PI_CODING_AGENT_DIR está establecida, Pi utiliza el directorio especificado por esa variable en su lugar. Una variable de entorno es un valor de configuración suministrado por el sistema para que los programas lo lean.

Ingresa la configuración como se muestra en el ejemplo de API 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, mientras que models enumera los modelos que se pueden seleccionar. El id de cada modelo debe coincidir con el ID de modelo completo en la lista de modelos actual de OmniProxy. input indica que el modelo está configurado aquí para entrada de texto.

apiKey se puede ingresar como un valor literal, o como $NAME o ${NAME} para que Pi lo lea de una variable de entorno. Un valor que comienza con ! se trata como un comando y se ejecuta para cada solicitud. No subas una clave real a un repositorio. Si el gateway no valida las claves, puedes ingresar una cadena de marcador de posición usada solo en tu máquina local. El 09-10-2026, Pi leyó con éxito el archivo con esta configuración.

Abrir /model recarga este archivo. /model es la interfaz en Pi para ver y seleccionar modelos. Los modelos personalizados no aparecen en /model hasta que Pi pueda resolver sus credenciales. Después de seleccionar un modelo, presiona Ctrl+S para guardarlo como el modelo predeterminado para nuevas sesiones.

Archivo

models.json

Directorio predeterminado: ~/.pi/agent
Añadir una entrada bajo providers
Establecer api en completions

Dirección

baseUrl

Incluir /v1
apiKey puede hacer referencia a una variable
El id del modelo debe ser exacto

Seleccionar

/model

Abrirlo recarga el archivo
Selecciona el modelo que acabas de añadir
Ctrl+S lo guarda como predeterminado

Después de editar el archivo, abre /model en Pi y confirma que los modelos aparecen.

Verificar con una tarea real

Después de completar la configuración, puedes realizar una comprobación no interactiva en un directorio que contenga archivos. El modo no interactivo significa que Pi completa esta única tarea y luego sale en lugar de entrar en una conversación continua. Reemplaza el valor después de --model con el ID completo de la lista actual de OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Read the first line of the file you specify. Do not modify the file."

Aquí, --tools read habilita solo la herramienta de lectura, y la tarea también instruye explícitamente a Pi para que no modifique el archivo. El 09-10-2026, Pi 1.1.0 leyó el contenido del archivo con éxito. La primera respuesta tomó alrededor de dos minutos.

También puedes usar el modo interactivo: ingresa al directorio, ejecuta pi y luego selecciona un modelo con /model. Un ejemplo de tarea en el Inicio rápido pide a Pi que explique cómo está organizado el repositorio y cómo ejecutar sus comprobaciones. Observa si lee los archivos y proporciona una explicación, luego confirma la fuente y el ID del modelo en los registros de solicitudes de OmniProxy.

Iniciar

pi se inicia

Primero cd a la carpeta
pi --version produce salida
El nombre del modelo aparece en la parte inferior de la interfaz

Tarea

Leyó el directorio

Preguntar cómo está organizado el repositorio
Revisar los archivos que enumera
No confiar solo en un guardado de configuración exitoso

Registros

Visible en el gateway

La fuente es Pi
El ID del modelo coincide
Mantener la clave en la máquina local

Después de que el nombre del modelo aparezca en la parte inferior de la interfaz, completa también una tarea real.

Errores comunes

No se puede encontrar pi: Vuelve a abrir la terminal e intenta pi --version de nuevo. Para una instalación de npm, confirma que el directorio bin global esté en PATH.
Los modelos personalizados no aparecen en /model: Confirma que models.json esté en ~/.pi/agent/, verifica que apiKey se pueda resolver y luego vuelve a abrir /model.
Windows informa que no se puede encontrar Bash: Instala Git for Windows, o establece shellPath en ~/.pi/agent/settings.json. Las barras diagonales inversas en JSON deben escribirse dos veces.
La solicitud es rechazada: Comprueba que api sea openai-completions y que baseUrl termine en /v1. No habilites opciones de compatibilidad adicionales simplemente porque el servicio se describe a sí mismo como compatible.
El ID del modelo no es válido: Cópialo de nuevo de la lista actual de OmniProxy.

Referencias oficiales

Para comandos de instalación, consulta el Pi website y Quickstart. Para el archivo de modelo, consulta Choose a Model y Configuration. Para el entorno de comandos de Windows, consulta Run Pi on Windows. Para los IDs de modelo usados en los ejemplos, consulta el Gemini model list y xAI models page.

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 prueba la compatibilidad completa del Agente. Verifica el origen y el modelo en el registro de llamadas de OmniProxy.

Fuentes oficiales · Pi ↗