Categoria: OpenCode
Última revisão: setembro de 2026

Se você chegou até aqui depois de descobrir o OpenCode, provavelmente já entendeu o que ele faz e agora quer colocá-lo para funcionar no seu computador.

A boa notícia é que é possível usar o OpenCode no Windows. Para obter a melhor experiência, porém, a documentação oficial recomenda executar o OpenCode através do WSL (Windows Subsystem for Linux). Neste guia, você vai configurar o WSL, instalar o OpenCode, verificar se tudo está funcionando, abrir um projeto do Windows e fazer o primeiro teste.

Resumo rápido: Windows → WSL → OpenCode → seu projeto → configuração de um modelo de IA → primeiro teste.

O que você vai aprender neste guia

Ao terminar este tutorial, você deverá ser capaz de:

verificar se o seu Windows é compatível com o WSL;
instalar o WSL;
abrir e configurar uma distribuição Linux;
instalar o OpenCode dentro do WSL;
verificar se a instalação funcionou;
acessar arquivos armazenados no Windows;
abrir um projeto no OpenCode;
conectar um provedor ou modelo de IA;
fazer um primeiro teste;
identificar e corrigir os problemas mais comuns.

A ideia não é apenas executar um comando de instalação. O objetivo é terminar o tutorial com o OpenCode funcionando em um projeto real.

Antes de começar: o que você precisa

Não é necessário ser programador avançado para acompanhar este tutorial.

Você precisará de:

Item	Para que serve
Windows compatível com WSL	Executar o ambiente Linux
Conexão com a internet	Baixar o WSL, o OpenCode e acessar serviços de IA
PowerShell ou Windows Terminal	Instalar e administrar o WSL
Uma distribuição Linux	É onde o OpenCode será executado
Um projeto para testar	Permite verificar o funcionamento do OpenCode
Um provedor/modelo de IA	Necessário para utilizar os recursos de IA

Segundo a documentação atual da Microsoft, o comando simplificado de instalação do WSL pode ser utilizado no Windows 10 versão 2004 ou superior (build 19041 ou superior) e no Windows 11.

Uma distinção importante

Existem duas coisas diferentes neste processo:

Instalar o OpenCode
e
ter acesso a um modelo de inteligência artificial para utilizá-lo.

O OpenCode é o agente de programação. Os modelos de IA são fornecidos por diferentes provedores, e as condições de acesso podem variar.

Portanto, instalar o OpenCode não significa automaticamente que qualquer modelo disponível será gratuito.

O que é WSL?

WSL significa Windows Subsystem for Linux, ou Subsistema do Windows para Linux.

Em termos simples, ele permite executar um ambiente Linux dentro do Windows, sem precisar instalar o Linux como sistema operacional principal ou configurar uma máquina virtual tradicional.

A Microsoft descreve o WSL como uma forma de utilizar distribuições Linux, aplicativos Linux e ferramentas de linha de comando diretamente no Windows.

Para o nosso objetivo, pense na estrutura desta maneira:

SEU COMPUTADOR
      │
      ▼
   WINDOWS
      │
      ▼
     WSL
      │
      ▼
   LINUX
      │
      ▼
   OPENCODE
      │
      ▼
   SEU PROJETO

Isso pode parecer complicado inicialmente, mas depois que o WSL estiver configurado, o processo fica bastante simples.

Por que usar WSL com o OpenCode?

O OpenCode pode ser executado diretamente no Windows. Portanto, o WSL não é uma exigência absoluta.

Entretanto, a documentação oficial do OpenCode recomenda o WSL para usuários do Windows. Segundo a documentação, o WSL oferece melhor desempenho de sistema de arquivos, suporte completo ao terminal e maior compatibilidade com ferramentas de desenvolvimento utilizadas pelo OpenCode.

Por isso, este tutorial utiliza o WSL como caminho principal.

Windows direto ou WSL?

Característica	Windows direto	WSL
Funciona no Windows	Sim	Sim
Precisa instalar WSL	Não	Sim
Ambiente Linux	Não	Sim
Terminal Linux	Não	Sim
É o caminho recomendado pela documentação para Windows	Não	Sim
É o caminho usado neste tutorial	Não	Sim

O OpenCode também disponibiliza métodos de instalação diretamente no Windows, incluindo Chocolatey, Scoop, npm, Mise e download de binário.

Se você quiser utilizar uma dessas alternativas, veja a seção “Como instalar o OpenCode diretamente no Windows” mais adiante.

Passo 1 — Verifique a versão do Windows

Antes de instalar o WSL, confirme qual versão do Windows você está utilizando.

Pressione:

Windows + R

Digite:

winver

e pressione Enter.

Uma janela mostrará a versão instalada.

Para o método simplificado apresentado neste artigo, a Microsoft informa suporte a Windows 10 versão 2004 ou superior, build 19041 ou superior, ou Windows 11.

Checkpoint

Se o seu Windows atende a esses requisitos, você pode continuar.

Passo 2 — Instale o WSL

Agora vamos instalar o ambiente Linux.

Abra o PowerShell como administrador.

Você pode fazer isso procurando por:

PowerShell

no menu Iniciar e escolhendo a opção para executar como administrador.

Digite:

wsl --install

e pressione Enter.

A Microsoft informa que esse comando instala os componentes necessários do WSL e, por padrão, instala também uma distribuição Ubuntu.

O Windows poderá solicitar que você reinicie o computador.

Se isso acontecer, reinicie.

O que deve acontecer?

O processo pode levar alguns minutos.

Na primeira inicialização da distribuição Linux instalada, o sistema poderá realizar uma preparação inicial e solicitar a criação de um usuário e uma senha Linux.

Checkpoint

Você terminou esta etapa quando consegue abrir a distribuição Linux e visualizar um terminal.

E se `wsl --install` não funcionar?

Em alguns computadores, o WSL pode já estar instalado ou o comando pode apresentar uma situação diferente.

A própria Microsoft orienta que, se wsl --install mostrar apenas informações de ajuda, você pode verificar as distribuições disponíveis com:

wsl --list --online

e instalar uma distribuição específica utilizando:

wsl --install -d <NomeDaDistribuição>

A documentação também apresenta opções para situações em que a instalação fica parada ou quando é necessário utilizar métodos alternativos.

Não avance para a instalação do OpenCode se o WSL ainda não estiver funcionando corretamente.

Primeiro faça o ambiente Linux funcionar.

Passo 3 — Abra o terminal do WSL

Depois que o WSL estiver instalado, abra a distribuição Linux instalada.

Se o Ubuntu foi instalado automaticamente, você poderá encontrá-lo no menu Iniciar procurando por:

Ubuntu

Ao abrir pela primeira vez, pode aparecer um terminal semelhante a este:

seuusuario@seucomputador:~$

Esse é o terminal Linux que utilizaremos para instalar o OpenCode.

PowerShell e WSL não são a mesma coisa

Essa diferença é importante.

O PowerShell é o terminal do Windows.

O terminal do Ubuntu/WSL é o ambiente Linux.

Neste tutorial:

PowerShell → instalação do WSL

Terminal WSL → instalação e utilização do OpenCode

Passo 4 — Instale o OpenCode no WSL

Agora chegamos à instalação propriamente dita.

Dentro do terminal do WSL, execute:

curl -fsSL https://opencode.ai/install | bash

Esse é o método de instalação apresentado na documentação oficial do OpenCode para o ambiente WSL.

Aguarde o processo terminar.

Importante

Não execute esse comando no PowerShell para seguir este tutorial. Abra o terminal da sua distribuição Linux no WSL e execute o comando nele.

Passo 5 — Verifique se o OpenCode foi instalado

Depois da instalação, execute:

opencode

Se tudo estiver correto, o OpenCode deverá ser iniciado.

Esse é um dos momentos mais importantes do tutorial.

Você não precisa apenas confiar que a instalação terminou sem erros.

Vamos testar o programa de verdade.

✅ Checkpoint

Se o comando opencode inicia o programa, a instalação básica foi concluída.

OpenCode instalado, mas o comando não funciona?

Se você executar:

opencode

e receber algo semelhante a:

command not found

não entre em pânico.

Isso normalmente significa que o comando não está disponível no ambiente atual ou que a instalação não foi concluída como esperado.

Primeiro teste

Feche o terminal do WSL.

Abra novamente.

Depois execute:

opencode

Se ainda não funcionar, repita a instalação pelo método oficial e observe cuidadosamente qualquer mensagem de erro exibida no terminal.

Uma regra importante

Se houver uma mensagem de erro durante a instalação, não ignore o erro e continue o tutorial.

Copie a mensagem.

Ela normalmente dará uma pista importante sobre o problema.

Passo 6 — Acesse um projeto que está no Windows

Uma das grandes vantagens do WSL é que você não precisa obrigatoriamente mover todos os seus projetos para outro computador.

O WSL consegue acessar os discos do Windows através do diretório /mnt/.

Por exemplo:

C:

corresponde a:

/mnt/c/

D:

corresponde a:

/mnt/d/

A própria documentação do OpenCode apresenta essa estrutura para acessar projetos armazenados no Windows.

Exemplo prático

Imagine que você tenha um projeto localizado em:

C:\Users\SeuNome\Documents\meu-projeto

No WSL, o caminho correspondente será:

/mnt/c/Users/SeuNome/Documents/meu-projeto

Você pode entrar nele com:

cd /mnt/c/Users/SeuNome/Documents/meu-projeto

Depois confirme que está no local correto:

pwd

Você também pode listar os arquivos da pasta com:

ls

Se os arquivos do seu projeto aparecerem, está tudo certo.

Checkpoint

Se você consegue entrar na pasta do seu projeto e visualizar seus arquivos pelo terminal WSL, pode iniciar o OpenCode.

Passo 7 — Abra seu projeto no OpenCode

Agora execute:

opencode

O OpenCode será iniciado dentro do diretório do seu projeto.

Esse detalhe é importante.

O OpenCode não precisa ser iniciado em uma pasta aleatória.

O ideal é abrir o agente dentro do projeto que você deseja analisar ou modificar.

A documentação oficial segue justamente esse fluxo: navegar até o diretório do projeto e então executar opencode.

Uma forma simples de entender o fluxo

Você pode pensar assim:

1. Windows
      ↓
2. Abrir WSL
      ↓
3. Entrar na pasta do projeto
      ↓
4. Executar "opencode"
      ↓
5. OpenCode analisa o projeto

Esse conceito será muito importante quando você começar a utilizar o OpenCode de maneira mais avançada.

Passo 8 — Configure um provedor ou modelo de IA

Aqui existe uma distinção importante.

O OpenCode está instalado.

Mas agora precisamos configurar a origem dos modelos de IA que ele utilizará.

A documentação atual informa que o OpenCode suporta muitos provedores de modelos e também permite trabalhar com modelos locais.

Para adicionar um provedor, o OpenCode utiliza o comando:

/connect

Dentro da interface do OpenCode, digite:

/connect

O sistema apresentará as opções disponíveis.

Depois de configurar as credenciais de um provedor, você pode utilizar:

/models

para visualizar e selecionar modelos disponíveis.

Atenção aos custos

Não presuma que um modelo é gratuito apenas porque o OpenCode é open source.

O custo, limite de uso e forma de autenticação dependem do provedor e do modelo escolhido.

Alguns serviços possuem opções gratuitas ou limites gratuitos; outros exigem pagamento, créditos ou uma assinatura.

É por isso que vamos tratar esse assunto separadamente em futuros artigos do NextTechAI.

Passo 9 — Faça o primeiro teste

Agora vem a parte que realmente importa.

Você instalou o WSL.

Instalou o OpenCode.

Abriu seu projeto.

Configurou um provedor/modelo.

Agora faça uma solicitação simples.

Por exemplo:

Analise a estrutura deste projeto e explique quais são os principais arquivos e pastas.

Para um primeiro teste, prefira uma tarefa de leitura e análise, em vez de pedir imediatamente para o agente alterar dezenas de arquivos.

Isso facilita a identificação de problemas.

Se o OpenCode conseguir analisar o projeto e responder adequadamente, você terá confirmado o funcionamento básico do fluxo.

🎯 Checkpoint final

Se o OpenCode conseguiu acessar seu projeto, utilizar o modelo configurado e responder à sua solicitação, sua instalação está funcionando.

Onde ficam os arquivos do OpenCode?

Ao utilizar o OpenCode pelo WSL, algumas configurações e sessões ficam armazenadas no ambiente Linux.

A documentação do OpenCode indica, por exemplo, o caminho:

~/.local/share/opencode/

para dados de configuração e sessões.

Isso é diferente dos arquivos do seu projeto.

Seu projeto pode continuar armazenado no Windows, enquanto os dados do OpenCode ficam no ambiente WSL.

Preciso mover meus projetos para dentro do WSL?

Não necessariamente.

O WSL consegue acessar os arquivos armazenados nas unidades do Windows através de /mnt/c/, /mnt/d/ e outros pontos de montagem.

Por exemplo:

cd /mnt/c/Users/SeuNome/Documents/meu-projeto
opencode

Entretanto, a documentação do OpenCode observa que, para uma experiência mais fluida, pode ser interessante clonar ou copiar o repositório para o sistema de arquivos do próprio WSL, como:

~/code/

Isso é especialmente relevante para projetos maiores e fluxos de desenvolvimento mais intensivos.

Para começar, você pode manter seus projetos onde já estão e utilizar /mnt/c/.

Posso instalar o OpenCode diretamente no Windows?

Sim.

O OpenCode também oferece métodos de instalação diretamente no Windows.

A documentação oficial lista opções como:

choco install opencode

para Chocolatey,

scoop install opencode

para Scoop,

npm install -g opencode-ai

para npm.

Também existem opções envolvendo Mise, Docker e download do binário.

Apesar disso, para este tutorial optamos pelo WSL porque essa é a configuração recomendada pela documentação do OpenCode para obter a melhor experiência no Windows.

Problemas comuns

1. `wsl --install` não funciona

Primeiro confirme sua versão do Windows.

Depois tente:

wsl --list --online

Se uma distribuição estiver disponível, a Microsoft permite especificar qual distribuição deseja instalar:

wsl --install -d <NomeDaDistribuição>

Consulte a documentação atual da Microsoft se a instalação apresentar um erro específico.

2. O WSL foi instalado, mas o Ubuntu não abre

Verifique se o computador foi reiniciado quando solicitado.

Depois procure novamente pela distribuição instalada no menu Iniciar.

Você também pode verificar as distribuições disponíveis pelo PowerShell:

wsl --list --online

ou consultar o estado das distribuições instaladas com os comandos oficiais do WSL.

3. `opencode: command not found`

Primeiro confirme que você está realmente dentro do terminal WSL.

Depois:

feche o terminal;
abra novamente;
execute opencode.

Se continuar apresentando erro, repita a instalação e verifique as mensagens exibidas pelo instalador.

4. O OpenCode abre, mas não consigo usar um modelo

Nesse caso, o problema provavelmente não está na instalação do OpenCode.

Verifique se um provedor foi configurado.

Dentro do OpenCode, utilize:

/connect

Depois:

/models

O primeiro comando serve para configurar um provedor e suas credenciais; o segundo permite visualizar e selecionar modelos disponíveis.

5. Não consigo encontrar meus arquivos do Windows

Lembre-se da correspondência:

C: → /mnt/c/
D: → /mnt/d/

Por exemplo:

cd /mnt/c/Users/SeuNome/Documents

Depois use:

ls

para verificar o conteúdo da pasta.

6. Estou executando o OpenCode no PowerShell e algo está diferente

Este tutorial utiliza o OpenCode dentro do WSL.

Portanto, confira se você está no terminal da sua distribuição Linux.

O fluxo recomendado pela documentação para Windows é:

Windows
   ↓
WSL
   ↓
Diretório do projeto
   ↓
opencode

O que você NÃO precisa fazer

Para seguir este tutorial, não é necessário:

instalar uma máquina virtual tradicional;
instalar Linux como sistema operacional principal;
apagar seus projetos do Windows;
migrar imediatamente todos os arquivos para o WSL;
instalar dezenas de ferramentas antes de testar o OpenCode.

Comece pelo básico.

WSL → OpenCode → projeto → modelo → primeiro teste.

Depois você pode aprimorar seu ambiente.

OpenCode instalado: e agora?

Se você chegou até aqui e conseguiu fazer o primeiro teste, parabéns: a parte mais importante da instalação está concluída.

Mas instalar o OpenCode é apenas o começo.

Agora você precisa aprender a trabalhar com ele.

No próximo artigo do NextTechAI, vamos entrar justamente nessa etapa:

Como usar o OpenCode: guia passo a passo

Você verá como conversar com o agente, pedir que ele analise um projeto, criar e modificar arquivos, entender o que ele está fazendo e utilizar seus recursos de maneira mais eficiente.

Depois, o conteúdo pode avançar para temas como:

modelos gratuitos de IA;
OpenCode + Ollama;
execução de modelos localmente;
comparação entre diferentes ferramentas de programação com IA;
configuração avançada do OpenCode.

Resumo da instalação

Se você só quiser lembrar do caminho principal, é este:

WINDOWS
   │
   ▼
Instalar WSL
   │
   ▼
Abrir Ubuntu/WSL
   │
   ▼
Instalar OpenCode
   │
   ▼
curl -fsSL https://opencode.ai/install | bash
   │
   ▼
opencode
   │
   ▼
Entrar na pasta do projeto
   │
   ▼
Configurar provedor
   │
   ▼
Selecionar modelo
   │
   ▼
Fazer primeiro teste

O comando de instalação e a recomendação de usar WSL são baseados na documentação oficial atual do OpenCode.

Perguntas frequentes

O OpenCode funciona no Windows?

Sim. O OpenCode pode ser executado diretamente no Windows, mas sua documentação recomenda o WSL para obter a melhor experiência.

Preciso obrigatoriamente instalar o WSL?

Não. Existem métodos para instalar o OpenCode diretamente no Windows. O WSL é o caminho recomendado pela documentação para usuários do Windows.

O OpenCode é gratuito?

O OpenCode é um projeto de código aberto, mas isso não significa que todos os modelos ou provedores utilizados com ele sejam gratuitos.

As condições de acesso dependem do provedor e do modelo escolhido.

Preciso instalar Node.js?

Não necessariamente.

O método utilizado neste tutorial instala o OpenCode pelo instalador oficial dentro do WSL. Existem também métodos de instalação que utilizam npm, entre outras alternativas.

Posso usar meus projetos que estão no Windows?

Sim.

O WSL permite acessar as unidades do Windows por caminhos como /mnt/c/ e /mnt/d/.

Posso usar modelos locais?

Sim.

A documentação atual do OpenCode informa suporte a modelos locais, além de dezenas de provedores de modelos hospedados.

Posso usar o OpenCode sem pagar por um modelo?

Depende do provedor e do modelo escolhido.

O OpenCode e o modelo de IA são componentes diferentes. Alguns provedores oferecem opções gratuitas ou limites gratuitos, enquanto outros cobram pelo uso.

O que fazer se o OpenCode não encontrar meu projeto?

Primeiro confirme que você entrou no diretório correto usando:

pwd

ls

Se o projeto estiver no Windows, lembre-se de utilizar /mnt/c/ ou /mnt/d/, conforme a unidade em que ele estiver armazenado.

Conclusão

Instalar o OpenCode no Windows pode parecer complicado à primeira vista porque envolve duas camadas: o Windows e o ambiente Linux fornecido pelo WSL.

Na prática, porém, o processo pode ser resumido em poucos passos:

instalar o WSL → abrir o ambiente Linux → instalar o OpenCode → abrir seu projeto → configurar um provedor/modelo → fazer o primeiro teste.

A principal vantagem de seguir esse caminho é que você não termina apenas com o OpenCode instalado. Você termina com o ambiente preparado para começar a utilizá-lo em seus próprios projetos.

E essa é a diferença entre simplesmente instalar uma ferramenta e realmente começar a trabalhar com ela.

O que ler depois

Você acabou de instalar o OpenCode. Agora é hora de aprender a usá-lo.

→ Como usar o OpenCode: guia passo a passo

Depois:

→ OpenCode é gratuito? Entenda como funciona

→ Como usar modelos gratuitos de IA no OpenCode

→ Como rodar uma IA localmente no PC com Ollama

→ OpenCode + Ollama: como usar IA local para programar

Fontes oficiais

Documentação do OpenCode — Windows e WSL.
Documentação do OpenCode — instalação.
Documentação do OpenCode — modelos e provedores.
Microsoft Learn — instalação do WSL.
Microsoft Learn — comandos básicos do WSL.

O que você vai aprender neste guia

Antes de começar: o que você precisa

Uma distinção importante

O que é WSL?

Por que usar WSL com o OpenCode?

Windows direto ou WSL?

Passo 1 — Verifique a versão do Windows

Passo 2 — Instale o WSL

O que deve acontecer?

E se wsl --install não funcionar?

Passo 3 — Abra o terminal do WSL

PowerShell e WSL não são a mesma coisa

Passo 4 — Instale o OpenCode no WSL

Passo 5 — Verifique se o OpenCode foi instalado

OpenCode instalado, mas o comando não funciona?

Primeiro teste

Uma regra importante

Passo 6 — Acesse um projeto que está no Windows

Exemplo prático

Passo 7 — Abra seu projeto no OpenCode

Uma forma simples de entender o fluxo

Passo 8 — Configure um provedor ou modelo de IA

Atenção aos custos

Passo 9 — Faça o primeiro teste

Onde ficam os arquivos do OpenCode?

Preciso mover meus projetos para dentro do WSL?

Posso instalar o OpenCode diretamente no Windows?

Problemas comuns

1. wsl --install não funciona

2. O WSL foi instalado, mas o Ubuntu não abre

3. opencode: command not found

4. O OpenCode abre, mas não consigo usar um modelo

5. Não consigo encontrar meus arquivos do Windows

6. Estou executando o OpenCode no PowerShell e algo está diferente

O que você NÃO precisa fazer

OpenCode instalado: e agora?

Como usar o OpenCode: guia passo a passo

Resumo da instalação

Perguntas frequentes

O OpenCode funciona no Windows?

Preciso obrigatoriamente instalar o WSL?

O OpenCode é gratuito?

Preciso instalar Node.js?

Posso usar meus projetos que estão no Windows?

Posso usar modelos locais?

Posso usar o OpenCode sem pagar por um modelo?

O que fazer se o OpenCode não encontrar meu projeto?

Conclusão

O que ler depois

Fontes oficiais

Deixe um comentário Cancelar resposta

E se `wsl --install` não funcionar?

1. `wsl --install` não funciona

3. `opencode: command not found`