Modelo Pi custom / variante

Quando Usar

O padrão salvo do Pi só carrega se o provider/id exato existir no registro do seu modelo. O Pi envia uma lista estática agrupada por provedor — então as variantes de atalho de roteamento do OpenRouter (:nitro = ordenar por vazão, :floor = mais barato, :exacto = uso de ferramenta de qualidade) e qualquer slug novíssimo NÃO estão nela. Quando o padrão não resolve, o Pi silenciosamente volta para o seu padrão interno por provedor (para o openrouter, é moonshotai/kimi-k2.6) — parecendo que o Pi "resetou" seu modelo. Correção = registrar o slug como um modelo customizado para que find(provider, id) corresponda.

Arquivos (global)

• ~/.pi/agent/settings.json — defaultProvider, defaultModel, defaultThinkingLevel
• ~/.pi/agent/models.json — modelos customizados, chaveados por provedor
• ~/.pi/agent/auth.json — credenciais do provedor (verifique se a chave do provedor existe)

Passos

1. Confirme se o slug é real antes de adicioná-lo (ex: verifique se o modelo/variante do OpenRouter existe). Um ID com erro de digitação também volta silenciosamente.
2. Confirme a autenticação. O provedor deve ter uma chave em auth.json (ou uma variável de ambiente como OPENROUTER_API_KEY). Sem autenticação → o modelo é registrado, mas indisponível → ainda volta.
3. Adicione o modelo em models.json sob providers.<provider>.models. Para um provedor integrado (openrouter, anthropic, etc.) você só fornece metadados — api, baseUrl e a autenticação são herdados dos padrões agrupados. Exemplo:

   {
     "providers": {
       "openrouter": {
         "models": [
           {
             "id": "z-ai/glm-5.2:nitro",
             "name": "Z.ai: GLM 5.2 (nitro)",
             "reasoning": true,
             "thinkingLevelMap": { "xhigh": "xhigh" },
             "input": ["text"],
             "cost": { "input": 0.95, "output": 3, "cacheRead": 0.18, "cacheWrite": 0 },
             "contextWindow": 1048576,
             "maxTokens": 32768,
             "compat": { "supportsDeveloperRole": false, "thinkingFormat": "openrouter" }
           }
         ]
       }
     }
   }
   

   Copie cost/contextWindow/compat do modelo base (a variante os compartilha) — encontre a entrada agrupada em <pi-pkg>/node_modules/@earendil-works/pi-ai/dist/providers/<provider>.models.js. Não codifique valores genéricos 128k/16k se o modelo real for maior.
4. Defina o padrão em settings.json: defaultProvider + defaultModel = o ID exato. Deixe defaultThinkingLevel como o usuário o tem.
5. Verifique: pi --list-models | grep <id> o mostra, e o JSON é analisado. Opcionalmente, faça um teste rápido: pi --provider <p> --model "<id>" "which model are you?".

Peculiaridades

• Correspondência exata apenas. find() é a correspondência exata de provider+id — sem correspondência aproximada/remoção de dois pontos para o caminho do padrão salvo. O slug em settings.json e models.json deve ser byte a byte idêntico.
• Retorno silencioso. O Pi não exibe erro quando o padrão não resolve; ele apenas mostra um modelo diferente no rodapé. Essa é a pista.
• Não edite settings.json sozinho. Definir defaultModel para um slug não registrado não faz nada — models.json é a correção real.
• enabledModels (opcional) fixa o seletor de modelos para que o ciclo Ctrl+P não possa voltar: "enabledModels": ["<provider>/<id>:<thinking>"].
• Sobrescrita de projeto. O .pi/settings.json de um repositório substitui o global. Se um padrão reverte apenas dentro de um projeto, verifique esse arquivo primeiro.
• Reinicie o Pi completamente — o registro é carregado na inicialização.

Exemplo

Solicitação do usuário:

Registrar slugs de modelos Pi Agent customizados para que as variantes OpenRouter salvas resolvam corretamente.

Limitações

• Adaptado de davidondrej/skills; verifique caminhos locais, ferramentas, credenciais e recursos do agente antes de agir.
• Para comandos, acesso remoto, agendamento, automação de navegador ou fluxos de trabalho de alteração de arquivos, obtenha aprovação explícita do usuário e confirme o ambiente de destino primeiro.