Instalação do Pi e configuração do OmniProxy

O Pi é um pequeno assistente de terminal, ou seja, um programa com o qual pode conversar diretamente na linha de comandos e que consegue ler ficheiros e concluir tarefas. A mensagem de sistema é curta e as ferramentas predefinidas são poucas; quando precisar de outros comandos, fluxos de trabalho ou interfaces, pode adicioná-los através de extensões. As extensões são componentes que acrescentam capacidades ao Pi e, depois de criadas, também podem ser partilhadas com outras pessoas.

Os subagentes permitem entregar parte de uma tarefa a outro assistente, enquanto o modo de planeamento organiza primeiro os passos e só depois inicia a execução. Estas duas funcionalidades não estão incluídas por predefinição, mas pode pedir ao próprio Pi que as crie ou instalar pacotes partilhados por outras pessoas.

Preparação antes da instalação

No macOS e no Linux, utiliza-se um script de instalação, ou seja, um único comando que trata automaticamente da transferência e da instalação. No Windows, utiliza-se o comando do PowerShell disponibilizado na página inicial do Pi; o PowerShell é o ambiente de linha de comandos incluído no Windows. Também pode instalar o Pi no WSL, o ambiente Linux do Windows.

Se optar pela instalação através do npm, precisa primeiro do Node.js 22.19 ou de uma versão mais recente. O npm é o gestor de pacotes utilizado com o Node.js e permite instalar o Pi a partir da linha de comandos.

macOS Linux

install.sh

• Use curl com o script oficial
• As dependências são fixadas pelo instalador
• Atualize com pi update

Windows

install.ps1

• Comando do PowerShell disponibilizado no site oficial
• Git for Windows disponibiliza Bash
• Também pode usar WSL

Se já tiver Node

npm

• Requer Node 22.19+
• O nome do pacote é pi-coding-agent
• Adicione --ignore-scripts

Instalação e primeira execução

No macOS ou no Linux, abra o terminal e execute:

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

No Windows, abra o PowerShell e execute:

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

Se já tiver o Node.js 22.19 ou uma versão mais recente, também pode utilizar o comando alternativo indicado no Quickstart:

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

Num terminal interativo, o script de instalação poderá parar para fazer perguntas; prossiga de acordo com as instruções apresentadas no ecrã. Se já tiver uma versão adequada do Node, este comando npm não fará perguntas. Para instalar noutro diretório, acrescente --prefix /o/seu/diretório. Em 2026-10-09, este método instalou o Pi 1.1.0.

Uma instalação normal através do npm não precisa dos scripts de ciclo de vida das dependências, isto é, scripts executados automaticamente pelos pacotes durante a instalação. O script de instalação fixa as dependências; posteriormente, utilize pi update para atualizar. Se instalar através do npm, o método de atualização depende do gestor de pacotes utilizado. Os utilizadores do Nix devem instalar a partir do flake do Pi; um flake é uma configuração utilizada pelo Nix para descrever software e dependências, e pi update não consegue atualizar uma instalação feita através do Nix.

Depois de concluir a instalação, confirme primeiro que o terminal consegue encontrar o Pi:

pi --version

No Windows, se quiser que o modelo execute comandos Bash, recomenda-se que a maioria dos utilizadores instale o Git for Windows. O Bash é o ambiente de comandos utilizado pelo Pi para executar alguns comandos. O Pi procura, por esta ordem, o valor shellPath em ~/.pi/agent/settings.json, o Git Bash em Program Files e o ficheiro bash.exe no PATH. shellPath especifica a localização do Bash, enquanto o PATH é a lista de diretórios que o sistema utiliza para procurar comandos.

Depois de iniciar o Pi, pode introduzir !printf 'Bash is working\n' para verificar. Se os ficheiros e as ferramentas já estiverem no WSL, instale o Pi nesse ambiente Linux seguindo o Quickstart.

Em seguida, entre na pasta que pretende que o Pi examine ou processe e inicie-o:

cd /path/to/folder
pi

Esta pasta será o âmbito de trabalho atual do Pi, utilizado para encontrar ficheiros e configurações, bem como para agrupar sessões.

Obter os parâmetros de ligação no OmniProxy

Comece por obter no OmniProxy os três valores seguintes:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copie o ID completo da lista atual de modelos do OmniProxy

baseUrl é o endereço da API para o qual o Pi envia os pedidos e deve incluir /v1. apiKey é a chave utilizada para aceder à API. Model ID é o nome do modelo a utilizar e deve ser copiado integralmente da lista atual de modelos do OmniProxy.

No campo api, introduza openai-completions, tal como no exemplo de API compatível. Este campo indica ao Pi o formato de API que deve utilizar para enviar os pedidos.

Copie o ID do modelo por inteiro, incluindo quaisquer barras no nome. Em 2026-10-09, dois IDs de referência presentes na documentação dos fornecedores eram gemini-3.8-flash e grok-4.7. Não copie nomes que não estejam presentes na lista.

Preencher a configuração da ferramenta

A configuração personalizada de modelos ao nível do utilizador do Pi é guardada em models.json. Este ficheiro encontra-se no diretório do agente, que, por predefinição, é ~/.pi/agent; assim, o caminho completo é ~/.pi/agent/models.json. Se definir a variável de ambiente PI_CODING_AGENT_DIR, o Pi utilizará o diretório indicado por essa variável; uma variável de ambiente é um valor de configuração disponibilizado pelo sistema para ser lido por um programa.

Preencha o ficheiro de acordo com o exemplo de API compatível:

{
  "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 apresenta os serviços ligados, enquanto models apresenta os modelos que podem ser selecionados. O id de cada modelo deve corresponder ao Model ID completo da lista atual do OmniProxy, e input indica que esta configuração utiliza entrada de texto.

Pode introduzir diretamente o valor de apiKey ou utilizar $NAME ou ${NAME} para que o Pi o leia a partir de uma variável de ambiente. Um valor iniciado por ! é tratado como um comando e executado em cada pedido. Não submeta a chave real para o repositório. Se o gateway não validar a chave, pode introduzir uma sequência de caracteres de substituição utilizada apenas localmente. Em 2026-10-09, o Pi conseguiu ler o ficheiro desta forma.

Abrir /model faz com que este ficheiro seja recarregado. /model é a opção do Pi utilizada para consultar e selecionar modelos. Os modelos personalizados não aparecem em /model enquanto o Pi não conseguir interpretar as credenciais. Depois de selecionar um modelo, prima Ctrl+S para o guardar como modelo predefinido das novas sessões.

Ficheiro

models.json

• O diretório predefinido é ~/.pi/agent
• Adicione uma entrada em providers
• Use completions em api

Endereço

baseUrl

• Termine em /v1
• apiKey pode usar uma variável
• O id do modelo deve ser exato

Seleção

/model

• O ficheiro é recarregado ao abrir
• Selecione o modelo que acabou de adicionar
• Use Ctrl+S para o guardar como predefinição

Verificar com uma tarefa real

Depois de concluir a configuração, pode efetuar uma verificação não interativa num diretório que contenha ficheiros. Não interativa significa que não é iniciada uma conversa contínua: o Pi termina depois de concluir esta única tarefa. Substitua o valor após --model pelo ID completo presente na lista atual do OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Lê a primeira linha do ficheiro que eu indicar, sem alterar o ficheiro."

Neste caso, --tools read disponibiliza apenas a ferramenta de leitura, e a própria tarefa indica explicitamente que o ficheiro não deve ser alterado. Em 2026-10-09, o Pi 1.1.0 leu o conteúdo do ficheiro. A primeira resposta demorou cerca de dois minutos.

Também pode utilizar o modo interativo: entre no diretório, execute pi e selecione o modelo através de /model. Uma das tarefas de exemplo do Quickstart pede ao Pi que explique como o repositório está organizado e como executar as verificações. Confirme se o Pi lê os ficheiros e apresenta uma explicação; depois, consulte os registos de pedidos do OmniProxy para confirmar a origem e o ID do modelo.

Arranque

O pi abre

• Primeiro, use cd para ir para a pasta
• pi --version apresenta uma saída
• O nome do modelo aparece na parte inferior da interface

Tarefa

Leu o diretório

• Pergunte como está organizado o repositório
• Veja os ficheiros apresentados
• Não se limite a confirmar que a configuração foi guardada

Registo

Visível no gateway

• A origem é Pi
• O ID do modelo corresponde
• Mantenha a chave no computador local

Erros comuns

• Não é possível encontrar pi: volte a abrir o terminal e tente novamente pi --version. Se tiver utilizado o npm, confirme que o diretório bin global está no PATH.
• O modelo personalizado não aparece em /model: confirme que models.json está em ~/.pi/agent/, que apiKey pode ser interpretada e, em seguida, volte a abrir /model.
• O Windows indica que não consegue encontrar o Bash: instale o Git for Windows ou defina shellPath em ~/.pi/agent/settings.json. No JSON, cada barra invertida deve ser escrita duas vezes.
• O pedido é recusado: confirme que api é openai-completions e que baseUrl termina em /v1. Não ative opções de compatibilidade adicionais apenas porque o outro serviço afirma ser compatível.
• O ID do modelo é inválido: volte a copiá-lo da lista atual do OmniProxy.

Referências oficiais

Consulte os comandos de instalação no site do Pi e no Quickstart. Consulte a configuração do ficheiro de modelos em Choose a Model e Configuration. Para o ambiente de comandos do Windows, consulte Run Pi on Windows. Os IDs de modelo utilizados nos exemplos podem ser consultados na lista de modelos Gemini e na página de modelos da xAI.

Substitua todos os espaços reservados por valores da sua própria configuração do OmniProxy. Nunca publique uma chave real.

Um resultado guardado ou HTTP 200 sozinho não prova a compatibilidade total do Agente. Verifique a origem e o modelo no registo de chamadas do OmniProxy.

Fontes oficiais · Pi ↗