OpenCode: instalação, modelos e primeiro arranque

O OpenCode é um agente de programação com IA de código aberto para o terminal: a ferramenta em si é gratuita (licença MIT) e pode ligar-lhe qualquer modelo — desde Claude e GPT até a um modelo local através do Ollama. O repositório do projeto já ultrapassou as duzentas mil estrelas no GitHub. A expressão «Claude Code gratuito com qualquer modelo» parece apelativa, mas precisa de ser clarificada: a ferramenta é gratuita; as condições de utilização dependem do modelo que escolher.

Segue-se tudo o que precisa de saber, de acordo com a documentação oficial: o que é a ferramenta, como a instalar em macOS, Linux ou Windows, como ligar um modelo e o que fazer no primeiro arranque. Há uma secção separada sobre custos, porque «gratuito» aqui aplica-se apenas à ferramenta: os modelos têm custos, e é isso que causa confusão com maior frequência.

A documentação contém informações práticas sobre como trabalhar com o Ailoot.

O que é o OpenCode, em termos simples?#

Em poucas palavras, o OpenCode faz o mesmo que o Claude Code: recebe uma tarefa em linguagem corrente e executa-a no seu projeto. Diferem em dois aspetos. O código é totalmente aberto, pelo que o pode ler e inspecionar. E a ferramenta não está associada a um único fornecedor de modelos: funciona com mais de 75 fornecedores, desde Anthropic e OpenAI até um modelo local executado no seu próprio hardware.

O projeto é desenvolvido pela equipa Anomaly. O repositório foi criado em 30 de abril de 2025 e, a 4 de outubro de 2026, tem mais de 211 mil estrelas e 28 mil forks (verificado através de um pedido à API do GitHub). A linguagem é TypeScript. A documentação é atualizada continuamente, pelo que as instruções abaixo se baseiam na versão atual.

Não confunda os nomes: o pacote npm da linha atual chama-se opencode-ai, o repositório é anomalyco/opencode e o comando do terminal é simplesmente opencode. Artigos mais antigos podem usar o endereço sst/opencode: a organização mudou de nome e a ligação antiga redireciona agora para a nova.

Atualizado a 4 de outubro de 2026: a equipa lançou o OpenCode 2.0, a nova geração principal da ferramenta. As instruções de instalação e ligação de modelos abaixo continuam a referir-se à linha atual 1.x (instalada com o comando curl -fsSL https://opencode.ai/install | bash; a versão atual a 30 de setembro de 2026 é a 1.18.34): continua a ser suportada ativamente e é a versão instalada pela documentação oficial em opencode.ai/docs. Uma secção separada, mais abaixo, explica exatamente o que mudou na segunda versão e quando mudar para ela.

Em que difere o OpenCode do Claude Code e do Codex?#

Se já tiver uma subscrição Claude, faz sentido manter o Claude Code como ferramenta principal — temos um guia de instalação detalhado. O OpenCode é uma boa opção em três casos: se quiser trabalhar através de uma subscrição ChatGPT Plus ou GitHub Copilot, executar um modelo local sem custos de API ou usar uma interface única para vários modelos. Também temos um artigo de análise e guia de instalação do Codex.

Se ainda estiver a escolher uma ferramenta, comece por esta visão geral: o que as pessoas usam para programar em 2026. E se já tiver o OpenCode instalado e precisar de o ligar a outros agentes no Devin Desktop através do ACP, consulte o nosso guia para essa configuração.

O que mudou no OpenCode 2.0?#

A segunda versão é instalada com o comando curl -fsSL https://opencode.ai/v2/install | bash. De acordo com o guia oficial de migração (opencode.ai/v2/docs/migrate-v1), ambas as versões usam o mesmo comando opencode e, por predefinição, já não são instaladas lado a lado: o instalador da v2 substitui o binário da v1 e, antes de instalar a v2 através de um gestor de pacotes, a documentação pede explicitamente que remova primeiro a versão v1. No entanto, a configuração é lida a partir dos mesmos ficheiros — ~/.config/opencode/ e <project>/.opencode/ — pelo que as definições, os agentes e os servidores MCP são transferidos sem necessidade de reescrita. Há três coisas que têm de ser reescritas: os plugins (têm uma nova API), as integrações com a API do servidor (o protocolo mudou) e as definições do terminal (agora num único ficheiro partilhado cli.json, em vez de vários ficheiros tui.json).

As duas novidades mais importantes da v2 são as seguintes. Primeiro, foi lançado o Console — um serviço pago para equipas, com acompanhamento da utilização, orçamentos e políticas partilhadas por todos os membros. Segundo, a equipa anunciou finalmente o preço da subscrição Go: $10 por mês para o Go e $40 por mês para o Go Plus, com limites superiores (página opencode.ai/go, verificada a 4 de outubro de 2026). Anteriormente, a documentação dizia apenas «subscrição de baixo custo», sem indicar um valor.

Se é novo e só quer instalar o agente, siga as instruções abaixo; abrangem a primeira versão atual, recomendada pela própria documentação. Considere a v2 se precisar das novas funcionalidades dos plugins ou do Console para equipas — mas conte com ter de reescrever alguns plugins antigos para a nova API. Se tiver mais interesse numa aplicação de computador de código aberto que não exija um terminal, temos uma análise do ZCode, outro agente semelhante com a sua própria interface.

O que é necessário antes de instalar?#

Mais algumas palavras sobre o terminal, porque é o único ponto em que a instalação pode não correr como previsto. O OpenCode apresenta no terminal uma interface completa, com painéis e realce, pelo que a documentação pede um emulador moderno. Se a interface não tiver o aspeto esperado depois do arranque, instale primeiro uma das quatro opções indicadas: WezTerm (funciona em todos os sistemas), Alacritty, Ghostty ou Kitty. No Windows, a opção principal é utilizar o WSL; há uma secção própria mais abaixo.

A segunda coisa é um modelo. O OpenCode funciona através do modelo que lhe ligar: por si só, não processa pedidos. Há quatro opções: uma subscrição (ChatGPT Plus, GitHub Copilot, GitLab Duo), uma chave de API de qualquer fornecedor, o OpenCode Zen, o agregador da própria equipa, ou um modelo local através do Ollama. As quatro opções são explicadas na secção sobre como ligar um modelo.

Sem uma descrição do projeto, o agente tem de adivinhar os comandos de compilação, a estrutura de ficheiros e as convenções utilizadas — daí as «alucinações». O OpenCode usa um ficheiro AGENTS.md para isso. A mesma abordagem aplica-se ao Claude Code e a qualquer outro agente; só muda o nome do ficheiro de instruções.

Como instalar o OpenCode em macOS e Linux?#

A opção recomendada é o instalador oficial:

1. Execute o instalador

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

   O script deteta o seu sistema e descarrega o OpenCode. Se não conseguir encontrar o comando depois da instalação, feche e volte a abrir o terminal; o caminho será reconhecido na nova sessão.

2. Verifique se a instalação foi concluída corretamente

   opencode --version
   

   O comando devolve um número de versão, o que significa que a instalação foi bem-sucedida. A resposta «command not found» leva-o de volta ao primeiro passo: inicie uma nova sessão do terminal ou edite manualmente o PATH.

Se preferir gerir os pacotes por conta própria, estas são as opções:

brew install anomalyco/tap/opencode

npm install -g opencode-ai

O comando Homebrew começa deliberadamente por anomalyco/tap/: a documentação recomenda o tap próprio da equipa porque a equipa Homebrew atualiza menos frequentemente a fórmula para brew install opencode. O mesmo nome de pacote, opencode-ai, também funciona com bun, pnpm e yarn (bun install -g opencode-ai, yarn global add opencode-ai). Em Arch Linux, use sudo pacman -S opencode do repositório estável ou paru -S opencode-bin para obter a versão mais recente do AUR.

Atualize o OpenCode com opencode upgrade; quando é iniciado, também descarrega atualizações autonomamente se a atualização automática estiver ativada. Depois da atualização, confirme a versão com o conhecido opencode --version. A desinstalação também está integrada:

opencode uninstall

O comando mostra exatamente o que será eliminado e pede confirmação. Se quiser, pode manter a configuração e os dados das sessões: use as opções --keep-config e --keep-data.

Como instalar o OpenCode no Windows?#

A primeira opção recomendada pelos próprios programadores é o WSL. Instale-o com um único comando no PowerShell executado como administrador:

wsl --install

Depois de reiniciar, abra o Ubuntu no menu Iniciar e execute nele o comando habitual:

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

Os ficheiros nas unidades do Windows estão disponíveis no WSL através de /mnt/ — a unidade C: está em /mnt/c/ e a unidade D: em /mnt/d/. Por isso, pode abrir um projeto em C:\Users\Name\project desta forma:

cd /mnt/c/Users/Name/project
opencode

A segunda opção é ignorar o WSL e utilizar gestores de pacotes do Windows. No PowerShell:

choco install opencode

scoop install opencode

A terceira opção é a aplicação para computador e a versão Web. A aplicação instala-se como um programa normal e apresenta a interface numa janela, sem terminal. A versão Web é iniciada com o comando opencode web: abre o OpenCode num browser e a documentação também recomenda iniciá-la a partir do WSL, para evitar problemas de acesso aos ficheiros. A documentação também indica opções menos comuns — mise, Docker e um binário pronto a usar na página de lançamentos do GitHub. A instalação através do bun no Windows ainda está em curso; se o bun for o seu gestor de pacotes principal, use a opção npm.

Como ligar um modelo ao OpenCode?#

O OpenCode suporta mais de 75 fornecedores através do AI SDK e do Models.dev, além de modelos locais. A maioria é ligada com o comando /connect dentro da interface; para modelos locais, também é necessário indicar o endereço do servidor na configuração. As opções diferem quanto à forma de pagamento e aos requisitos do computador:

A documentação recomenda que os principiantes comecem pelo OpenCode Zen. A equipa selecionou modelos que funcionam bem especificamente como agentes e testou as respetivas combinações com fornecedores nas suas próprias tarefas.

A ligação funciona assim: introduza /connect, escolha OpenCode Zen, inicie sessão e adicione uma forma de pagamento em opencode.ai/auth, obtenha uma chave e cole-a. Depois, /models apresenta a lista de modelos recomendados. A 4 de outubro de 2026, a lista inclui, por exemplo, GPT 6.1 Sol, GPT 6 Astra, Claude Opus 5.5, Claude Sonnet 5, GLM 5.3 e Kimi K2.5. A documentação avisa honestamente que a lista não é exaustiva e fica rapidamente desatualizada, porque são lançados novos modelos todas as semanas.

As subscrições são ligadas com o mesmo comando /connect: escolha ChatGPT Plus ou GitHub Copilot na lista e inicie sessão na sua conta — não é necessária qualquer configuração adicional.

Se escolher Anthropic, /connect apresenta duas opções: introduzir manualmente uma chave de API ou escolher Claude Pro/Max e autenticar-se através do browser. No entanto, a Anthropic proíbe plugins de terceiros para utilizar uma subscrição Claude Pro/Max, e os plugins integrados deste tipo foram removidos do OpenCode a partir da versão 1.3.0. Se encontrar um artigo antigo sobre «OpenCode através de uma subscrição Claude», refere-se a esses plugins removidos, não a uma autorização oficial. As subscrições ChatGPT Plus, GitHub Copilot, GitLab Duo (assinalada como experimental) e Atomic Chat funcionam sem configuração adicional.

O OpenCode guarda no ficheiro ~/.local/share/opencode/auth.json as chaves que introduz através de /connect. Se não quiser escolher um modelo de cada vez, defina o modelo predefinido no ficheiro de configuração opencode.json, na raiz do projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

O formato é provider/model; ambos os identificadores aparecem na saída de /models.

Como ligar um modelo local através do Ollama?#

Esta opção não implica quaisquer custos de API: o modelo é executado no seu computador. Se estiver a escolher entre modelos gratuitos em geral, temos uma análise separada sobre quais funcionam razoavelmente bem como agentes e quais só o fazem em teoria. Para o OpenCode, instale o Ollama a partir do site oficial e descarregue um modelo:

ollama pull qwen3-coder

Um pormenor útil da documentação: o Ollama pode configurar-se automaticamente para o OpenCode; tem um guia de integração separado. Se preferir configurar tudo manualmente, adicione um fornecedor ao opencode.json com o endereço do seu servidor Ollama local:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder"
        }
      }
    }
  }
}

Depois, o comando /models na interface apresenta o modelo local na lista. Selecione-o e comece a trabalhar. Há uma ressalva prática na documentação: se o agente deixar de chamar ferramentas (editar ficheiros ou executar comandos), aumente num_ctx nas definições do Ollama — comece com valores entre 16k e 32k. Os modelos locais são mais fracos do que os modelos na nuvem especificamente no trabalho de agente, e um contexto pequeno agrava essa diferença. Se a versão local não for suficiente, pode ligar o Qwen na nuvem com uma chave; o guia como obter uma chave de API para o Qwen Code explica onde a obter.

Quanto custa o OpenCode e a sua utilização?#

Todos os custos aqui referidos são do modelo e há quatro cenários. Com uma chave de API ou o Zen, paga pela utilização real e o montante depende de quanto o agente trabalha. O Go é um plano de subscrição da equipa OpenCode para modelos abertos: $10 por mês para o Go e $40 por mês para o Go Plus, com limites superiores (verificado na página opencode.ai/go a 4 de outubro de 2026). O limite depende do modelo: por exemplo, o Go permite cerca de 110 pedidos por cada 5 horas (440 por mês) para o Kimi K3 e cerca de 26 000 pedidos por cada 5 horas para o DeepSeek V4.1 Flash, mais leve. Para aceder a um modelo específico acima do limite, a documentação apresenta um preço separado ($15 por mês para o Kimi K3, $60 para o Go Plus). Consulte a página da subscrição durante a ligação para ver a lista completa de modelos e limites. Com o ChatGPT Plus ou o Copilot, os pedidos estão cobertos pela subscrição que já paga; lembre-se apenas de que as subscrições têm os seus próprios limites de utilização intensiva. Por último, os pedidos a um modelo local através do Ollama não custam nada — mas precisa de um computador suficientemente potente para o executar rapidamente.

O que fazer no primeiro arranque?#

Primeiro arranque — dentro da pasta do projeto:

cd path/to/project
opencode

A interface abre com um campo de introdução. Primeiro, use o comando /init: o agente analisa os ficheiros importantes do repositório, faz algumas perguntas se necessário e cria um ficheiro AGENTS.md — um guia sobre a estrutura do projeto, os comandos a executar para compilar e testar e as convenções utilizadas. A documentação recomenda guardar este ficheiro no git; a partir daí, o OpenCode usa-o como instrução permanente para o projeto. Em termos de finalidade, AGENTS.md é um equivalente direto de CLAUDE.md no ecossistema OpenCode.

Em segundo lugar, use o modo Plan. A tecla Tab alterna entre os dois agentes principais: o Build tem acesso total a ficheiros e comandos, enquanto o Plan se destina a análise e planeamento — no modo Plan, as edições de ficheiros e os comandos bash requerem, por predefinição, a sua aprovação. Para tarefas novas, a documentação recomenda começar por um plano: leia o que o agente pretende fazer, ajuste a formulação e só depois volte ao Build com Tab.

A documentação deixa este conselho:

Quanto mais específica for a tarefa e mais contexto fornecer, menos trabalho terá de refazer. Adicione ficheiros a um pedido com @ — comece a escrever um nome e a interface irá encontrá-los através de pesquisa difusa. Pode arrastar imagens diretamente para o terminal, e uma mensagem que começa por ! é executada como comando da shell; o resultado é acrescentado ao contexto do agente. Se se enganou na tarefa ou o agente fez algo errado, /undo reverte as alterações e pode executá-lo várias vezes seguidas. Mudou novamente de ideias? /redo restaura o que foi revertido. E /share cria uma ligação para uma conversa, para a sua equipa; sem este comando, a conversa não é publicada em lado nenhum.

O que mais pode fazer o OpenCode?#

Comandos personalizados. Qualquer pedido recorrente pode tornar-se num comando: coloque um ficheiro markdown em .opencode/commands/, defina description, agent e model no respetivo frontmatter e escreva abaixo um modelo de pedido. Depois, chame o comando com /. Verificações do projeto antes de publicar, revisão de erros recentes, geração de uma migração — qualquer coisa que peça regularmente.

Subagentes. Além de Build e Plan, existem mais três: General para tarefas com várias etapas (acesso a todas as ferramentas, exceto à lista de tarefas), Explore para ler código rapidamente sem permissão para o editar e Scout para pesquisar bibliotecas externas. Chame-os mencionando-os com @ numa mensagem.

Servidores MCP. Ligue ferramentas externas através da secção mcp da configuração opencode.json — são suportados servidores locais e remotos. Cada servidor MCP adiciona as suas ferramentas ao contexto, e um servidor que consome muitos recursos, como o GitHub, pode esgotar o contexto muito rapidamente — ligue apenas os que precisa. Temos um guia com configurações prontas a usar sobre o conceito MCP; foi escrito para o Claude Code, mas o protocolo é partilhado.

Versão Web e servidor. opencode web abre a interface num browser. Para aceder a partir de outra máquina, use opencode serve --hostname 0.0.0.0 --port 4096; sempre que houver acesso à rede, defina uma palavra-passe através da variável OPENCODE_SERVER_PASSWORD. Sem palavra-passe, o servidor fica desprotegido.

O que fazer se a instalação correr mal?#

«opencode: command not found» depois da instalação. O terminal ainda não reconhece o novo caminho. Primeiro, feche-o e volte a abri-lo. Se isso não ajudar, descubra onde o instalador colocou o binário e adicione essa pasta ao PATH do terminal.

O modelo não responde ou apresenta um erro de autorização. Confirme se o fornecedor está ligado: introduza /connect e volte a autenticar-se. As chaves são guardadas em ~/.local/share/opencode/auth.json — se moveu a instalação de outro computador ou limpou pastas, o ficheiro pode estar em falta. A documentação aborda separadamente os erros ProviderInitError e AI_APICallError: no primeiro caso, volte a autorizar o fornecedor; no segundo, limpe a pasta ~/.cache/opencode e reinicie.

A interface está avariada: os painéis estão desorganizados ou aparecem caracteres ilegíveis em vez de símbolos. Comece por verificar o terminal. Instale uma das opções recomendadas — o WezTerm funciona nos três sistemas — e inicie o OpenCode a partir dela.

Se nada ajudar, consulte os registos: em macOS e Linux, estão em ~/.local/share/opencode/log/; no Windows, prima Win+R e introduza %USERPROFILE%\.local\share\opencode\log. São mantidos os dez ficheiros mais recentes; ative o registo detalhado com a opção opencode --log-level DEBUG. Com estes registos, pode comunicar um erro no repositório do projeto no GitHub.

Que outras perguntas fazem sobre o OpenCode?#

Abrir o Ailoot.