Instal·lació de Pi i configuració d'OmniProxy

Pi és un petit assistent de terminal—un programa que parla amb tu directament a la línia d’ordres, llegeix fitxers i completa tasques. Té un missatge de sistema curt i només unes poques eines per defecte. Si necessites altres ordres, fluxos de treball o interfícies, pots afegir-les més tard a través d’extensions. Les extensions són components que afegeixen capacitats a Pi, i pots compartir-les amb altres després de crear-les.

Els subagents deleguen part d’una tasca a un altre assistent, mentre que el mode de pla organitza els passos abans que comenci l’execució. Cap de les dues funcions s’inclou per defecte, però pots demanar a Pi que les construeixi o instal·lar paquets compartits per altres.

Abans de començar

macOS i Linux utilitzen un script d’instal·lació—una única ordre que descarrega i instal·la Pi automàticament. A Windows, utilitza l’ordre de PowerShell proporcionada a la pàgina d’inici de Pi. PowerShell és l’entorn de línia d’ordres inclòs amb Windows. També pots instal·lar Pi a WSL, l’entorn Linux disponible dins de Windows.

Si tries instal·lar amb npm, necessites Node.js 22.19 o posterior. npm és el gestor de paquets utilitzat amb Node.js i pot instal·lar Pi des de la línia d’ordres.

macOS Linux

install.sh

• curl l'script oficial
• L'instal·lador fixa les dependències
• Actualitza amb pi update

Windows

install.ps1

• Ordre oficial de PowerShell
• Git for Windows proporciona Bash
• També pots utilitzar WSL

Node ja instal·lat

npm

• Requereix Node 22.19+
• El nom del paquet és pi-coding-agent
• Afegeix --ignore-scripts

Instal·lació i llançament de Pi per primera vegada

En macOS o Linux, obre un terminal i executa:

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

A Windows, obre PowerShell i executa:

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

Si Node.js 22.19 o posterior ja està instal·lat, també pots utilitzar l’ordre alternativa de l’inici ràpid:

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

L’script d’instal·lació pot fer una pausa per fer preguntes en un terminal interactiu. Segueix les indicacions a la pantalla per continuar. Si ja tens una versió compatible de Node, aquesta ordre npm no farà preguntes. Per instal·lar Pi en un altre directori, afegeix --prefix /your/directory. El 09-10-2026, això va instal·lar Pi 1.1.0.

Una instal·lació normal de npm no requereix scripts de cicle de vida de dependències, que són scripts que els paquets executen automàticament durant la instal·lació. L’script d’instal·lació fixa les dependències; després, actualitza Pi amb pi update. Per a una instal·lació de npm, utilitza el mètode d’actualització proporcionat pel teu gestor de paquets. Els usuaris de Nix haurien d’instal·lar des del flake de Pi. Un flake és una configuració de Nix que descriu el programari i les seves dependències, i pi update no pot actualitzar una instal·lació de Nix.

Després de la instal·lació, confirma primer que el teu terminal pot trobar Pi:

pi --version

A Windows, si vols que els models executin ordres Bash, es recomana instal·lar Git for Windows per a la majoria d’usuaris locals. Bash és l’entorn d’ordres que Pi utilitza per executar algunes ordres. Pi comprova el shellPath paràmetre a ~/.pi/agent/settings.json, Git Bash sota Program Files, i després bash.exe al PATH, en aquest ordre. shellPath especifica la ubicació de Bash, mentre que PATH és la llista de directoris que el sistema cerca per a les ordres.

Després d’iniciar Pi, pots introduir !printf 'Bash is working\n' per comprovar-ho. Si els teus fitxers i eines ja estan a WSL, instal·la Pi en aquest entorn Linux seguint l’inici ràpid.

Seguidament, entra a la carpeta que vols que Pi inspeccioni o en la qual treballi, i després inicia’l:

cd /path/to/folder
pi

Aquesta carpeta es converteix en l’àmbit de treball actual de Pi. Pi l’utilitza per descobrir fitxers i configuració i per agrupar sessions.

Obtenir valors de connexió d’OmniProxy

Primer, obtén aquests tres valors d’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 és el punt final de l’API al qual Pi envia les sol·licituds, i ha d’incloure /v1. apiKey és la clau utilitzada per accedir a l’API. Model ID és el nom del model a cridar i s’ha de copiar completament de la llista de models actual d’OmniProxy.

Estableix api a openai-completions, tal com es mostra a l’exemple de l’API compatible. Aquest camp indica a Pi quin format d’API utilitzar en enviar sol·licituds.

Copia l’ID complet del model, incloent-hi qualsevol barra inclinada al nom. El 09-10-2026, els dos IDs de referència a la documentació del proveïdor eren gemini-3.8-flash i grok-4.7. No copiïs un nom que no estigui present a la llista.

Introduir la configuració de l’eina

La configuració de models personalitzats a nivell d’usuari de Pi s’emmagatzema a models.json. Aquest fitxer es troba al directori de l’agent, que per defecte és ~/.pi/agent, per la qual cosa la seva ruta completa és ~/.pi/agent/models.json. Si la variable d’entorn PI_CODING_AGENT_DIR està establerta, Pi utilitza el directori especificat per aquesta variable en lloc d’això. Una variable d’entorn és un valor de configuració subministrat pel sistema perquè els programes el llegeixin.

Introdueix la configuració tal com es mostra a l’exemple de l’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 llista els serveis connectats, mentre que models llista els models que es poden seleccionar. Cada id del model ha de coincidir amb l’ID complet del model a la llista de models actual d’OmniProxy. input indica que el model està configurat aquí per a l’entrada de text.

apiKey es pot introduir com un valor literal, o com $NAME o ${NAME} perquè Pi el llegeixi d’una variable d’entorn. Un valor que comença amb ! es tracta com una ordre i s’executa per a cada sol·licitud. No enviïs una clau real a un repositori. Si la gateway no valida les claus, pots introduir una cadena de text de marcatge utilitzada només a la teva màquina local. El 09-10-2026, Pi va llegir correctament el fitxer amb aquesta configuració.

Obrir /model recarrega aquest fitxer. /model és la interfície a Pi per veure i seleccionar models. Els models personalitzats no apareixen a /model fins que Pi pot resoldre les seves credencials. Després de seleccionar un model, prem Ctrl+S per desar-lo com a model per defecte per a noves sessions.

Fitxer

models.json

• Directori per defecte: ~/.pi/agent
• Afegeix una entrada sota providers
• Estableix api a completions

Adreça

baseUrl

• Inclou /v1
• apiKey pot fer referència a una variable
• L'id del model ha de ser exacte

Selecciona

/model

• Obrir-lo recarrega el fitxer
• Selecciona el model que acabes d'afegir
• Ctrl+S el desa com a per defecte

Verificar amb una tasca real

Després de completar la configuració, pots realitzar una comprovació no interactiva en un directori que contingui fitxers. El mode no interactiu significa que Pi completa aquesta única tasca i després surt en lloc d’entrar en una conversa contínua. Substitueix el valor després de --model amb l’ID complet de la llista actual d’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 només l’eina de lectura, i la tasca també instrueix explícitament a Pi que no modifiqui el fitxer. El 09-10-2026, Pi 1.1.0 va llegir el contingut del fitxer correctament. La primera resposta va trigar uns dos minuts.

També pots utilitzar el mode interactiu: entra al directori, executa pi, i després selecciona un model amb /model. Un exemple de tasca a l’inici ràpid demana a Pi que expliqui com s’organitza el repositori i com executar les seves comprovacions. Observa si llegeix els fitxers i proporciona una explicació, després confirma la font i l’ID del model als registres de sol·licituds d’OmniProxy.

Llançament

pi es llança

• Primer cd a la carpeta
• pi --version produeix una sortida
• El nom del model apareix a la part inferior de la interfície

Tasca

Ha llegit el directori

• Pregunta com s'organitza el repositori
• Revisa els fitxers que llista
• No confiïs només en un desat de configuració correcte

Registres

Visible a la gateway

• La font és Pi
• L'ID del model coincideix
• Mantingues la clau a la màquina local

Errors comuns

• pi no es pot trobar: Torna a obrir el terminal i torna a provar pi --version . Per a una instal·lació de npm, confirma que el directori bin global estigui al PATH.
• Els models personalitzats no apareixen a /model: Confirma que models.json estigui a ~/.pi/agent/, verifica que apiKey es pugui resoldre, i després torna a obrir /model.
• Windows informa que no es pot trobar Bash: Instal·la Git for Windows, o estableix shellPath a ~/.pi/agent/settings.json. Les barres invertides en JSON s’han d’escriure dues vegades.
• La sol·licitud és rebutjada: Comprova que api sigui openai-completions i que baseUrl acabi en /v1. No habilitis opcions de compatibilitat addicionals només perquè el servei es descrigui a si mateix com a compatible.
• L’ID del model no és vàlid: Copia’l de nou de la llista actual d’OmniProxy.

Referències oficials

Per a les ordres d’instal·lació, consulta el Pi website i Quickstart. Per al fitxer de models, consulta Choose a Model i Configuration. Per a l’entorn d’ordres de Windows, consulta Run Pi on Windows. Per als IDs de model utilitzats als exemples, consulta el Gemini model list i xAI models page.

Substitueix cada marcador de posició amb valors de la teva pròpia configuració d'OmniProxy. No publiquis mai una clau real.

Un resultat guardat o HTTP 200 sols no demostra compatibilitat completa de l'Agent. Comprova la font i el model al registre de crides d'OmniProxy.

Fonts oficials · Pi ↗