Guia técnico · 2026-07-11

OpenCode no Windows — Guia de instalação e configuração 2026

Guia completo de instalação e configuração do OpenCode no Windows 11 com WSL 2. Passo a passo, dicas de performance e troubleshooting para integrar com Claude Code.

Usar OpenCode no Windows sempre foi mais complicado do que deveria. Dependências quebradas, permissões do WSL mal configuradas, PATH ausente — cada obstáculo vira motivo para desistir e voltar para o ambiente Linux. A documentação oficial foca em macOS e Linux, deixando o usuário de Windows sem um roteiro claro. Mas a verdade é que o Windows 11, combinado com WSL 2, entrega tudo que o OpenCode precisa para rodar com desempenho de primeira. Este guia mostra o passo a passo para instalar, configurar e usar o OpenCode no Windows 11 sem frustração, resolvendo cada problema comum no caminho.

Imagem sugerida: Banner mostrando o OpenCode rodando dentro de um terminal no Windows 11 com WSL 2 ativo. Alt text: "OpenCode rodando no Windows 11 com WSL 2 — terminal exibindo sessão ativa do agente de IA."

Sumário

O problema: instalar OpenCode no Windows não é trivial

Se você pesquisou sobre instalar OpenCode no Windows, provavelmente encontrou tutoriais que pressupõem Linux ou macOS. A documentação oficial trata o suporte ao Windows como secundário, e isso gera dores de cabeça concretas:

  • WSL mal configurado: O OpenCode precisa do subsistema Linux. Se o WSL 2 não estiver com a distribuição correta, a instalação falha.
  • Problemas de PATH: O Node.js do Windows não é reconhecido dentro do WSL. Você instala, mas o OpenCode não encontra o runtime.
  • Permissões de diretório: O mapeamento entre NTFS e ext4 gera erros de "Permission denied" em arquivos de configuração.
  • Dependências conflitantes: Versões diferentes de Node.js entre Windows e WSL fazem o npx opencode simplesmente não responder.

Cada problema isolado é resolvível. Juntos, viram um paredão que afasta desenvolvedores que poderiam se beneficiar do agente.

Imagem sugerida: Print de tela mostrando um erro comum de instalação do OpenCode no Windows (ex: "command not found" ou "permission denied"). Alt text: "Erro comum ao tentar instalar OpenCode no Windows sem a configuração correta do WSL 2."

Pré-requisitos: Windows 11, WSL 2, Node.js e Git

Antes de começar, verifique se você tem os seguintes itens instalados e configurados:

  1. Windows 11 (build 22000 ou superior) — versões anteriores do Windows 10 podem funcionar, mas o WSL 2 tem melhor desempenho e estabilidade no Windows 11.
  2. WSL 2 com Ubuntu 22.04 LTS (ou superior) — siga o guia oficial da Microsoft para instalar o WSL se ainda não tiver configurado. O OpenCode roda dentro do subsistema Linux, e o Ubuntu é a distribuição mais testada.
  3. Node.js 18+ instalado dentro do WSL — essencial para executar o OpenCode via npx ou npm global.
  4. Git configurado — necessário para que o OpenCode entenda o contexto do repositório e analise diffs, commits e branches.
  5. Terminal Windows Terminal (recomendado) — oferece a melhor experiência com abas, perfis separados para WSL e PowerShell, e suporte a fontes Nerd Font.

Para verificar se o WSL 2 está ativo, abra o PowerShell como administrador e execute:

wsl --status wsl --set-default-version 2

A saída deve mostrar "Default Version: 2". Caso contrário, atualize com wsl --update.

Imagem sugerida: Tela do Windows Terminal com três abas abertas: PowerShell, WSL Ubuntu e uma sessão do OpenCode rodando. Alt text: "Windows Terminal com abas de PowerShell, WSL Ubuntu e OpenCode — configuração ideal para desenvolvimento."

Passo a passo de instalação do OpenCode

Com os pré-requisitos atendidos, a instalação do OpenCode no Windows leva menos de 5 minutos. Siga cada etapa com atenção.

1. Atualize o WSL e instale as dependências

Abra o terminal do WSL (Ubuntu) e execute:

sudo apt update && sudo apt upgrade -y sudo apt install -y curl git build-essential

2. Instale o Node.js via nvm (recomendado)

O gerenciador de versões nvm evita conflitos de permissão e facilita futuras atualizações:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 node --version # Deve exibir v20.x.x

3. Instale o OpenCode globalmente

Com o Node.js pronto, instale o OpenCode via npm:

npm install -g @opencode-ai/cli opencode --version # Verifica se a instalação foi bem-sucedida

Se preferir usar npx sem instalação global, o comando é:

npx @opencode-ai/cli --version

4. Configure a chave de API

O OpenCode precisa de uma chave de API para se conectar ao modelo. Defina como variável de ambiente no ~/.bashrc:

echo 'export ANTHROPIC_API_KEY="sua-chave-aqui"' >> ~/.bashrc source ~/.bashrc

Imagem sugerida: Sequência de três prints lado a lado: (1) instalação via npm, (2) verificação de versão, (3) configuração da chave de API no .bashrc. Alt text: "Passo a passo da instalação do OpenCode no WSL: npm install, version check e configuração da API key."

Configuração inicial e integração com Claude Code

Com o OpenCode instalado, a configuração inicial define como ele se comporta no seu fluxo de trabalho. A integração com Claude Code no Windows é um dos cenários mais poderosos: você pode usar Claude Code como o cérebro principal e OpenCode como executor especializado, ou vice-versa.

Arquivo de configuração do OpenCode

O OpenCode cria automaticamente um arquivo de configuração em ~/.config/opencode/config.json. Você pode personalizar:

{ "model": "claude-sonnet-4-20250514", "maxTokens": 4096, "systemPrompt": "Você é um engenheiro de software especializado em TypeScript e React. Prefira soluções simples e bem testadas.", "theme": "dark" }

Integrando com Claude Code

Se você também usa Claude Code, a integração é direta. Ambos compartilham a mesma chave de API Anthropic. Para alternar entre os dois agentes conforme a tarefa:

  • Use Claude Code para tarefas que exigem compreensão profunda de contexto, refatoração e arquitetura.
  • Use OpenCode para tarefas estruturadas, automações e execução de comandos repetitivos.

Dentro de uma ferramenta de orquestração como o Orquestra, você pode manter ambos rodando lado a lado no mesmo canvas, cada um responsável por uma parte do projeto.

Imagem sugerida: Canvas do Orquestra mostrando dois terminais lado a lado — um rodando Claude Code, outro rodando OpenCode — com linhas de conexão entre eles. Alt text: "Orquestração de OpenCode e Claude Code no Windows usando o canvas infinito do Orquestra."

Primeiro projeto com OpenCode no Windows

Vamos criar um projeto real para testar. Este exemplo usa OpenCode no Windows para gerar uma API REST em Node.js.

mkdir minha-api-opencode cd minha-api-opencode git init opencode "Crie uma API REST em Node.js com Express, uma rota GET /status e uma rota POST /mensagem. Inclua teste básico."

O OpenCode vai analisar o pedido, consultar o repositório Git recém-inicializado e gerar os arquivos necessários. Durante a execução, você pode interagir, pedir ajustes ou redirecionar o foco.

Depois que o código for gerado:

npm init -y npm install express node index.js

Acesse http://localhost:3000/status no navegador para ver a resposta. Se tudo funcionou, sua instalação do OpenCode no Windows está completa e operacional.

Imagem sugerida: Terminal exibindo a execução bem-sucedida do OpenCode gerando os arquivos do projeto, seguido do servidor Express rodando. Alt text: "OpenCode gerando API REST em Node.js no Windows — terminal mostra arquivos criados e servidor rodando."

Dica extra: projetos com Claude Code em paralelo

Para tarefas maiores, como criar o front-end enquanto o OpenCode gera o back-end, use o Orquestra para rodar os dois agentes simultaneamente. Cada um em seu terminal, cada um com seu contexto, tudo visível em um único canvas. Confira os planos e preços do Orquestra para saber qual se adequa ao seu time.

Dicas de performance e troubleshooting

Mesmo com a instalação correta, alguns problemas podem aparecer. Aqui estão as soluções mais comuns para OpenCode no Windows:

OpenCode não é encontrado após instalação

zsh: command not found: opencode

Solução: O npm global pode não estar no PATH do WSL. Adicione ao ~/.bashrc:

echo 'export PATH="$PATH:$(npm bin -g)"' >> ~/.bashrc source ~/.bashrc

Erro de permissão ao criar arquivos

Error: EACCES: permission denied

Solução: Certifique-se de que o projeto está dentro do sistema de arquivos do WSL (/home/user/...) e não em uma montagem do Windows (/mnt/c/...). O OpenCode lida melhor com ext4 do que com NTFS.

OpenCode lento para responder

Solução: O OpenCode depende de API externa. Verifique sua conexão com a internet e considere reduzir maxTokens na configuração. Modelos menores como claude-haiku respondem mais rápido para tarefas simples.

Conflito entre Node.js do Windows e do WSL

Solução: Sempre use o Node.js instalado dentro do WSL para rodar o OpenCode. O Node.js do Windows não é acessível de dentro do subsistema Linux. Use which node para confirmar que está no caminho correto.

WSL travando ou consumindo muita memória

Solução: Limite o uso de memória do WSL 2 criando o arquivo %USERPROFILE%\.wslconfig:

[wsl2] memory=4GB processors=2

Após salvar, reinicie o WSL com wsl --shutdown no PowerShell.

Imagem sugerida: Print do arquivo .wslconfig no Bloco de Notas com as configurações de limite de memória e processadores. Alt text: "Configuração do arquivo .wslconfig para limitar memória do WSL 2 a 4GB."

Perguntas frequentes

OpenCode funciona nativamente no Windows ou precisa de WSL?

O OpenCode precisa do WSL 2. Ele foi construído para ambientes Linux e depende de chamadas de sistema que não existem no kernel nativo do Windows.

Qual a diferença entre OpenCode e Claude Code?

Ambos são agentes de IA de terminal, mas com filosofias diferentes. Claude Code é o agente oficial da Anthropic, focado em contexto profundo e refatoração. OpenCode é open source e prioriza simplicidade. Muitos devs usam os dois em conjunto. Veja o guia sobre Claude Code e Codex no Windows para comparar.

OpenCode consome muitos recursos?

Não. O processamento pesado ocorre nos servidores da Anthropic. O consumo de RAM fica entre 100 MB e 200 MB.

Como atualizar o OpenCode no Windows?

Dentro do WSL: npm update -g @opencode-ai/cli. Verifique com opencode --version. Recomenda-se atualizar mensalmente.

OpenCode funciona com qualquer LLM ou só com Anthropic?

Atualmente funciona com modelos Anthropic (Claude). A arquitetura permite outros provedores no futuro, mas o ecossistema mais estável hoje é com Claude.

Preciso de GPU para rodar OpenCode no Windows?

Não. É um cliente de terminal que se conecta a APIs na nuvem. Qualquer notebook com Windows 11 e 8 GB de RAM roda sem dificuldade.

Comece a orquestrar seus agentes hoje

Agora que você sabe como instalar e configurar o OpenCode no Windows, o próximo passo é integrá-lo ao seu ecossistema de desenvolvimento. O verdadeiro ganho de produtividade vem quando múltiplos agentes trabalham juntos — OpenCode gerando código, Claude Code revisando, Codex testando — tudo no mesmo ambiente.

É exatamente isso que o Orquestra faz: um canvas infinito nativo para Windows 11 onde você orquestra OpenCode, Claude Code, Codex e qualquer outra CLI em terminais lado a lado. Sem abas, sem alt-tab, sem perder contexto.

Baixe o Orquestra gratuitamente por 7 dias e veja seus agentes trabalharem em sincronia pela primeira vez.

*Artigo atualizado em 11 de julho de 2026. Este post faz parte da série sobre orquestração de agentes de IA no Windows. Leia também o guia definitivo de orquestração de agentes de IA para uma visão completa do ecossistema.*

Pronto para orquestrar seus agentes?

Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.

Começar teste grátis