Início Rápido do OpenCode: Instale, Configure e Utilize o Agente de Codificação de IA no Terminal

Como Instalar, Configurar e Usar o OpenCode

Conteúdo da página

OpenCode é um agente de codificação com IA de código aberto que você pode executar no terminal (TUI + CLI), com superfícies opcionais para desktop e IDE. Este é o OpenCode Quickstart: instale, verifique, conecte um modelo provedor e execute fluxos de trabalho reais (CLI + API).

Nota de versão: OpenCode evolui rapidamente. Os comandos “mais recentes” aqui são estáveis, mas a saída e os valores padrão podem mudar — verifique sempre a documentação oficial da CLI e o registro de alterações (linkado abaixo).

Este artigo faz parte de Ferramentas de Desenvolvedor de IA: O Guia Completo para Desenvolvimento Impulsionado por IA.

O que é o OpenCode (e onde ele se encaixa)

O OpenCode foi projetado para codificação agent-first baseada no terminal, mantendo-se flexível em relação a provedores e modelos. Na prática, é uma camada de fluxo de trabalho que pode:

  • iniciar uma interface de terminal (TUI) quando você executa opencode
  • executar prompts “one-shot” não interativos via opencode run (scripts/automação)
  • expor um servidor HTTP headless via opencode serve (e uma interface web via opencode web)
  • ser controlado programaticamente via o SDK oficial JS/TS @opencode-ai/sdk

Se deseja compará-lo com outro assistente agent de código aberto que pode executar planos de várias etapas em um ambiente sandboxed, consulte OpenHands Coding Assistant QuickStart.

Para o agente baseado no terminal da Anthropic com a mesma história de “modelo local via HTTP” (Ollama ou llama.cpp, permissões, preços), veja Instalação e configuração do Claude Code para Ollama, llama.cpp, preços.

opencode com LLM qwen3.5 27b auto-hospedado

Pré-requisitos

Você precisará de:

  • Um emulador de terminal moderno (importante para a experiência TUI).
  • Acesso a pelo menos um modelo/provedor (chaves de API ou autenticação por assinatura, dependendo do provedor). Opções locais como Ollama ou llama.cpp funcionam sem chaves de API quando você executa um servidor compatível localmente.

Instalação do OpenCode (copiar e colar)

Script de instalação oficial (Linux/macOS/WSL):

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

Opções de gerenciador de pacotes (exemplos oficiais):

# Instalação global do Node.js
npm install -g opencode-ai

# Homebrew (recomendado pelo OpenCode para as versões mais atualizadas)
brew install anomalyco/tap/opencode

# Arch Linux (estável)
sudo pacman -S opencode

# Arch Linux (mais recente via AUR)
paru -S opencode-bin

Notas para Windows (o guia oficial recomenda comumente WSL para a melhor compatibilidade). Alternativas incluem Scoop/Chocolatey ou npm.

# chocolatey (Windows)
choco install opencode

# scoop (Windows)
scoop install opencode

Docker (útil para uma tentativa rápida):

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

Verificar a instalação

opencode --version
opencode --help

Formato da saída esperado (variará conforme a versão):

# Exemplo:
# <imprime um número de versão, ex. vX.Y.Z>
# <imprime ajuda com comandos/subcomandos disponíveis>

Conectar um provedor (duas práticas caminhos)

Caminho A: TUI /connect (interativo)

Inicie o OpenCode:

opencode

Em seguida, execute:

/connect

Siga os passos da interface para selecionar um provedor e autenticar (alguns fluxos abrem um navegador/login de dispositivo).

Caminho B: CLI opencode auth login (chaves do provedor)

O OpenCode suporta a configuração de provedores via:

opencode auth login

Notas:

  • As credenciais são armazenadas em ~/.local/share/opencode/auth.json.
  • O OpenCode também pode carregar chaves de variáveis de ambiente ou de um arquivo .env no seu projeto.

Hospedagem local de LLM (Ollama, llama.cpp)

O OpenCode funciona com qualquer API compatível com OpenAI. Para desenvolvimento local, muitos usuários executam Ollama e apontam o OpenCode para ele. Recentemente, tive uma experiência muito boa configurando e executando o OpenCode com llama.cpp em vez disso — o llama-server expõe endpoints compatíveis com OpenAI, então você pode usar modelos GGUF com o mesmo fluxo de trabalho. Se você prefere controle mais granular sobre memória e tempo de execução, ou deseja uma stack mais leve sem Python (aliás, o ollama é implementado em Go), o llama.cpp vale a pena tentar. Aproveitei muito a oportunidade de configurar camadas offload, facilidade de uso dos modelos no formato GGUF e uma compatibilidade muito melhor/menos rápida com novos modelos, como o Qwen3.5. Se você quiser saber quais modelos realmente performam bem dentro do OpenCode — em tarefas de codificação e precisão de saída estruturada — veja minha comparação prática de LLMs para OpenCode.

Iniciar um projeto corretamente (primeira execução recomendada)

A partir do seu repositório:

cd /path/to/your/repo
opencode

Em seguida, inicialize:

/init

Isso analisa seu projeto e cria um arquivo AGENTS.md na raiz do projeto. Geralmente vale a pena commitar este arquivo para que o OpenCode (e os colegas de equipe) compartilhem um contexto de projeto consistente.

Fluxos de trabalho principais da CLI (exemplos para copiar e colar)

O OpenCode suporta execuções não interativas:

opencode run "Explique como closures funcionam em JavaScript"

Fluxo de trabalho: gerar código (CLI)

Objetivo: gerar uma função pequena e testável com contexto mínimo.

opencode run "Escreva uma função Go ParsePort(envVar string, defaultPort int) (int, error). Ela deve ler a var de ambiente, parsear um int, validar 1-65535 e retornar defaultPort se vazio. Inclua 3 tests baseados em tabelas."

Saída esperada:

  • Uma explicação mais blocos de código (função + tests). O código exato varia conforme o modelo/provedor e o prompt.

Fluxo de trabalho: refatorar um arquivo com segurança (CLI + agente Plan)

Objetivo: refatorar sem edições acidentais usando um agente mais restritivo.

opencode run --agent plan --file ./src/auth.ts \
  "Refatore este arquivo para reduzir a complexidade. Saída: (1) um plano curto, (2) um patch diff unificado, (3) riscos/casos extremos para testar. Não execute comandos."

Saída esperada:

  • Uma seção de plano + um bloco de patch diff --git ... + uma lista de verificação de testes.
  • O conteúdo varia. Se não produzir um diff, repita o prompt: “Retorne apenas um diff unificado” ou “Use o formato diff --git.”

Fluxo de trabalho: fazer perguntas sobre o repositório (CLI)

Objetivo: localizar detalhes de implementação rapidamente.

opencode run --agent explore \
  "Neste repositório, onde a autenticação é validada para requisições de API? Liste os arquivos prováveis e explique o fluxo. Se não tiver certeza, diga o que verificou."

Saída esperada:

  • Um mapa curto de caminhos de arquivos + descrição do fluxo.
  • A saída depende do tamanho do repositório e das ferramentas de contexto do modelo/provedor.

Fluxo de trabalho: acelerar execuções CLI repetidas com um servidor persistente

Se você estiver criando scripts ou executando múltiplas chamadas opencode run, pode iniciar um servidor headless uma vez:

Terminal 1:

opencode serve --port 4096 --hostname 127.0.0.1

Terminal 2:

opencode run --attach http://localhost:4096 "Resuma a estrutura do repositório e os principais pontos de entrada."
opencode run --attach http://localhost:4096 "Agora proponha 3 refatorações de alto impacto e o porquê."

Saída esperada:

  • O mesmo que opencode run, mas geralmente com menos sobrecarga de inicialização repetida.

Uso programático (SDK oficial JS/TS)

O OpenCode expõe um servidor HTTP (OpenAPI) e fornece um cliente JS/TS seguro de tipos.

Instale:

npm install @opencode-ai/sdk

Exemplo: iniciar servidor + cliente, depois prompt

Crie scripts/opencode-sdk-demo.mjs:

import { createOpencode } from "@opencode-ai/sdk";

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    // O formato da string do modelo é provedor/modelo (apenas exemplo)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Servidor rodando em: ${opencode.server.url}`);

// Verificação básica de saúde/versão
const health = await opencode.client.global.health();
console.log("Saudável:", health.data.healthy, "Versão:", health.data.version);

// Criar uma sessão e fazer um prompt
const session = await opencode.client.session.create({ body: { title: "Demo quickstart do SDK" } });

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Gere uma pequena seção README descrevendo este repositório." }],
  },
});

console.log(result.data);

// Fechar o servidor quando terminar
opencode.server.close();

Execute:

node scripts/opencode-sdk-demo.mjs

Formato da saída esperado:

  • “Servidor rodando em …”
  • Uma resposta de saúde incluindo uma string de versão
  • Um objeto de resposta de prompt de sessão (a estrutura exata depende de responseStyle e versão do SDK)

Configuração mínima do OpenCode para copiar

O OpenCode suporta configurações JSON e JSONC. Este é um ponto de partida razoável para uma configuração local de projeto.

Crie opencode.jsonc na raiz do seu repositório:

{
  "$schema": "https://opencode.ai/config.json",

  // Escolha um modelo padrão (provedor/modelo). Mantenha isso alinhado com o que `opencode models` mostra.
  "model": "provedor/modelo",

  // Opcional: um "modelo pequeno" mais barato para tarefas leves (títulos, etc.)
  "small_model": "provedor/modelo-pequeno",

  // Opcional: padrões do servidor OpenCode (usado por serve/web)
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },

  // Segurança opcional: exigir confirmação antes de edições/comandos
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Guia de referência rápida (cheatsheet curto)

Comandos que você usará diariamente

opencode                       # iniciar TUI
opencode run "..."             # execução não interativa (automação)
opencode run --file path "..." # anexar arquivos ao prompt
opencode models --refresh      # atualizar lista de modelos
opencode auth login            # configurar credenciais do provedor
opencode serve                 # servidor HTTP headless (OpenAPI)
opencode web                   # servidor headless + interface web
opencode session list          # listar sessões
opencode stats                 # estatísticas de tokens/custos

Comandos TUI que valem a pena memorizar

/connect   # conectar um provedor
/init      # analisar repositório, gerar AGENTS.md
/share     # compartilhar uma sessão (se habilitado)
/undo      # desfazer uma mudança
/redo      # refazer uma mudança
/help      # ajuda/atalhos

Conceito de “tecla líder” padrão (TUI)

O OpenCode usa uma tecla “líder” configurável (comumente ctrl+x) para evitar conflitos no terminal. Muitos atalhos são “Líder + tecla”.

Tabela de cheatsheet do OpenCode em uma página para impressão

Esta versão é intencionalmente densa e “amigável para impressão”. (Você pode colá-la em uma página dedicada /ai-devtools/opencode/cheatsheet/ depois.)

Tarefa Comando / atalho Notas
Iniciar TUI opencode O comportamento padrão é lançar a interface do terminal
Executar prompt one-shot opencode run "..." Modo não interativo para scripting/automação
Anexar arquivo(s) ao prompt opencode run --file path/to/file "..." Use múltiplas flags --file para vários arquivos
Escolher modelo para uma execução opencode run --model provedor/modelo "..." Strings de modelo são provedor/modelo
Escolher agente opencode run --agent plan "..." Plan é projetado para trabalho “sem mudanças” mais seguro (restrito de permissão)
Listar modelos opencode models [provedor] Use --refresh para atualizar a lista em cache
Configurar credenciais do provedor opencode auth login Armazena credenciais em ~/.local/share/opencode/auth.json
Listar provedores autenticados opencode auth list / opencode auth ls Confirma o que o OpenCode vê
Iniciar servidor headless opencode serve --port 4096 --hostname 127.0.0.1 Spec OpenAPI em http://host:port/doc
Anexar execuções ao servidor opencode run --attach http://localhost:4096 "..." Útil para evitar inicializações frias repetidas
Habilitar autenticação básica OPENCODE_SERVER_PASSWORD=... opencode serve O usuário padrão é opencode a menos que sobrescrito
Modo Interface Web opencode web Inicia servidor + abre navegador
Exportar uma sessão opencode export [sessionID] Útil para arquivamento ou compartilhamento de contexto
Importar uma sessão opencode import session.json Também pode importar de uma URL de compartilhamento
Ver flags globais da CLI opencode --help / opencode --version --print-logs + --log-level para debug
Conceito de tecla líder TUI tecla líder padrão frequentemente ctrl+x Customizável em tui.json

Oh My Opencode — leve o OpenCode além com orquestração multi-agente

Uma vez que o OpenCode está rodando, o próximo passo natural é Oh My Opencode — um plugin da comunidade que envolve o OpenCode em um harness multi-agente. A ideia principal: digite ultrawork (ou ulw) em uma sessão e um orquestrador (Sisyphus) assume o controle, delegando sub-tarefas para agentes especialistas que rodam em paralelo, cada um na família de modelo para a qual seus prompts são ajustados.

Três artigos cobrem isso em profundidade:

Fontes (oficiais primeiro)

Oficial:

Referência de integração autoritativa:

Comparações/tutoriais respeitados:

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.