Provedores do OpenCode: 7 verificações para modelos, chaves e configuração

A busca provedores do OpenCode pode significar quais serviços usar, como adicionar um provedor externo, se um endpoint compatível com OpenAI funciona ou por que o provedor aparece sem os modelos. Uma lista fixa de marcas fica desatualizada com preços, IDs e autenticação; um processo de decisão continua verificável.

A documentação oficial do OpenCode reúne Credentials, Config, OpenCode Zen, OpenCode Go e um diretório de provedores. Este guia acrescenta a ordem prática: identificar a camada, escolher a conexão mínima, confirmar o ID do modelo e registrar a evidência antes de habilitar tarefas com escrita.

O provedor é o caminho até um serviço de modelos. O modelo é a capacidade específica exposta por esse serviço; as credenciais provam que a solicitação é autorizada. Se tudo for tratado como uma configuração única, os sintomas confundem: uma chave válida não corrige um ID errado e um modelo visível não prova que a credencial ainda funciona.

O escopo da configuração é uma quarta decisão. Um provedor pode funcionar no arquivo do projeto e não no global, ou uma configuração gerenciada pode substituir a sua alteração. Registre arquivo, escopo, nome do provedor, ID do modelo e data de validação em vez de compartilhar um arquivo completo com caminhos locais.

Há quatro caminhos comuns. OpenCode Go e OpenCode Zen são serviços próprios com planos e premissas de modelos diferentes. Um provedor hospedado de terceiros é útil quando a equipe já tem cobrança, controle regional ou catálogo preferido. Um endpoint compatível com OpenAI ou local é flexível, mas exige mais responsabilidade por URL, descoberta, runtime e diagnóstico.

Não escolha apenas pelo nome no diretório. Pergunte qual restrição vem primeiro: custo mensal previsível, controle por uso, localização dos dados, uso offline, qualidade, latência ou um serviço já operado pela equipe. Um provedor barato pode não servir se a lista de modelos for instável ou se o ambiente não puder verificar o endpoint.

A estrutura oficial coloca provedores personalizados dentro da chave provider. O adaptador npm, as opções, a variável de autenticação e o mapa de modelos dependem do serviço. Leia a documentação do fornecedor, copie apenas os campos compreendidos e registre por que o endpoint e o adaptador foram escolhidos.

Mantenha o segredo fora do repositório: use OAuth, variável de ambiente ou o armazenamento de credenciais da plataforma. Nunca cole uma chave ativa em opencode.json, captura de tela, histórico do shell ou sessão compartilhada. Se a chave apareceu em um log, faça a rotação antes de continuar.

Adicione um provedor por vez. Uma alteração pequena separa problema de schema, falha do serviço e rollback; remova o bloco novo, restaure o modelo conhecido e repita a solicitação conhecida.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "my-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "provider-demo",
      "options": { "baseURL": "https://api.provider.test/v1" },
      "models": { "model-id": { "name": "Model name" } }
    }
  }
}

A entrada só está pronta quando o OpenCode encontra um modelo real e conclui uma solicitação pequena. Confira ID e autenticação na documentação atual do provedor e use /models. Se houver várias variantes, comece com uma que combine contexto, ferramentas, latência e custo da tarefa.

A primeira solicitação deve ser somente de leitura e fácil de comparar: peça uma explicação de um arquivo local pequeno ou apenas o próximo comando de validação, sem executá-lo. Registre completude, ferramentas, duração e modelo usado. Só depois teste edição ou escrita externa.

1. Checar escopoConfirme se é global, de projeto, caminho personalizado ou gerenciado.
2. Proteger a chaveUse OAuth, variável de ambiente ou o cofre do provedor.
3. Confirmar provedorCompare ID, adaptador, endpoint e instruções oficiais.
4. Confirmar modeloUse o ID exato, não apenas o nome exibido.
5. Listar modelosAbra o seletor ou siga o fluxo `/models` documentado.
6. Testar leituraUse um prompt pequeno e compare com uma expectativa conhecida.
7. Anotar rollbackGuarde a configuração válida, o resultado e a reversão mínima.

Os erros ficam mais claros quando autenticação, descoberta, modelo e transporte continuam separados. Um 401 ou loop OAuth aponta para credenciais ou escopos. Um provedor ausente aponta para escopo, schema ou carregamento. Um modelo ausente aponta para catálogo ou ID. Um timeout depois da descoberta aponta para rede, proxy, região ou saúde do serviço.

Altere uma variável por teste. Verifique primeiro o endpoint segundo a fonte oficial, depois o arquivo lido pelo OpenCode, a lista de modelos e por fim o prompt. Adicionar muitos provedores para investigar um só dificulta o catálogo e os logs.

OpenCode Go combina com assinatura e cota previsíveis; Zen com catálogo selecionado e pagamento por uso. Um provedor hospedado de terceiros é adequado quando cobrança, conformidade, região ou um modelo específico importam. Um endpoint local ou compatível com OpenAI é útil se você aceitar manter o runtime e o serviço. São decisões de adequação, não um ranking permanente.

O provedor também muda a hipótese de privacidade. O CLI pode rodar localmente enquanto as solicitações vão para o serviço escolhido. Leia a política, não envie segredos nem dados de clientes desnecessários e faça o primeiro teste em um repositório não produtivo. As páginas de Models, JSONC, Ollama e Go vs Zen cobrem os temas vizinhos; esta página apenas os conecta.

Para a consulta ampla provedores do OpenCode, o resultado útil é uma conexão reproduzível, não uma lista congelada de vencedores. Diretório, modelos, preços, limites e login mudam; confira a fonte oficial no dia da configuração e registre a data.