OpenCode não instala? Os erros comuns e as correções

Índice

• Primeiro: isto é um erro de instalação ou de conexão?
• Erro 1: error: opencode-ai's postinstall script was not run.
• Erro 2: brew install opencode não funciona
• Erro 3: command not found: opencode
• Erro 4: instalei no Ubuntu e não acho o pacote
• Erro 5: tenho a v1 e quero migrar para a v2
• Erro 6: o instalador pede permissões ou falha com EACCES
• Erro 7: a TUI abre mas o modelo não responde
• Erro 8: funcionava e acabou no meio da tarde
• Erro 9: instalei duas vezes e agora o comportamento é estranho
• Checklist rápido
• Continue lendo

Primeiro: isto é um erro de instalação ou de conexão?

Essa distinção economiza horas, e quase ninguém a faz.

Se a TUI abre — se você vê a interface do OpenCode no seu terminal — a instalação funcionou. Qualquer coisa errada a partir daí é configuração: a API key, o provedor, a cota. Não reinstale nada.

Se o comando não existe ou o instalador aborta, então realmente é a instalação, e siga lendo.

Erro 1: error: opencode-ai's postinstall script was not run.

Este é o erro mais pesquisado, e tem duas causas distintas que as pessoas confundem.

Causa A: seu gerenciador de pacotes bloqueou o script. O pacote npm usa um script postinstall confiável para baixar o binário nativo da sua plataforma. bun e pnpm não rodam scripts postinstall sem permissão explícita, por decisão de segurança. Se você instalou com qualquer um deles sem a flag, o pacote fica meio instalado: existe, mas sem binário.

# bun
bun install -g --trust @opencode/cli

# pnpm
pnpm add -g --allow-build=@opencode/cli @opencode/cli

Causa B: você está no pacote antigo. Olhe o nome no erro: opencode-ai. Esse é o pacote antigo. O do v2 é @opencode/cli. Se você seguiu um tutorial de 2025, instalou o errado.

npm uninstall -g opencode-ai
npm install -g @opencode/cli

Rode a desinstalação mesmo que ache que não o tem. Dois pacotes registrando o mesmo comando opencode no seu PATH produzem erros que não lembram em nada a causa.

Erro 2: brew install opencode não funciona

Não funciona porque não existe. A documentação do v2 é explícita: Homebrew, AUR, Scoop e Chocolatey não são suportados.

Se você pesquisou brew install anomalyco/tap/opencode e não chegou a lugar nenhum, o tap não está fora do ar: ele não é um canal oficial. O mesmo vale para qualquer .exe solto de um mirror.

Os canais que funcionam:

Rota	Comando
npm	npm install -g @opencode/cli
bun	bun install -g --trust @opencode/cli
pnpm	pnpm add -g --allow-build=@opencode/cli @opencode/cli
yarn	yarn global add @opencode/cli
Script oficial	curl -fsSL https://opencode.ai/v2/install | bash
Docker	ghcr.io/anomalyco/opencode com tag de versão

Qualquer tutorial que te entregue um brew install para o OpenCode é de 2025 ou de uma fonte não oficial. A lista atual está na documentação do OpenCode.

Erro 3: command not found: opencode

Quase nunca é a instalação. É o PATH.

1. Abra um novo terminal. Se você instalou com o script curl, o diretório pode não estar carregado na sua sessão atual.
2. Se preferir não fechar o terminal, recarregue o shell: source ~/.bashrc ou source ~/.zshrc.
3. Verifique onde o binário caiu: npm bin -g imprime o diretório global do npm. Se esse diretório não está no seu $PATH, adicione-o.

No Windows esse erro é mais comum porque o prefixo global do npm às vezes não acaba no PATH do sistema quando o Node é instalado. Esse é um problema do Node, não do OpenCode: conserte uma vez e conserta todos os pacotes globais que você tem.

Erro 4: instalei no Ubuntu e não acho o pacote

Não existe pacote apt ou snap. No Linux você instala exatamente como no macOS: via npm/bun/pnpm/yarn, ou com o script oficial do v2.

Se você usou o script curl no Ubuntu e o comando não aparece, volte ao erro 3: é o PATH. O script instala num diretório próprio que o seu shell precisa conhecer.

Erro 5: tenho a v1 e quero migrar para a v2

O salto de versão mudou o nome do pacote, e é isso que quebra o upgrade. Rodar npm update -g no pacote antigo não te leva à v2, porque são pacotes diferentes no registry.

npm uninstall -g opencode-ai
npm install -g @opencode/cli
opencode --version

Confira a versão no final. Se ela ainda reporta a antiga, você tem um binário órfão em outro diretório do PATH: ache com which -a opencode e apague o que não pertence.

Erro 6: o instalador pede permissões ou falha com EACCES

O clássico problema do npm global no Linux e macOS: o diretório global pertence ao root e seu usuário não pode escrever nele.

O conserto errado e tentador é sudo npm install -g. Funciona, mas deixa arquivos de root na sua home e vai causar problemas depois. O conserto certo é mudar o prefixo do npm para um diretório na sua própria home, ou usar um gerenciador de versões do Node como nvm, fnm ou volta, que instalam tudo sob sua home e eliminam o problema na raiz.

Erro 7: a TUI abre mas o modelo não responde

Repetindo o aviso do começo, porque é aqui que a maioria reinstala à toa: isto não é um erro de instalação.

Rode /connect dentro da TUI. Confira se a API key é a certa e se o provedor selecionado é aquele que você paga. Se você usa o Coding Plan da Z.ai, o endpoint importa: existe um compatível com Anthropic e um compatível com OpenAI, e escolher o errado significa que sua cota do plano nunca é debitada. Isso está coberto em a configuração do Z.ai Coding Plan.

Erro 8: funcionava e acabou no meio da tarde

Também não é bug. Esse é o teto de uso do seu plano.

O OpenCode Go aplica limites por janela de tempo, não uma cota mensal única. Se você secou no meio da tarde, bateu o teto da janela de 5 horas, não o mensal. Os números exatos e como eles se dividem estão em OpenCode Go: preço, limites de uso e se vale a pena.

Erro 9: instalei duas vezes e agora o comportamento é estranho

Sintomas: o comando reporta uma versão diferente da que você instalou, ou mudanças de config não têm efeito.

which -a opencode

Esse comando lista todos os caminhos onde o binário existe. Se ele devolve mais de um, você tem instalações concorrentes: tipicamente uma do npm e uma do script curl, ou uma de uma tentativa antiga de brew. Apague as que não quer e deixe uma única.

Checklist rápido

Se você não quer ler tudo o que está acima, esta é a ordem de diagnóstico:

1. A TUI abre? → o problema não é a instalação, é o /connect.
2. which -a opencode → se aparecer mais de um, limpe.
3. npm uninstall -g opencode-ai → remova o pacote antigo.
4. npm install -g @opencode/cli → instale o do v2.
5. Terminal novo → elimine o PATH.
6. No bun ou pnpm → adicione --trust ou --allow-build.
7. Nunca brew.

Continue lendo

• O tutorial completo: Como instalar OpenCode e programar com IA passo a passo
• Se o problema é cota: OpenCode Go: preço, limites de uso e se vale a pena
• Se o problema é o endpoint: Z.ai Coding Plan: base URL, API key e configuração