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

O Pi é um pequeno assistente de terminal, ou seja, um programa que conversa com você diretamente pela linha de comando, lê arquivos e executa tarefas. O prompt de sistema é curto e há poucas ferramentas disponíveis por padrão. Quando precisar de outros comandos, fluxos de trabalho ou interfaces, você poderá adicioná-los por meio de extensões. As extensões são componentes que acrescentam recursos ao Pi e também podem ser compartilhadas com outras pessoas.

Um subagente permite delegar parte de uma tarefa a outro assistente, enquanto o modo de planejamento organiza as etapas antes de iniciar a execução. Esses dois recursos não vêm incluídos por padrão. Você pode pedir ao próprio Pi que os crie ou instalar pacotes compartilhados por outras pessoas.

Preparação antes da instalação

No macOS e no Linux, use o script de instalação, ou seja, um único comando que baixa e instala tudo automaticamente. No Windows, use o comando do PowerShell fornecido na página inicial do Pi. O PowerShell é o ambiente de linha de comando integrado ao Windows. Também é possível instalar o Pi no WSL, o ambiente Linux do Windows.

Se optar pela instalação com npm, será necessário ter o Node.js 22.19 ou uma versão mais recente. O npm é o gerenciador de pacotes usado com o Node.js e permite instalar o Pi pela linha de comando.

macOS e Linux

install.sh

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

Windows

install.ps1

• Use o comando do PowerShell disponível no site oficial
• Git for Windows fornece o Bash
• Também é possível usar WSL

Node já instalado

npm

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

Instalação e primeira execução

No macOS ou 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 o Node.js 22.19 ou uma versão mais recente já estiver instalado, você também poderá usar o comando alternativo do Quickstart:

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

Em um terminal interativo, o script de instalação pode fazer pausas para apresentar perguntas. Nesse caso, continue conforme as instruções exibidas na tela. Quando uma versão compatível do Node já está instalada, esse comando npm não apresenta perguntas. Para instalar em outro diretório, acrescente --prefix /seu/diretorio. Em 2026-10-09, esse procedimento instalou o Pi 1.1.0.

Uma instalação normal com 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; depois, use pi update para atualizar. Em instalações feitas com npm, a forma de atualização depende do gerenciador de pacotes utilizado. Usuários do Nix devem instalar pelo flake do Pi. Um flake é a configuração que o Nix usa para descrever o software e suas dependências, e pi update não atualiza uma instalação feita com Nix.

Após concluir a instalação, verifique primeiro se o terminal consegue localizar o Pi:

pi --version

No Windows, caso você queira que o modelo execute comandos Bash, recomenda-se que a maioria dos usuários instale o Git for Windows. Bash é o ambiente de comandos que o Pi usa para executar alguns comandos. O Pi procura, nesta ordem, pelo shellPath em ~/.pi/agent/settings.json, pelo Git Bash em Program Files e por bash.exe no PATH. shellPath especifica a localização do Bash, enquanto PATH é a lista de diretórios que o sistema consulta ao procurar comandos.

Depois de iniciar, você pode inserir !printf 'Bash is working\n' para fazer a verificação. Se os arquivos e as ferramentas já estiverem no WSL, faça a instalação nesse ambiente Linux conforme o Quickstart.

Em seguida, acesse a pasta cujos arquivos você pretende deixar o Pi examinar ou processar e inicie o programa:

cd /path/to/folder
pi

Essa pasta será o escopo de trabalho atual do Pi. Ela será usada para localizar arquivos e configurações, além de agrupar as sessões.

Obtenção dos parâmetros de conexão no OmniProxy

Primeiro, obtenha estes três itens no OmniProxy:

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 interface para a qual o Pi envia as solicitações e deve incluir /v1. apiKey é a chave usada para acessar a interface. Model ID é o nome do modelo que será chamado e deve ser copiado por inteiro da lista atual de modelos do OmniProxy.

No campo api, insira openai-completions, conforme o exemplo de interface compatível. Esse campo informa ao Pi qual formato de interface deve ser usado para enviar as solicitações.

Copie o ID completo do modelo, preservando também as barras presentes 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 use nomes que não estejam na lista.

Preenchimento da configuração da ferramenta

A configuração de modelos personalizados do Pi no nível do usuário fica em models.json. Esse arquivo está no diretório do agente, que por padrão é ~/.pi/agent. Portanto, o caminho completo é ~/.pi/agent/models.json. Se a variável de ambiente PI_CODING_AGENT_DIR estiver definida, o Pi usará o diretório indicado por ela. Uma variável de ambiente é um valor de configuração disponibilizado pelo sistema para ser lido pelos programas.

Preencha o arquivo conforme o exemplo de interface 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 lista os serviços conectados, enquanto models lista os modelos disponíveis para seleção. O id de cada modelo deve corresponder ao Model ID completo presente na lista atual do OmniProxy. Já input indica que esta configuração aceita entrada de texto.

apiKey pode ser informado diretamente como um valor literal ou escrito como $NAME ou ${NAME}, para que o Pi o leia de uma variável de ambiente. Valores que começam com ! são tratados como comandos e executados a cada solicitação. Não envie a chave real para o repositório. Se o gateway não validar a chave, você poderá informar uma sequência de caracteres de preenchimento usada apenas localmente. Em 2026-10-09, o arquivo foi lido dessa forma.

Abrir /model recarrega esse arquivo. /model é a opção do Pi usada para visualizar e selecionar modelos. Os modelos personalizados não aparecem em /model até que o Pi consiga interpretar as credenciais. Depois de selecionar um modelo, pressione Ctrl+S para salvá-lo como padrão para novas sessões.

Arquivo

models.json

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

Endereço

baseUrl

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

Seleção

/model

• Ao abrir, o arquivo será recarregado
• Selecione o modelo recém-adicionado
• Use Ctrl+S para salvar como padrão

Verificação com uma tarefa real

Após concluir a configuração, você pode fazer uma verificação não interativa em um diretório que contenha arquivos. No modo não interativo, o Pi não inicia uma conversa contínua: ele é encerrado depois de concluir essa única tarefa. Substitua o conteúdo depois de --model pelo ID completo presente na lista atual do OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Leia a primeira linha do arquivo que você indicar. Não altere o arquivo."

Aqui, --tools read disponibiliza somente a ferramenta de leitura, e a própria tarefa também determina explicitamente que o arquivo não deve ser alterado. Em 2026-10-09, o Pi 1.1.0 leu o conteúdo do arquivo. A primeira resposta levou cerca de dois minutos.

Também é possível usar o modo interativo: acesse o diretório, execute pi e selecione o modelo com /model. Uma tarefa de exemplo do Quickstart pede ao Pi que explique como o repositório está organizado e como executar as verificações. Observe se ele lê os arquivos e apresenta uma explicação. Em seguida, confirme a origem e o ID do modelo nos registros de chamadas do OmniProxy.

Inicialização

pi abre

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

Tarefa

Ele leu o diretório

• Pergunte como o repositório está organizado
• Confira os arquivos listados
• Não verifique apenas se a configuração foi salva

Registros

Visível no gateway

• A origem é Pi
• O ID do modelo corresponde
• Mantenha a chave localmente

Erros comuns

• pi não é encontrado: reabra o terminal e tente novamente com pi --version. Em instalações com npm, confirme que o diretório global de binários está no PATH.
• O modelo personalizado não aparece em /model: confirme que models.json está em ~/.pi/agent/ e que apiKey pode ser interpretada. Depois, abra /model novamente.
• O Windows informa que não encontrou 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.
• A solicitação é recusada: confirme se api está definido como openai-completions e se baseUrl termina com /v1. Não ative opções adicionais de compatibilidade apenas porque o outro serviço afirma ser compatível.
• O ID do modelo é inválido: copie-o novamente da lista atual do OmniProxy.

Referências oficiais

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

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

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

Fontes oficiais · Pi ↗