models.json. O exemplo usa BetterToken: defina a chave, a Base URL do protocolo e o Model ID. Para outro serviço, use a URL, as credenciais e os IDs de modelos desse serviço.
Configurações principais
Pré-requisitos
- Node.js 22.19 ou mais recente.
- Crie uma BetterToken API Key e escolha um modelo com chamadas de ferramentas no model plaza.
- No Windows nativo, instale Git for Windows para a ferramenta Bash do Pi, ou execute o Pi no WSL.
Instalação
Use o comando npm oficial atual do Pi:Configuração manual
Defina a API Key
No terminal que iniciará o Pi, substituaYOUR_API_KEY pela sua chave:
- macOS / Linux
- Windows PowerShell
Obtenha modelos e gere a configuração
Clique em Obter lista de modelos para consultar o catálogo público atual do BetterToken sem informar uma API Key. Escolha uma API e modelos com suporte a chamadas de ferramentas; depois copie um Model ID ou baixe omodels.json gerado.
Se o models.json já existir, mescle a entrada bettertoken gerada com a configuração atual em vez de substituir o arquivo. A configuração usa a variável $BETTERTOKEN_API_KEY definida acima; adicione outros parâmetros conforme as capacidades reais do modelo.
O Pi aceita vários protocolos; escolha um compatível com o modelo e o servidor. Para esta conexão, recomendamos Anthropic Messages para Claude, Responses para GPT quando o servidor oferecer suporte e Chat Completions para outros modelos compatíveis com OpenAI. O seletor usa Chat Completions por padrão e filtra pelas APIs declaradas no catálogo público. Se o modelo não aparecer em Responses, use o exemplo manual abaixo para modelos com suporte confirmado a Responses.
Adicione a URL e o modelo
Crie~/.pi/agent/models.json. No Windows, o caminho padrão é %USERPROFILE%\.pi\agent\models.json. Se o arquivo já existir, adicione a entrada bettertoken ao objeto providers existente.
Como alternativa à configuração gerada, preencha manualmente este exemplo de Responses API. Substitua YOUR_MODEL_ID por um ID do model plaza e mantenha $BETTERTOKEN_API_KEY como referência à variável:
baseUrl e api com uma combinação correspondente:
Escolha uma API com chamadas de ferramentas para seu modelo. Por exemplo, GPT-6.1 Sol usa Responses. Mantenha a Base URL como na tabela; o Pi adiciona o caminho da requisição.
Inicie o Pi
No diretório do projeto, use o Model ID configurado:Verificar a conexão
Executepi --list-models e confirme que bettertoken e seu modelo aparecem. Depois, inicie o Pi e envie:
PI_OK, teste uma pequena tarefa somente de leitura para verificar as chamadas de ferramentas.
Trocar de modelo
Adicione entradas ao arraymodels e execute /model no Pi para recarregar models.json. Selecione um modelo e pressione Ctrl+S para torná-lo padrão em novas sessões. Use nomes locais diferentes para protocolos distintos, cada um com seu api e baseUrl.
Erros comuns
Configuração avançada
Para imagens, níveis de raciocínio ou contexto maior, definainput, reasoning, contextWindow e maxTokens de acordo com as capacidades reais do modelo. Consulte o guia de seleção de modelos.
Detalhes técnicos
providers e --provider são campos de configuração do Pi; bettertoken é o nome local deste exemplo. O Pi consulta primeiro --api-key, depois as credenciais de auth.json e, em seguida, apiKey em models.json. Se esse nome tiver credenciais antigas salvas, remova a entrada correspondente pelo /logout no Pi e conecte novamente.