Atualize o opencode no Windows em 1 comando (2026)
TL;DR
- O update nativo do opencode falha em instalacoes via Scoop porque quem gerencia o binario e o gerenciador de pacotes — o caminho correto e atualizar pelo proprio Scoop.
- Um unico comando instala o Scoop atualizado, o opencode na ultima versao e configura 26 modelos gratuitos da NVIDIA; aqui, o salto de versao levou 16 segundos com 26/26 modelos preservados.
- O updater faz backup automatico do opencode.jsonc, confere a contagem de modelos depois do update e restaura sozinho se algo sumir; a chave gratuita sai de build.nvidia.com.
Nota Tecnica: Scripts e automacoes fornecidos tem fins exclusivamente educacionais. Teste sempre em ambiente controlado. O @CanalQb nao se responsabiliza por danos, perdas ou bloqueios decorrentes do uso indevido.
Transparencia de IA (Lei Felca nº 15.211/2025): este conteudo foi produzido com assistencia de IA e revisado, testado e validado na pratica pelo @CanalQb, com logs reais de execucao.
Por que o update nativo do opencode da erro no Windows?
O update nativo do opencode falha em instalacoes via Scoop porque o gerenciador de pacotes e o dono do binario: quem instala, versiona e substitui o executavel dentro de ~\scoop\apps\opencode e o Scoop. Quando o app tenta se auto-substituir, o arquivo esta em uso e a pasta pertence a outro processo. A atualizacao correta nasce de dentro do Scoop, com scoop update opencode.
O Scoop funciona com uma pasta por versao e um link current apontando para a ativa. Esse design e otimo para isolar versoes e reverter quando algo quebra, mas ele tem uma regra de ouro: ninguem substitui o executavel por fora. Quando o opencode tenta fazer isso sozinho, o Windows bloqueia o arquivo em uso e a atualizacao nativa morre com um erro generico que nao aponta o culpado.
Aqui esta o detalhe que quase ninguem percebe: o problema nao e sua maquina, sua internet nem o opencode. E o caminho de atualizacao. Vale para qualquer app gerenciado pelo Scoop — do Git ao 7-Zip, nenhum deles consegue se auto-atualizar por dentro. Quem entende esse mecanismo nunca mais perde tempo tentando o botao de update do app.
E o melhor? A solucao nao exige decorar comando nenhum. Veja agora como resolver em 1 comando so.
Como atualizar o opencode no Windows em 1 comando?
Abra o PowerShell e execute irm https://github.com/canalqb/opencode-update/releases/latest/download/install.ps1 | iex. Esse unico comando instala o Scoop se faltar, atualiza o proprio Scoop e os buckets, instala o opencode na versao mais recente se voce nao tiver, configura os 26 modelos gratuitos e deixa o comando opencode-update pronto no PATH. Depois disso, atualizar e digitar uma palavra em qualquer janela nova do PowerShell.
irm https://github.com/canalqb/opencode-update/releases/latest/download/install.ps1 | iexO que esse comando faz, na ordem, e verificado por um CI publico no GitHub — nada de caixa preta:
- Scoop atualizado: instala o gerenciador se ele nao existir e roda
scoop updatepara renovar o nucleo e os buckets. Assim o opencode ja sai da versao mais fresca do catalogo. - opencode na ultima versao: se o app nao existir, instala; se existir, garante o refresh para a release mais nova via Scoop. Se o opencode estiver aberto, o instalador pula o refresh na hora e te avisa do por que.
- 26 modelos gratuitos configurados: cria ou completa o
opencode.jsonccom o provider da NVIDIA e os 26 modelos recomendados, preservando o que ja existe no seu config e criando backup antes de qualquer merge. - Comando pronto: a ferramenta e implantada em
%LOCALAPPDATA%\Programs\opencode-updatee ganha uma entrada no PATH do usuario. A partir dai,opencode-updatevira o seu atalho de atualizacao permanente. - Nao interativo: o instalador nao pergunta nada e nao travar automacao. Todas as opcoes avancadas ficam em parametros opcionais, documentados no repositorio no GitHub.
Mas tem um porem: iex executa codigo remoto, e a regra de ouro e auditar antes. Nao confie em one-liner de fonte que voce nao conhece — nem em fonte conhecida sem olhar. Baixe, leia, depois rode:
irm https://github.com/canalqb/opencode-update/releases/latest/download/install.ps1 -OutFile install.ps1
notepad install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1Como configuro os 26 modelos gratuitos da NVIDIA?
Os modelos rodam na API integrate da NVIDIA, e a chave e gratuita: acesse build.nvidia.com, entre com sua conta e clique em "Get API Key". O instalador escreve os 26 modelos no opencode.jsonc e aceita sua chave de tres formas: parametro -NvidiaApiKey, variavel de ambiente NVIDIA_API_KEY ou resposta ao prompt em instalacao nova. Nenhuma chave fica armazenada no repositorio — ela vive apenas no seu arquivo local.
O conjunto cobre as familias que importam em 2026: GLM-5.3 (o modelo principal deste setup), Nemotron Super 49B e Ultra 253B, Llama 3.3 70B e 3.1 405B, DeepSeek V4 Pro e R1, Kimi K2 e K3, Qwen3 Coder 480B, Mistral Large 3 675B e Codestral, alem dos modelos rapidos como Nemotron Nano 8B e DeepSeek V4 Flash. A tabela completa com contextos e capacidade de reasoning esta no README do repositorio.
# opcao 1: parametro (salve o install.ps1 e rode com -File)
powershell -ExecutionPolicy Bypass -File .\install.ps1 -NvidiaApiKey "nvapi-..."
# opcao 2: variavel de ambiente antes do one-liner
$env:NVIDIA_API_KEY = "nvapi-..."
irm https://github.com/canalqb/opencode-update/releases/latest/download/install.ps1 | iex
# opcao 3: prompt — instalacao nova sem chave pergunta na hora
# (responder em branco mantem o placeholder para preencher depois)Aqui no @CanalQb, validamos que o fluxo de chave por variavel de ambiente e o mais comodo para quem repete a instalacao em varias maquinas. E se o seu config ja tem modelos proprios, o instalador nao sobrescreve nada: ele apenas relata quantos dos 26 recomendados voce ja tem e, com -ApplyModels, adiciona so os que faltam — com backup antes.
Como garantir que meus modelos sobrevivem ao update?
O updater copia o opencode.jsonc para opencode_backups\ antes de qualquer mudanca, junto com um backup_info.txt que grava versao, hash SHA-256 e contagem de modelos. Depois do update, ele compara o hash e o numero de modelos antes e depois; se qualquer modelo sumir, o backup volta automaticamente. E verificacao de integridade, nao promessa.
Mas nao acredite em mim: acredite no log. Esta e a saida real da atualizacao que rodei no meu setup, do 1.18.31 para o 1.19.0 — 16 segundos no total, com download de 59,3 MB:
[2026-10-12 05:07:57] Session started [2026-10-12 05:07:57] Current version: 1.18.31 [2026-10-12 05:07:57] Models configured before update: 26 [2026-10-12 05:07:57] STEP 1 OK - Backup saved to: opencode_backups\20261012_050757 [2026-10-12 05:08:12] scoop: opencode: 1.18.31 -> 1.19.0 [2026-10-12 05:08:12] scoop: 'opencode' (1.19.0) was installed successfully! [2026-10-12 05:08:13] Version updated: 1.18.31 -> 1.19.0 [2026-10-12 05:08:13] Models preserved: 26/26 [2026-10-12 05:08:13] RESULT: SUCCESS
Repare no detalhe que quase ninguem percebe: o Scoop atualiza os buckets, baixa a nova versao, desinstala a antiga e religa o current — tudo dentro do modelo dele, sem tocar no seu config. O updater nao interfere nesse processo; ele apenas fotografa o estado antes e depois e age se a foto mudar para pior. Aqui no @CanalQb, validamos que essa e a arquitetura certa: automacao que protege em vez de automacao que arrisca.
O que acontece se o opencode estiver aberto durante o update?
O updater detecta processos do opencode em execucao e aborta com seguranca, sem fechar nada por conta propria. Perder uma sessao de trabalho no meio de um refactoring custa mais caro do que alguns dias de versao atrasada. Para atualizar mesmo assim, use opencode-update -KillRunning, que exige confirmacao explicita antes de encerrar as sessoes.
Esse guard nasceu de um erro real: a primeira versao do script usava taskkill /F /IM opencode.exe — e encerrou a propria sessao de trabalho que eu estava usando para escreve-lo. Nenhuma perda irreversivel, mas a licao ficou: automacao que mata processos do usuario sem perguntar e um risco de producao disfarcado de conveniencia. O resultado e um updater que trata sua sessao aberta como cargo precioso, nao como obstaculo.
Como conferir tudo antes de atualizar (modo Check)?
Execute opencode-update -Check para um relatorio sem efeitos colaterais: ele mostra se o Scoop esta disponivel, a versao do opencode, quantos modelos estao configurados, a cobertura dos 26 recomendados e quantos processos estao rodando. Em maquinas sem Scoop, ele responde FAILED sem alterar arquivo algum. E a forma segura de validar o ambiente antes do update real.
opencode-update -Check[2026-10-12 09:38:10] CHECK MODE - report only, nothing will be changed [2026-10-12 09:38:10] scoop available : yes [2026-10-12 09:38:10] opencode installed : 1.19.0 [2026-10-12 09:38:10] models configured : 26 [2026-10-12 09:38:10] recommended models : 26/26 [2026-10-12 09:38:10] opencode running : 6 process(es) [2026-10-12 09:38:10] RESULT: SUCCESS - ready to update (run again without -Check)
E o insight que quase ninguem ve em automacao de pipeline: durante os testes deste projeto no GitHub Actions, um teste que passava reprovar o job. O motivo? O PowerShell 7 herda o exit code do ultimo processo nativo executado — o modo -Check do updater havia terminado com codigo 1 (Scoop ausente no runner) e contaminava o passo seguinte. A correcao foi um exit 0 explicito no final do teste. Esse padrao de bug aparece em qualquer pipeline Windows, e conhecer ele economiza horas de debug.
Existe diferenca entre opencode v1 e v2?
Sim. O Scoop tambem oferece o opencode v2 no pacote versions/opencode2, com configuracao incompativel com a v1. Este projeto atualiza o pacote principal (opencode, v1), que e o instalado na maioria das maquinas. A migracao para v2 e manual e documentada oficialmente em opencode.ai/v2/docs/migrate-v1.
Se voce depende do seu config atual de modelos, nao migrate por impulso: a incompatibilidade significa reconfigurar provider por provider. Para a maioria dos casos, manter a v1 atualizada e limpa (com este updater) e o caminho de menor risco — e a decisao de migrar fica onde deve estar: nas suas maos, com documentacao aberta.
Qual metodo de atualizacao escolher?
Existem tres caminhos: o botao nativo do app (que falha com Scoop), os comandos manuais do Scoop (que funcionam, mas nao protegem nada) e o updater deste post (que faz backup, verifica e restaura). A diferenca nao e so esforco — e nivel de protecao. A tabela abaixo resume o que cada metodo entrega.
| Metodo | Pre-requisito | Preserva modelos | Seguranca de sessao | Esforco |
|---|---|---|---|---|
| Update nativo do app | Instalacao manual (sem Scoop) | N/A | N/A | Falha via Scoop |
scoop update opencode manual | Decorar comandos e checar sozinho | Config nao e tocado, mas sem verificacao | Nenhuma | Medio |
opencode-update | 1 comando one-liner | Backup + verificacao + auto-restauracao | Aborta ou pede confirmacao | Minimo |
Este script foi otimizado para os leitores do blog do CanalQb: cada decisao — do guard de sessao ao modo Check — existe porque falhamos sem ela primeiro. Se quiser ir alem do Scoop, veja tambem os conteudos de PowerShell aqui do blog.
Perguntas Frequentes
Por que o update nativo do opencode da erro com Scoop?
Atualizar o opencode apaga meus modelos e minha chave de API?
O comando irm | iex e seguro para instalar?
Preciso de permissao de administrador para atualizar o opencode?
Como verificar o estado do opencode antes de atualizar?
Este updater funciona com o opencode v2?
Fontes e Referencias
- Repositorio canalqb/opencode-update (GitHub) — scripts, template dos 26 modelos e CI de validacao
- Documentacao oficial do opencode
- Scoop — gerenciador de pacotes para Windows
- NVIDIA Build — chave gratuita da API integrate
- Guia oficial de migracao do opencode v1 para v2
Gostou do tutorial? O repositorio com tudo — instalador, updater, template dos 26 modelos e CI — e o canalqb/opencode-update no GitHub. Assine o canal para acompanhar os testes reais que rodamos por aqui.
@CanalQb no YouTube — e confira tambem os conteudos de automacao aqui no blog.