Verificar o ambiente
Prepare Node.js LTS, Git, uma pasta limpa e um terminal com acesso ao provider.
Guia prático 2026
Guia de implantação do OpenCodeInstale, configuree valide seu modelo
Este guia é para desenvolvedores que querem deixar o OpenCode funcionando rapidamente. Ele cobre ambiente, CLI, conexão do provider, configuração do projeto, testes de validação e falhas comuns.
- Entrada recomendada
- CLI primeiro
- Configuração central
- Provider + modelo
- Melhor para
- Usuários de AI coding
Quick Start
Fluxo de implantação em 7 etapas
Use esta sequência na primeira instalação ou ao migrar a configuração para outra máquina.
Instalar a CLI
Use o método oficial e confirme que o comando opencode está disponível.
Conectar um provider
Comece com apenas um provider e mantenha chaves API fora do repositório.
Escolher um modelo
Use um modelo estável e copie o ID real do painel ou da documentação do provider.
Criar a configuração
Use opencode.json para preferências não secretas como permissões, caminhos ignorados e modelo padrão.
Validar com uma tarefa pequena
Peça para ler um arquivo, editar algo simples e executar um teste.
Registrar notas de erro
Anote versão do Node, provider, proxy, modelo padrão e erros frequentes.
Provider
Provider: faça um caminho funcionar antes de otimizar
A maioria dos erros vem de chave API, Base URL, nome do modelo, proxy ou permissões amplas demais.
| Checagem | Ação recomendada | Erro comum |
|---|---|---|
| API key | Guarde fora do repositório. | Enviar segredos para o Git. |
| Base URL | Use o endpoint oficial ou compatível. | Usar caminho errado ou sem protocolo. |
| Modelo | Copie o ID real do modelo. | Usar nome comercial em vez do ID da API. |
| Permissões | Comece de forma conservadora e libere após validar. | Permitir todos os comandos antes de testar. |
Project config example
Use this as a non-secret configuration shape. Confirm exact fields with your OpenCode version.
{
"model": "provider/model-id",
"permission": { "edit": "ask", "bash": "ask" },
"ignore": ["node_modules", ".env", "dist"]
}Platform Notes
Notas por plataforma
Windows
PowerShell serve para projetos simples; use WSL quando houver muitas dependências Linux.
macOS
Confirme qual instalação do Node o terminal está usando.
Linux
Use usuário normal, proteja chaves API e evite tarefas de desenvolvimento como root.
Troubleshooting
Ordem de diagnóstico
- Se o comando não existe, revise o npm global bin e reabra o terminal.
- Se a lista de modelos está vazia, confira provider, chave, URL e rede.
- Se há timeout, separe rede local, proxy, limites e indisponibilidade do serviço.
- Se permissões falham, confira diretório, permissões de arquivo e política.
- Se a qualidade oscila, valide primeiro com um modelo estável.
FAQ
FAQ de implantação do OpenCode
O que instalar antes do OpenCode?
Node.js LTS, Git, um terminal e pelo menos uma chave de provider.
Onde fica opencode.json?
Normalmente na raiz do repositório, sem segredos.
Como validar a implantação?
Leia um arquivo, edite um arquivo de baixo risco e execute teste ou formatação.