Pular para o conteúdo

Como Instalar e Usar o OpenCode: Um Guia Completo

BlogsOpenCodeAITerminalCLIPor volta de 9 min

Como Instalar e Usar o OpenCode: Um Guia Completo

O OpenCode é um agente de codificação AI open-source que traz o poder da inteligência artificial diretamente para o seu terminal. Diferente das ferramentas tradicionais de codificação AI que vivem em editores ou navegadores, o OpenCode oferece uma interface baseada em terminal, aplicativo desktop e extensão para IDE—tudo projetado para tornar você mais produtivo como desenvolvedor. Este guia completo vai te acompanhar em tudo que você precisa saber para instalar, configurar e usar o OpenCode de forma eficaz.

O que é o OpenCode?

O OpenCode é um assistente de codificação com AI que ajuda você a:

  • Escrever código mais rápido com geração e completamento inteligente de código
  • Depurar eficientemente analisando erros e sugerindo correções
  • Entender bases de código através de consultas em linguagem natural
  • Adicionar funcionalidades com planejamento e implementação automatizados
  • Revisar código com análise e sugestões alimentadas por AI
  • Automatizar fluxos de trabalho usando agentes AI e ferramentas customizadas

Ele suporta múltiplos provedores de LLM incluindo Anthropic, OpenAI, Google e outros, dando flexibilidade para escolher os modelos que melhor atendem suas necessidades.

Requisitos do Sistema

Pré-requisitos

Antes de instalar o OpenCode, certifique-se de ter:

  1. Emulador de Terminal Moderno (para uso do TUI):

  2. Node.js (para instalação via npm/bun/pnpm/yarn):

    • Node.js v18 ou superior recomendado

  3. Chaves API para provedores de LLM:

    • Chave da API Anthropic (para modelos Claude)
    • Chave da API OpenAI (para modelos GPT)
    • Ou chaves de outros provedores suportados

Métodos de Instalação

Método 1: Script de Instalação (Recomendado)

A forma mais rápida de instalar o OpenCode é usando o script oficial de instalação:

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

Este método funciona em macOS, Linux e Windows (com Git Bash ou WSL).

Método 2: Usando Gerenciadores de Pacotes Node.js

Usando npm:

npm install -g opencode-ai

Usando Bun:

bun install -g opencode-ai

Usando pnpm:

pnpm install -g opencode-ai

Usando Yarn:

yarn global add opencode-ai

Método 3: Usando Homebrew (macOS & Linux)

brew install opencode

Método 4: Usando Paru (Arch Linux)

paru -S opencode-bin

Método 5: Instalações para Windows

Usando Chocolatey:

choco install opencode

Usando Scoop:

scoop bucket add extras
scoop install extras/opencode

Usando Mise:

mise use -g github:sst/opencode

Método 6: Docker

Para uso conteinerizado:

docker run -it --rm ghcr.io/sst/opencode

Método 7: Download do Binário

Você pode baixar o binário pré-compilado diretamente na página de GitHub Releases.

Verificar a Instalação

Após a instalação, verifique se está funcionando:

opencode --version

Você deve ver o número da versão exibido.

Configuração Inicial

Conectando ao OpenCode Zen (Recomendado para Iniciantes)

OpenCode Zen é uma lista selecionada de modelos testados e verificados pela equipe OpenCode. É a forma mais fácil de começar.

  1. Inicie o OpenCode:
cd /caminho/do/seu/projeto
opencode
  1. Execute o comando connect no TUI:
/connect

  1. Selecione "opencode" na lista de provedores

  2. Visite a URL de autenticação: opencode.ai/auth

  3. Faça login e adicione dados de pagamento (ou use créditos gratuitos, se disponíveis)

  4. Copie sua chave API e cole no terminal quando solicitado

Conectando a Outros Provedores

Você também pode conectar o OpenCode a outros provedores de LLM:

Usando o comando /connect:

/connect

Selecione seu provedor preferido (Anthropic, OpenAI, Google, etc.) e siga o fluxo de autenticação.

Usando autenticação CLI:

opencode auth login

Este comando guia você na configuração das chaves API para qualquer provedor disponível em Models.dev.

Listar provedores configurados:

opencode auth list

ou versão curta:

opencode auth ls

Logout de um provedor:

opencode auth logout

Configurando o Contexto do Projeto

Depois de configurar um provedor, inicialize o OpenCode para seu projeto:

  1. Navegue até seu projeto:
cd /caminho/do/seu/projeto
  1. Inicie o OpenCode:
opencode
  1. Execute o comando init:
/init

Isso analisa a estrutura do projeto e cria um arquivo AGENTS.md na raiz. Esse arquivo ajuda o OpenCode a entender seus padrões de codificação, frameworks e arquitetura do projeto.

Dica: Faça commit do arquivo AGENTS.md no Git. Isso ajuda a manter a consistência na equipe e melhora o entendimento do OpenCode sobre seu projeto com o tempo.

Usando a Interface de Usuário no Terminal (TUI)

O TUI do OpenCode oferece uma experiência interativa no terminal.

Iniciando o TUI

Basta executar:

opencode

Ou com flags opcionais:

# Continuar a última sessão
opencode --continue

# Continuar uma sessão específica
opencode --session <session-id>

# Iniciar com um prompt
opencode --prompt "Explique esta base de código"

# Usar um modelo específico
opencode --model anthropic/claude-sonnet-4-5

# Usar um agente específico
opencode --agent plan
  • Scroll: Use a roda do mouse ou as setas do teclado
  • Alternar modos: Pressione Tab para alternar entre modo Plan e modo Build
  • Executar comandos: Digite / para acessar a paleta de comandos
  • Buscar arquivos: Use @ para busca fuzzy em arquivos do projeto
  • Sair: Pressione Ctrl+C ou use /exit

Fazendo Perguntas

Você pode fazer perguntas ao OpenCode sobre seu código:

Como a autenticação é tratada em @packages/functions/src/api/index.ts

Use o símbolo @ para referenciar arquivos específicos. O OpenCode vai analisar esses arquivos e fornecer explicações detalhadas.

Adicionando Funcionalidades

O OpenCode é ótimo para adicionar novas funcionalidades por meio do seu fluxo de trabalho em dois modos:

Passo 1: Modo Plan

  1. Troque para o modo Plan pressionando Tab
  2. Descreva o que você deseja:
Quando um usuário deletar uma nota, queremos marcá-la como deletada no banco de dados.
Depois criar uma tela que mostre todas as notas deletadas recentemente.
Dessa tela, o usuário pode restaurar uma nota ou deletá-la permanentemente.
  1. Revise o plano sugerido
  2. Faça iterações com feedback:
Gostaríamos de desenhar essa nova tela usando um design que já usei antes.
[Imagem #1] Veja essa imagem e use como referência.

Dica: É possível arrastar e soltar imagens no terminal. O OpenCode irá escanear e analisar as imagens.

Passo 2: Modo Build

  1. Troque para o modo Build pressionando Tab novamente
  2. Aprove a implementação:
Perfeito! Pode seguir e fazer as alterações.

O OpenCode então implementará a funcionalidade, criando e modificando arquivos conforme necessário.

Fazendo Alterações Diretas

Para mudanças simples, você pode pular a fase de planejamento:

Precisamos adicionar autenticação na rota /settings.
Veja como isso é tratado na rota /notes
em @packages/functions/src/notes.ts e implemente a mesma lógica
em @packages/functions/src/settings.ts

Desfazer e Refazer Alterações

Cometeu um erro? Use o comando desfazer:

/undo

Isso reverte o último conjunto de alterações e permite refinar seu prompt.

Para refazer alterações desfeitas:

/redo

Você pode usar /undo várias vezes para reverter múltiplas alterações.

Comandos CLI

O OpenCode oferece um CLI poderoso para acesso programático e automação.

Executando Prompts Diretos

Execute o OpenCode de forma não interativa:

opencode run "Explique como closures funcionam em JavaScript"

Útil para scripts, automação, ou respostas rápidas sem abrir o TUI.

Gerenciando Modelos

Liste todos os modelos disponíveis:

opencode models

Filtre por provedor:

opencode models anthropic

Atualize o cache de modelos (útil quando novos modelos são adicionados):

opencode models --refresh

Mostre informações detalhadas dos modelos incluindo custos:

opencode models --verbose

Iniciando um Servidor Headless

Inicie um servidor HTTP para acesso via API:

opencode serve

Com porta customizada:

opencode serve --port 3000

Útil para integrar o OpenCode em aplicações web ou para respostas mais rápidas em scripts (evitando cold boot do servidor MCP).

Conectando a um Servidor

Em um terminal, inicie o servidor:

opencode serve

Em outro terminal, conecte-se para execução mais rápida:

opencode run --attach http://localhost:4096 "Explique async/await em JavaScript"

Gerenciando Agentes

Crie um novo agente customizado:

opencode agent create

Este comando guia você na criação de um agente com prompts de sistema customizados e configuração de ferramentas.

Integração com GitHub

Instale o agente GitHub para automação no repositório:

opencode github install

Isso configura workflows GitHub Actions para revisão automática de código e manipulação de issues.

Atualizando o OpenCode

Atualize para a versão mais recente:

opencode upgrade

Ou para uma versão específica:

opencode upgrade v0.1.48

Especifique o método de instalação se necessário:

opencode upgrade --method brew

Configuração

O OpenCode suporta configuração flexível por meio de arquivos JSON.

Locais de Configuração

Arquivos config são mesclados (não substituídos), permitindo configs globais, específicas do projeto e customizadas.

  1. Config Global: ~/.config/opencode/opencode.json

    • Para temas, provedores, keybinds e configurações gerais

  2. Config de Projeto: opencode.json na raiz do projeto

    • Para provedores, agentes ou configurações específicas do projeto
    • Seguro para versionar no Git

  3. Config Customizada por Path: Definida pela variável de ambiente OPENCODE_CONFIG

  4. Config Customizada por Diretório: Definida pela variável de ambiente OPENCODE_CONFIG_DIR

Exemplo Básico de Configuração

Crie um arquivo config com esta estrutura:

{
  "$schema": "https://opencode.ai/config.json",
  
  // Seleção do tema
  "theme": "opencode",
  
  // Modelo principal a ser usado
  "model": "anthropic/claude-sonnet-4-5",
  
  // Modelo menor para tarefas leves
  "small_model": "anthropic/claude-haiku-4-5",
  
  // Configuração de auto-atualização
  "autoupdate": true
}

Configurando Provedores

Configure chaves API diretamente na config:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Recomenda-se usar variáveis de ambiente para segurança. Use a sintaxe {env:NOME_VARIAVEL}.

Usando Referências a Arquivos

Também é possível referenciar arquivos para dados sensíveis:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Comandos Customizados

Defina comandos customizados para tarefas repetitivas:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Execute a suíte completa de testes com relatório de cobertura e mostre falhas.\nFoque nos testes que falham e sugira correções.",
      "description": "Executar testes com cobertura",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Crie um novo componente React chamado $ARGUMENTS com suporte a TypeScript.\nInclua tipagem adequada e estrutura básica.",
      "description": "Criar um novo componente"
    }
  }
}

Use comandos customizados no TUI digitando /test ou /component MeuComponente.

Agentes Customizados

Crie agentes especializados:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Revisa código procurando boas práticas e problemas potenciais",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "Você é um revisor de código. Foque em segurança, performance e manutenibilidade.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Configuração de Permissões

Controle o que o OpenCode pode fazer sem pedir permissão:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Isso exige aprovação do usuário para operações de edição e bash.

Formatadores de Código

Configure formatadores para formatar o código automaticamente:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Configurações do TUI

Customize a interface do terminal:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

Recursos Avançados

Compartilhando Conversas

Compartilhe suas conversas com a equipe:

/share

Isso cria um link compartilhável e copia para seu clipboard. Conversas não são compartilhadas por padrão.

Configure o comportamento do compartilhamento:

{
  "share": "manual"  // "manual", "auto" ou "disabled"
}

Servidores MCP

Servidores Model Context Protocol (MCP) ampliam as capacidades do OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/caminho/para/arquivos/autorizados"]
    }
  }
}

Instruções e Regras

Forneça instruções específicas do projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

O OpenCode usará esses arquivos para entender padrões e convenções de codificação do projeto.

Variáveis de Ambiente

Configure o OpenCode usando variáveis de ambiente:

# Compartilhar sessões automaticamente
export OPENCODE_AUTO_SHARE=true

# Caminho para config customizada
export OPENCODE_CONFIG=/caminho/para/config.json

# Caminho para diretório de configs
export OPENCODE_CONFIG_DIR=/caminho/para/config-dir

# Desabilitar auto-atualização
export OPENCODE_DISABLE_AUTOUPDATE=true

# Desabilitar plugins padrão
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# Habilitar modelos experimentais
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Habilitar busca web Exa
export OPENCODE_ENABLE_EXA=true

Recursos Experimentais

Ative recursos experimentais:

export OPENCODE_EXPERIMENTAL=true

Recursos experimentais específicos:

# Habilitar descoberta de ícones
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# Desabilitar cópia ao selecionar no TUI
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# Definir limite máximo para saída de comandos bash
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# Definir timeout padrão para comandos bash (ms)
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000

Melhores Práticas

Prompting Eficaz

  1. Seja específico: Dê instruções claras e detalhadas
  2. Use contexto: Referencie arquivos com @ para melhor entendimento
  3. Forneça exemplos: Mostre exemplos do que deseja
  4. Divida em etapas: Tarefas complexas funcionam melhor em passos

Trabalhando com Projetos Grandes

  1. Use /init: Deixe o OpenCode entender a estrutura do projeto
  2. Referencie arquivos específicos: Use @ para limitar contexto
  3. Use modo Plan: Revise planos antes da implementação
  4. Mudanças incrementais: Faça alterações pequenas e gerenciáveis

Otimização de Custos

  1. Use modelos menores: Configure small_model para tarefas leves
  2. Planeje antes de construir: Revise no modo Plan para reduzir iterações
  3. Comandos customizados: Defina fluxos eficientes para tarefas comuns
  4. Monitore uso: Confira os dashboards dos provedores para estatísticas de uso

Melhores Práticas de Segurança

  1. Nunca versionar chaves API: Use variáveis de ambiente
  2. Use permissões: Configure permission para exigir aprovação em operações sensíveis
  3. Revise mudanças: Sempre revise as alterações sugeridas pelo OpenCode
  4. Use chaves separadas: Crie chaves API específicas para o OpenCode com limites apropriados

Solução de Problemas

Problemas de Instalação

Problema: Comando não encontrado após a instalação

Solução:

  • Verifique a instalação: which opencode
  • Cheque o PATH: echo $PATH
  • Tente caminho completo: ~/.local/bin/opencode
  • Reinstale usando método alternativo

Problemas de Autenticação

Problema: Chave API não reconhecida

Solução:

  • Verifique se a chave está correta: opencode auth list
  • Cheque variáveis de ambiente: echo $ANTHROPIC_API_KEY
  • Reautentique: opencode auth login

Problemas de Performance

Problema: Respostas lentas

Solução:

  • Use opencode serve para execução mais rápida
  • Troque para um modelo mais rápido
  • Use janelas de contexto menores
  • Desabilite ferramentas não utilizadas na config

Problemas no TUI

Problema: Problemas de visualização no terminal

Solução:

  • Use um emulador de terminal moderno (WezTerm, Alacritty etc.)
  • Verifique se o terminal suporta cores 24-bit
  • Tente tema diferente
  • Desative aceleração de scroll se houver problemas

Problemas com Modelos

Problema: Modelo não encontrado

Solução:

  • Atualize lista de modelos: opencode models --refresh
  • Verifique se o provedor está configurado: opencode auth list
  • Confira formato do nome do modelo: provedor/modelo
  • Veja se o provedor tem o modelo disponível

Integrando o OpenCode no Seu Fluxo de Trabalho

Desenvolvimento Diário

  1. Manhã: Rode /init para sincronizar com as últimas mudanças
  2. Trabalho em funcionalidades: Use modo Plan para design, depois modo Build para implementar
  3. Depuração: Faça perguntas sobre erros referenciando arquivos
  4. Revisão de código: Use agente customizado de revisão de código
  5. Documentação: Gere docs usando comandos customizados

Colaboração em Equipe

  1. Compartilhe configs: Faça commit de opencode.json e AGENTS.md no Git
  2. Compartilhe conversas: Use /share para discutir implementações
  3. Comandos customizados: Defina comandos específicos da equipe na configuração do projeto
  4. Agentes consistentes: Use definições de agentes compartilhadas para uniformidade

Integração CI/CD

  1. Agente GitHub: Instale para revisões automáticas de PRs
  2. Testes: Use comandos customizados em CI
  3. Qualidade de código: Configure formatadores e permissões

Conclusão

O OpenCode representa um novo paradigma no desenvolvimento assistido por AI ao trazer capacidades poderosas de inteligência artificial diretamente para o seu terminal. Com opções flexíveis de configuração, suporte a múltiplos provedores de LLM e uma interface TUI intuitiva, ele foi desenhado para aumentar sua produtividade sem interromper seu fluxo de trabalho atual.

Principais pontos:

  • Instale usando o script oficial ou seu gerenciador de pacotes preferido
  • Configure chaves API via /connect ou opencode auth login
  • Inicialize projetos com /init para melhor entendimento do contexto
  • Use o modo Plan para funcionalidades complexas, modo Build para mudanças diretas
  • Customize com arquivos config, comandos e agentes
  • Aproveite os comandos CLI para automação e scripting
  • Pratique bons hábitos de segurança com chaves API e permissões

Próximos passos:

Pronto para turbinar seu fluxo de desenvolvimento?
Confira as soluções de hosting otimizadas para AI da LightNode para deploy de aplicações movimentadas por AI com instâncias dedicadas de GPU e infraestrutura escalável.

O OpenCode é open source e está em constante evolução. Contribua com o projeto, reporte problemas ou compartilhe sua experiência para ajudar a torná-lo ainda melhor para todos. Boas codificações!

Economize Muito em VPS Barato