OpenCode não funciona: corrija PATH, tela preta e erros de modelo
Uma lista de correções para o OpenCode com o diagnóstico em primeiro lugar — "command not found" no Windows, janelas de terminal pretas, erros de limite gratuito e de provedores, uma lista de modelos que parece incompleta e a extensão do VS Code — cada correção mostrada em uma gravação real.
Respostas rápidas
- "opencode: command not found" logo depois da instalação? A pasta bin do instalador está fora do PATH — exporte-a no perfil do seu shell (o vídeo adiciona o caminho .opencode/bin para o Git Bash) e abra um terminal novo.
- O script de instalação dá erros? Ele é um script Bash — executado no PowerShell falha na flag -fsSL. Troque primeiro o perfil de terminal padrão do VS Code para o Git Bash e rode de novo curl -fsSL https://opencode.ai/install | bash.
- O terminal ou a janela do app abre preta? Apague a pasta de dados corrompida em .local/share/opencode (AppData\Local\share\opencode no Windows), encerre os processos travados e reabra — na gravação a TUI volta a renderizar em menos de um minuto.
- "Free usage exceeded" ou erros de provedor? Abra o seletor de modelos com /models e troque para outro modelo, ou reautentique com /connect. Rode opencode auth list para confirmar que suas credenciais chegaram.
- Modelos sumiram da lista? Só aparecem provedores conectados. Adicione o provedor com /connect, ou organize a lista com as chaves model, disabled_providers e as whitelist/blacklist por provedor no opencode.json.
Fix OpenCode Error in Antigravity Terminal (Git Bash + PATH Solution)
Canal:teacher account5:52
OpenCode docs — install, config & troubleshooting
Docs:opencode.ai/docs
Os quadros vêm de três gravações de tela: a correção de PATH acima, um reparo de tela preta no Windows (xiXPoY2d4iw por Vũ Văn Hà) e uma troca de modelo ao estourar o limite gratuito (DX8MZFuu1BM por Free Code). Cada passo linka direto no trecho correspondente do vídeo.
Os quadros do vídeo continuam propriedade de seus criadores e são incorporados aqui como documentação passo a passo, com atribuição e deep links.
Conserte o OpenCode passo a passo
Instalação e PATH — a fase do "not recognized"
- 1
Pegue o comando de instalação oficial
Abra opencode.ai e copie o comando da caixa de instalação — curl -fsSL https://opencode.ai/install | bash — ou troque a aba para npm, bun ou brew. Se o OpenCode "não funciona" porque nunca chegou a instalar por completo, recomeçar desse comando oficial rende mais do que depurar um comando copiado pela metade.
A caixa de instalação do opencode.ai com abas curl, npm, bun e brewAssistir em 0:08 - 2
Rode o instalador em um shell Bash, não no PowerShell
O script de instalação foi escrito para Bash. Colado no PowerShell, produz Invoke-WebRequest: A parameter cannot be found that matches parameter name 'fsSL', exatamente como capturado na gravação. A correção mostrada na tela: definir terminal.integrated.defaultProfile.windows como Git Bash no settings.json do IDE para que o comando caia em um shell Bash.
O erro -fsSL lançado pelo PowerShell, ao lado da configuração de perfil padrãoAssistir em 1:32 - 3
Corrija "opencode: command not found" estendendo o PATH
A instalação termina mas o terminal continua dizendo bash: opencode: command not found — a pasta do binário nunca chegou ao PATH. Na gravação, adiciona-se o diretório .opencode/bin com export PATH=/c/Users/<you>/.opencode/bin:$PATH no Git Bash e roda-se o opencode de novo — o mesmo export vai no ~/.bashrc para valer sempre.
command not found, o export do PATH e a nova tentativa que funcionaAssistir em 4:32 - 4
Rode o instalador de novo no Git Bash e confirme
Com o Git Bash como perfil padrão, rode curl -fsSL https://opencode.ai/install | bash outra vez e deixe terminar. Dá para instalar via npm com npm install -g opencode-ai, ou com choco e scoop no Windows. Reabra o terminal depois para o PATH atualizado valer.
Git Bash como perfil padrão enquanto o comando de instalação roda de novoAssistir em 2:30
Tela preta e travadas na inicialização
- 5
Reconheça a inicialização de tela preta
Segundo modo de falha: você digita opencode, o título da janela muda e o corpo fica preto — sem banner, sem prompt. A gravação mostra exatamente essa janela morta no Windows 11. Sua digitação não tem nada a ver: é o estado no disco ou um processo travado impedindo a TUI de renderizar.
A janela preta do Prompt de Comando logo após abrir o opencodeAssistir em 0:09 - 6
Apague a pasta de dados corrompida
A correção mostrada na gravação: feche o OpenCode, encerre instâncias travadas no Gerenciador de Tarefas e apague a pasta de dados AppData\Local\share\opencode (em macOS e Linux é ~/.local/share/opencode). Ela guarda auth.json, logs e estado de projetos, então você precisará autenticar de novo depois — um preço pequeno por uma TUI que funciona.
A pasta de dados do opencode em AppData\Local\share antes da exclusãoAssistir em 0:28 - 7
Reabra e confirme que a TUI renderiza
Rode opencode mais uma vez. A cena seguinte da gravação é a UI de terminal saudável — banner, prompt Ask anything e a dica "Run /connect to add an AI provider and start coding". Se a janela continua escura, abra com opencode --print-logs e confira o arquivo mais recente na pasta log/ em busca da linha que falha.
A TUI do OpenCode restaurada após a limpeza do estadoAssistir em 1:09
Provedores, modelos e problemas de IDE
- 8
Leia a mensagem de limite gratuito antes de trocar
Quando a cota de um modelo incluso esgota, a sessão mostra um banner vermelho "Free usage exceeded, subscribe to Go [retrying…]" e para de responder. Não é um crash — a gravação mostra a sessão se recuperando no instante em que outro modelo é selecionado; leia a mensagem como sinal para ir ao passo 9.
O banner Free usage exceeded e a linha do modelo atualAssistir em 0:36 - 9
Abra o seletor de modelos e escolha outro
Rode /models na sessão (ou opencode models no shell) para listar tudo que os provedores conectados oferecem. Na gravação, escolhe-se outro modelo marcado como Free do catálogo do OpenCode Zen; qualquer modelo para o qual você tenha credenciais vale, incluindo Claude, GPT ou Gemini depois de conectar com /connect.
O seletor Select model com modelos marcados Free e provedoresAssistir em 0:12 - 10
Escolha uma variante de reasoning effort se for oferecida
Alguns modelos abrem um segundo diálogo Select variant com as opções Default, minimal, medium, high e xhigh, como capturado na gravação. Esforços menores respondem mais rápido e custam menos; guarde o high para refactors espinhosos. A escolha vale para a sessão atual, então é um experimento seguro.
Select variant com opções de reasoning de minimal a xhighAssistir em 0:20 - 11
Confirme a troca na barra de status
A barra de status abaixo do prompt nomeia o modelo ativo — na gravação, após a troca ela mostra Build · Muse Spark 1.2 Free · OpenCode Zen · xhigh, e o painel de contexto exibe tokens usados e $0.00 gastos. Se um erro teimoso persiste mesmo no modelo novo, reautentique com /connect e verifique com opencode auth list.
A barra de status confirmando o modelo e o effort trocadosAssistir em 0:30 - 12
Integre o OpenCode ao VS Code
Para a cara de "não funciona no VS Code": abra o terminal integrado, rode opencode, e a extensão do OpenCode se instala automaticamente — a gravação mostra opencode for VS Code by SST na lista Installed. Depois, Ctrl+Esc abre o OpenCode em um terminal dividido; se falhar, busque "OpenCode" no Marketplace de extensões e instale manualmente.
A extensão opencode instalada e as instruções de execução do instaladorAssistir em 3:02
Ainda quebrado? Siga o checklist
Se os três estágios acima não cobriram seu sintoma, estes são os padrões de falha restantes — cada um mapeado para a documentação oficial para você corrigir a causa, não o sintoma.
- 1Ainda "not recognized" depois de instalar — todo terminal aberto guarda o PATH antigo. Feche e reabra o shell, e ponha a linha de export no ~/.bashrc (ou ajuste o PATH do Windows nas Propriedades do Sistema) para sobreviver a reinícios. Usuários de npm: confira se a pasta bin global do npm também está no PATH.
- 2Não inicia de jeito nenhum — rode opencode --print-logs para ver a falha ao vivo e leia o log mais recente em ~/.local/share/opencode/log/ (Windows: %USERPROFILE%\.local\share\opencode\log). Só ficam guardados os 10 últimos logs; o que importa é o mais novo. Se desconfiar de binário desatualizado, tente opencode upgrade.
- 3ProviderInitError ou "invalid or corrupted configuration" — a documentação manda apagar o diretório de dados (rm -rf ~/.local/share/opencode) e reautenticar com /connect. O mesmo remédio do conserto de tela preta do passo 6, só que chegando pela mensagem de erro.
- 4AI_APICallError no meio da sessão — limpe o cache de pacotes de provedores com rm -rf ~/.cache/opencode e reinicie para que os SDKs se reinstalem. Depois confira o opencode auth list; credenciais expiradas ou ausentes são a segunda causa mais comum.
- 5App desktop morta no Windows — atualize o runtime WebView2, feche por completo e reabra, e remova qualquer override próprio de server.port / OPENCODE_PORT. A documentação recomenda WSL para a experiência mais suave no Windows, o que também contorna a maioria dos problemas de perfil de terminal.
- 6Não mostra todos os modelos — o /models só lista provedores conectados. Adicione um com /connect e organize o catálogo no opencode.json: defina "model": "provider/model-id" como padrão, esconda provedores com disabled_providers ou afine a lista de um provedor com a whitelist/blacklist dele.
Passar pela lista em ordem resolve a esmagadora maioria dos relatos de "opencode não funciona": primeiro PATH, depois estado, por último provedores e modelos. Quando nada adiantar, guarde o arquivo de log mais recente e abra uma issue no repositório do OpenCode — os mantenedores pedem o log, não um print.