Para o erro de provedor ou modelo não encontrado do OpenCode, primeiro associe o modelo selecionado aos IDs de provedor e modelo que o OpenCode realmente carregou. A referência normalmente tem o formato providerId/modelId. Uma chave de API correta não pode corrigir um ID digitado incorretamente, um modelo personalizado não declarado ou um arquivo de configuração que o processo em execução nunca lê.
Siga o erro, não apenas a expressão “problema do provedor”
| O que você vê | Primeiro ramo a inspecionar |
|---|---|
ProviderModelNotFoundError | Identidade do provedor/modelo, catálogo carregado e adaptador do modelo |
| v2: modelo indisponível | Provedor inativo, modelo ausente ou desabilitado, descoberta ou alias alterado |
ProviderInitError | Pacote do provedor e configuração de inicialização |
| HTTP 401 ou 403 do endpoint | Credencial, host e permissão da conta |
| HTTP 429 ou mensagem de cobrança | Limites de taxa e gastos do provedor que respondeu |
O guia oficial de solução de problemas direciona os erros de modelo não encontrado para as referências de modelo. No código-fonte do provedor, a busca verifica tanto a entrada do provedor quanto seu mapa de modelos. O mesmo erro também pode encapsular o erro de modelo ausente de um adaptador. Capture a mensagem exata antes de alterar credenciais ou comprar mais crédito.
1. Identifique a versão e o modelo selecionado
Execute estas verificações no projeto em que a falha ocorre. Se o aplicativo desktop usar outro servidor, compare a versão e a configuração dele com esta instalação do terminal:
opencode --version
opencode models
opencode auth listEncontre a referência completa do modelo na lista e compare-a caractere por caractere com sua seleção. O prefixo do provedor faz parte da identidade. Um modelo oferecido por um gateway personalizado não se torna o provedor Anthropic integrado apenas porque seu nome contém Claude.
Não interprete uma credencial salva como prova de autenticação remota bem-sucedida. Ela estabelece que existe uma credencial localmente; o endpoint ainda precisa aceitá-la quando uma solicitação for feita.
2. Corrija o par provedor/modelo
Este exemplo usa o formato de provedor da v1 e ilustra os três identificadores correspondentes. Defina a variável de ambiente referenciada no processo que inicia o OpenCode ou use o fluxo de credenciais documentado. Mescle os campos relevantes à sua configuração em vez de substituir configurações não relacionadas:
{
"$schema": "https://opencode.ai/config.json",
"model": "kunavo/claude-sonnet-5",
"provider": {
"kunavo": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kunavo",
"options": {
"baseURL": "https://api.kunavo.com/v1",
"apiKey": "{env:KUNAVO_API_KEY}"
},
"models": {
"claude-sonnet-5": {
"name": "Claude Sonnet 5"
}
}
}
}
}Aqui, kunavo é a chave do provedor e claude-sonnet-5 é a chave do modelo. Portanto, a seleção é kunavo/claude-sonnet-5. Selecionar anthropic/claude-sonnet-5 escolhe outro provedor; selecionar Kunavo/Claude Sonnet 5 substitui as chaves de busca por nomes de exibição. Nenhum dos dois se refere à entrada mostrada acima.
Ao usar /connect e Other para um provedor personalizado, insira o mesmo ID de provedor. A credencial, por si só, não define o catálogo de modelos. Verifique também o adaptador: o adaptador compatível com v1 mostrado aqui usa Chat Completions; um endpoint Responses exige o adaptador apropriado.
3. Mantenha as configurações v1 e v2 separadas
A documentação do provedor v2 usa providers, package e settings, em vez de provider, npm e options da v1. Use a configuração específica da versão, em vez de copiar o bloco anterior sem alterações para uma configuração v2.
Na v2, a chave do mapa de um modelo também pode ser diferente de modelID upstream. Se o mapa contiver coder e enviar o modelo upstream upstream/coder-v2, escolha company/coder para o provedor company. Alterar a seleção para o nome upstream ignoraria o alias configurado.
4. Verifique qual configuração prevalece
O OpenCode mescla fontes de configuração. Um arquivo do projeto pode substituir o modelo global; caminhos personalizados, configuração inline e configurações gerenciadas também podem importar. Inspecione o arquivo do projeto que falha, a configuração global e quaisquer substituições configuradas. Verifique listas de permissões de provedores ou entradas de provedores desabilitados.
Faça uma alteração direcionada, reinicie o processo afetado e liste os modelos novamente. Se o modelo agora estiver disponível, mas a primeira solicitação retornar um erro HTTP, siga esse novo erro. Mantenha os arquivos originais e os dados da sessão durante o diagnóstico; excluir todo o diretório de dados pode remover credenciais e histórico sem corrigir uma referência de modelo incorreta.
Finalize com uma solicitação pequena
Quando a seleção for resolvida, experimente um prompt curto antes de uma tarefa no repositório. Confirme que o provedor pretendido o recebe e registra o modelo esperado. Se ainda falhar, colete a versão, a configuração sanitizada, o erro exato e o trecho de log relevante. Revise os logs para remover chaves e conteúdo do projeto antes de compartilhá-los.
Para o Kunavo, continue com o guia de integração do OpenCode e verifique seu registro de uso. A tarifa atual de Claude Sonnet 5 é $1.40 de entrada e $7.00 de saída por milhão de tokens. Uma comparação de preços se torna útil depois que o cliente seleciona a rota pretendida.
Perguntas frequentes
O que significa ProviderModelNotFoundError no OpenCode?
O OpenCode não consegue resolver o par provedor/modelo selecionado, ou o adaptador do modelo não consegue resolver esse modelo. Verifique o ID do provedor carregado, a chave do modelo e a configuração ativa antes de tratar isso como um problema de saldo ou chave de API. Uma resposta HTTP do provedor, como 401, pertence a um ramo de diagnóstico diferente.
Por que adicionar minha chave de API não adicionou o modelo personalizado?
Uma credencial salva e uma definição de provedor/modelo têm finalidades diferentes. No fluxo de provedor personalizado da v1, o ID do provedor inserido por /connect deve corresponder à chave de configuração, e o modelo deve ser declarado no mapa models desse provedor.
Devo usar provider ou providers no opencode.json?
Siga a documentação da versão instalada. A documentação da v1 usa provider com npm e options. A documentação da v2 usa providers com package e settings. Misturar os dois formatos não é uma migração confiável; siga o esquema e o guia do provedor correspondentes.
Por que o modelo funciona em um projeto, mas não em outro?
As configurações do projeto podem substituir as configurações globais, enquanto a configuração de ambiente, inline ou gerenciada também pode afetar o resultado. Verifique as configurações do modelo e do provedor selecionados no diretório de trabalho do projeto que falha. Se um cliente desktop se conectar a outro servidor, inspecione também a configuração desse servidor.
Documentação oficial e código-fonte do provedor verificados em 17 de setembro de 2026. O exemplo explica a identidade da configuração; não é um benchmark de tarefa de ponta a ponta.