Configuração de modelos do Pi Coding Agent: /login, models.json e provedor personalizado

A configuração de modelos do agente de codificação Pi tem três camadas: use /login para entrar em um provider integrado (assinatura ou chave de API) ou defina uma variável de ambiente; para endpoints não integrados ao Pi, mas compatíveis com as APIs OpenAI, Anthropic ou Google, escreva em ~/.pi/agent/models.json; serviços que exigem autenticação ou protocolo especial precisam de uma extensão. Depois de escolher, alterne com /model.Este artigo explica como configurar cada camada, a ordem de leitura das chaves (alterada após a revisão), três valores padrão de modelos personalizados que causam falhas silenciosas e um exemplo completo de conexão a um endpoint compatível com OpenAI, com base na documentação do Pi após a revisão de 22 de setembro de 2026 e no código-fonte v0.99.2 publicado em 30 de setembro de 2026.

Primeiro, confirme qual Pi você está usando. Esta página trata do agente de código para terminal publicado pela empresa Earendil em pi.dev, no repositório earendil-works/pi (antes badlogic/pi-mono), sob licença MIT. Ele não é o chatbot Pi da Inflection (pi.ai), a moeda Pi Network, o Raspberry Pi nem o Oh My Pi de outro autor.

Escolha primeiro o método de conexão

O início da documentação de modelos do Pi traz esta tabela de correspondência:

O Pi inclui um catálogo de modelos e pode acrescentar dados mais recentes do catálogo de pi.dev; offline, usa o cache. Para forçar uma atualização, execute pi update --models. Só é necessário configurar modelos personalizados quando o Pi não tiver o provider ou endpoint desejado.

Selecionar um modelo no Pi

• /model: pesquise e selecione um modelo. Apenas modelos de providers com credenciais disponíveis serão listados.
• Pressione Ctrl+S sobre um modelo: salve-o como modelo padrão de novas sessões.
• /thinking: escolha o nível de raciocínio do modelo atual; o Pi lista apenas os níveis compatíveis com o modelo. Pressione Ctrl+S para salvá-lo como padrão de inicialização.
• Ctrl+P: alterne entre os modelos disponíveis; /scoped-models controla a lista de alternância e a salva.

A sessão registra as mudanças de modelo e nível de raciocínio e as restaura ao retomar a sessão, mas não altera o padrão de novas sessões.

Ordem de leitura das chaves (alterada após a revisão)

Quando várias fontes de chave estão configuradas, a documentação do Pi informa esta ordem: --api-key em tempo de execução → credenciais armazenadas em auth.json → apiKey de models.json → variável de ambiente do provider (ou credencial de ambiente da plataforma de nuvem). Portanto, uma chave antiga salva com /login substituirá a que você acabou de gravar no arquivo; essa é a causa mais comum de “alterei a configuração, mas a conta antiga continua sendo usada”. /logout remove as credenciais salvas. Observação: antes da revisão de 22 de setembro, a documentação colocava a variável de ambiente antes de models.json; tutoriais online antigos podem ainda usar essa ordem.

Outro equívoco comum: quando um modelo não aparece em /model, geralmente é um problema de autenticação, não um erro no JSON. A documentação informa que modelos personalizados podem ser carregados de models.json, mas permanecem “indisponíveis” até que o Pi consiga resolver as credenciais.

models.json: exemplo completo para conectar um endpoint compatível com OpenAI

O exemplo do próprio Pi é o Ollama local — a chave fictícia apenas torna o modelo disponível; o Ollama não a verifica:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

Para conectar um endpoint que exige autenticação, como o Kunavo, faça assim:

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

• baseUrl e api são obrigatórios. Eles podem ser definidos no nível do provider ou do modelo; conforme o código-fonte v0.99.2, se qualquer um dos dois faltar, o Pi não carregará o modelo.
• api não é uma escolha entre quatro opções. Antes da revisão de 22 de setembro, a documentação do Pi listava quatro valores para providers personalizados: openai-completions, openai-responses, anthropic-messages e google-generative-ai. A documentação revisada deixou de listar os valores e apenas diz, na tabela acima, “endpoint compatível com OpenAI, Anthropic ou Google”; o exemplo também usa somente openai-completions. O código-fonte v0.99.2 define api como uma string arbitrária e a encaminha para uma das dez implementações integradas: os quatro valores acima, mais openai-codex-responses, azure-openai-responses, google-vertex, mistral-conversations, bedrock-converse-stream e pi-messages. Apenas os quatro primeiros foram documentados como uso de provider personalizado; os outros seis não foram testados aqui, e esta página não afirma que eles conectem endpoints de terceiros.
• O openai-completions de baseUrl deve incluir /v1. A documentação não estabelece isso em uma frase, mas todos os exemplos de endpoints compatíveis incluem o caminho da versão. Sem /v1, você receberá 404, não um erro de autenticação.
• Não grave a chave diretamente.apiKey e os valores de cabeçalho podem referenciar variáveis de ambiente com $NAME ou ${NAME}, conter um valor direto ou usar !指令 para obtê-lo; a documentação informa que o comando em models.json é executado a cada solicitação e não é armazenado em cache. Mantenha auth.json e qualquer comando que obtenha chaves em segredo.
• Não é necessário reiniciar depois de alterar. O arquivo é relido ao abrir /model. Itens com o mesmo ID em models são adicionados ou substituem o modelo daquele provider; para alterar metadados de um modelo integrado sem substituir a lista inteira, use modelOverrides.

Três valores padrão que causam falhas silenciosas

A revisão da documentação de 22 de setembro removeu a tabela de campos, mas os valores padrão ainda estão no código-fonte (v0.99.2, provider-composer.ts). Se não forem preenchidos, os modelos personalizados usarão:

Além disso, reasoning tem padrão false e input oferece apenas texto por padrão. O exemplo do Kunavo acima já preencheu o contexto e o limite de saída conforme a tabela de preços e não incluiu cost, porque preços gravados no arquivo ficam desatualizados rapidamente — para exibir o custo na parte inferior, preencha você mesmo os preços por milhão de tokens conforme a tabela de preços. O Pi também suporta promptCache (declarar em segundos por quanto tempo o cache do fornecedor permanece ativo, para aquecimento do cache); a documentação recomenda usar a extremidade mais conservadora do intervalo público.

anthropic-messages: é possível conectar, mas o baseUrl não é definido

anthropic-messages é um dos quatro valores que a documentação anterior à reformulação listava para provedores personalizados. O Kunavo também oferece uma interface Anthropic Messages, portanto a opção api: "anthropic-messages" existe. Mas a documentação do Pi nunca deixou claro se o baseUrl desse tipo deve incluir /v1: antes da reformulação, um exemplo usava https://proxy.example.com/v1 e outro usava https://proxy.example.com sem caminho; após a reformulação, os dois exemplos foram removidos, e a questão continua sem uma resposta definitiva. Se optar por essa abordagem, teste primeiro uma das formas e, se a primeira requisição retornar 404 (em vez de 401), altere essa linha. compat também contém algumas opções criadas especificamente para endpoints de terceiros (por exemplo, supportsEagerToolInputStreaming e supportsStrictTools), mas a documentação alerta: as configurações de compatibilidade devem descrever “diferenças de comportamento verificadas”; não as ative apenas porque o endpoint declara ser compatível com OpenAI ou Anthropic. O exemplo de openai-completions acima evita essas questões, e esse é o verdadeiro motivo pelo qual se recomenda começar por ele, não por ser mais rápido.

Transparência e pagamento

O conteúdo acima é uma referência de configuração compilada a partir da documentação e do código-fonte do Pi. O Kunavo não executou o Pi com seu próprio endpoint — não executou sessões, streaming ou interações com ferramentas, nem confirmou em qual modelo a solicitação finalmente termina. Mantenha o caminho que já funciona e dê ao Pi uma tarefa que leia e grave arquivos reais; como o Pi depende quase sempre de chamadas de ferramentas, essa primeira execução é a melhor forma de revelar incompatibilidades de streaming ou de formato de ferramentas. A página completa de configuração em inglês está em Pi integration guide; compare as opções pagas (incluindo o gateway Radius da própria Earendil) em Pi coding agent pricing.

A Kunavo funciona com recarga pré-paga e cobrança por token, sem mensalidade. A recarga mínima é $10; o checkout usa a Stripe e, em Taiwan, aceita cartões de crédito (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay e Link. JKO Pay e LINE Pay não estão disponíveis. Consulte as informações de cobrança; quando estiver pronto, você pode criar uma conta e gerar uma chave.

Perguntas frequentes

Verificado em 1º de outubro de 2026: as páginas pi.dev/docs/latest/models (Choose a Model) e providers, a tag v0.99.2 de earendil-works/pi nos arquivos src/core/model-config.ts e provider-composer.ts, além das informações de versão da API do GitHub. No mesmo dia, o campo api foi verificado separadamente: quais valores a página de modelos lista atualmente (somente openai-completions no exemplo do Ollama), o tipo de api em model-config.ts do v0.99.2 (string arbitrária, linhas 191 e 233), o encaminhamento de modelos personalizados em provider-composer.ts (linha 579) e BUILTIN_APIS em packages/ai/src/compat.ts (linha 180, dez valores ao todo). O Kunavo não executou o Pi com seu próprio endpoint.