OpenCode Ollama Setup - 7 verificações para modelos locais

Este guia foca a integração OpenCode Ollama: endpoint local, escolha de modelo, validação em repositório pequeno e solução de problemas.

OpenCode connected to Ollama as a local model provider on a developer laptop — OpenCode can use Ollama as a local provider, but the setup should be verified in layers: server, model, config, and a real repository task.

Veredito rápido

Valide primeiro a cadeia inteira: serviço Ollama, modelo carregado e visibilidade no OpenCode.

Depois documente modelo, endpoint e tarefas permitidas para que a configuração seja repetível.

Tabela de decisão

A escolha depende do trabalho. Teste individual pede velocidade; equipe pede rastreabilidade e rollback.

Mantenha esta página separada das intenções de instalação geral, comparação e armazenamento de sessões.

Question	Use ollama launch	Use opencode.json
First-time setup	Best default because it guides model selection and startup.	Useful only if you already know the exact provider fields.
Team repeatability	Good for demos, but easy to leave undocumented.	Better because the endpoint and model choice are explicit.
Local privacy	Works when the selected model actually runs locally.	Better for review because you can verify the local base URL.
Remote Ollama server	Less ideal unless the integration exposes the right host choice.	Better because you can point OpenCode at the server endpoint.
Troubleshooting	Good for confirming whether launch itself works.	Better when comparing machines, ports, and model names.

Antes de começar

Teste o Ollama sozinho. Um modelo lento ou sem memória não melhora dentro de um repositório.

Use um repositório pequeno, com Git e uma tarefa segura.

Separe histórico de sessão, configuração e segredos. Um modelo local não protege automaticamente `.env`, tokens ou caminhos privados. Quanto mais limpo for o contexto do repositório, melhor será a resposta do OpenCode.

Em equipe, defina quem mantém o modelo recomendado, porta, notas de atualização e solução de problemas. Sem dono, cada máquina vira uma exceção difícil de reproduzir.

7 verificações

As verificações separam serviço, modelo, config, leitura, edição, comandos e notas de erro.

Confirm the service Run Ollama directly and make sure the default local service is reachable before opening OpenCode.
Pull the model Use a model that is appropriate for coding and fits your memory budget.
Choose launch or config Use `ollama launch opencode` for the first proof, then document `opencode.json` if the workflow will be reused.
Select the model in OpenCode Open the model picker or equivalent provider selection and confirm the Ollama model is visible.
Run a read-only task Ask OpenCode to summarize a small file before allowing edits.
Run a low-risk edit Change documentation or a test fixture and inspect the Git diff.
Record failure notes Save the model name, port, OS, shell, and fix for any timeout, missing model, or spawn error.

Exemplo de configuração

Confirme os campos na documentação oficial. A ideia é apontar OpenCode para o endpoint compatível com OpenAI do Ollama.

Não coloque tokens reais de cloud em exemplos locais.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      }
    }
  }
}

Troubleshooting

Se o modelo não aparece, rode-o diretamente no Ollama e só depois revise porta, URL e nome.

Se a edição é fraca, reduza o escopo ou use um modelo mais forte.

Se o Ollama responde e o OpenCode falha, registre comando, modelo, porta, sistema e mensagem de erro. Isso permite comparar máquinas antes de mexer no repositório real.

Se a lentidão domina, meça uma pergunta curta, leitura de arquivo e pequena edição. Lentidão em tudo aponta para modelo ou hardware; lentidão só na edição aponta para contexto e permissões.

Four troubleshooting checks for OpenCode and Ollama: server, model, config, and test — Most failures are easier to isolate when you check the Ollama service before changing OpenCode configuration.

Quando não usar como padrão

Não use Ollama como padrão se hardware, contexto ou manutenção não bastam.

Um fluxo misto costuma ser mais prático.

O melhor caminho pode ser híbrido. Use Ollama para explicações privadas e testes locais, e mantenha um modelo cloud mais forte para mudanças complexas e diffs de alto risco.

FAQ OpenCode Ollama

Forma mais rápida?

`ollama launch opencode`.

Keyword principal?

`opencode ollama`.

Servidor remoto funciona?

Sim, com endpoint acessível e seguro.

Local ou cloud?

Use o modelo com diffs confiáveis.

Por que falha?

Modelo ausente, serviço parado, URL, nome ou PATH.

Sources

Verify commands and supported models against official documentation because OpenCode and Ollama integration details can change.

OpenCode Ollama Setup: 7 verificações antes de usar modelos locais