OpenCode Quickstart: Instale, configure e use o agente de codificação AI do terminal

Como instalar, configurar e usar o OpenCode

Conteúdo da página

OpenCode é um agente de IA de código aberto que você pode executar no terminal (TUI + CLI) com superfícies desktop e IDE opcionais. Esta é a Introdução Rápida ao OpenCode: instale, verifique, conecte-se a um modelo/fornecedor e execute fluxos de trabalho reais (CLI + API).

Nota de versão: O OpenCode é lançado rapidamente. Os comandos “mais recentes” aqui são estáveis, mas a saída e os padrões podem mudar — sempre confirme com os documentos oficiais do CLI e o registro de alterações (linkados abaixo).

Este artigo é parte de Ferramentas para Desenvolvedores de IA: Guia Completo para Desenvolvimento Potencializado por IA.

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

O OpenCode foi projetado para codificação agente-first, com terminal, enquanto mantém a flexibilidade de fornecedor/modelo. Na prática, é uma camada de fluxo de trabalho que pode:

  • iniciar uma interface de usuário do terminal quando você executar opencode
  • executar prompts não interativos “um único disparo” via opencode run (scripts/automatização)
  • expor um servidor HTTP sem interface gráfica via opencode serve (e uma interface web via opencode web)
  • ser controlado programaticamente via o SDK oficial JS/TS @opencode-ai/sdk

opencode com qwen3.5 27b LLM auto-hospedado

Se você está construindo um cluster /ai-devtools/, o OpenCode é uma forte candidata para um subcluster porque naturalmente se expande para:

  • profundidade do CLI
  • comportamento e custos de modelo/fornecedor (comparação de LLM dentro do OpenCode)
  • configuração & agentes
  • integrações (GitHub/GitLab/Copilot)
  • dicas rápidas

Pré-requisitos

Você vai querer:

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

Instale o OpenCode (cópia e colagem)

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

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

Opções do 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 recentes)
brew install anomalyco/tap/opencode

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

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

Notas do Windows (a orientação oficial comumente recomenda o 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

Verifique a instalação

opencode --version
opencode --help

Forma esperada da saída (variará por versão):

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

Conecte-se a um fornecedor (dois caminhos práticos)

Caminho A: /connect no TUI (interativo)

Inicie o OpenCode:

opencode

Em seguida, execute:

/connect

Siga as etapas da interface para selecionar um fornecedor e autenticar (alguns fluxos abrem um navegador/login de dispositivo).

Caminho B: opencode auth login no CLI (chaves do fornecedor)

O OpenCode suporta a configuração de fornecedores 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ê preferir o controle granular sobre a memória e o tempo de execução, ou quiser uma pilha mais leve sem Python (por sinal, o Ollama é implementado em Go), o llama.cpp vale a pena tentar. Realmente gostei da oportunidade de configurar camadas deslocadas, da facilidade de uso dos modelos no formato GGUF e da implementação muito melhor e mais rápida da compatibilidade com novos modelos, como o Qwen3.5.

Inicie um projeto corretamente (execução recomendada inicial)

Do seu repositório:

cd /caminho/para/seu/repositório
opencode

Em seguida, inicialize:

/init

Isso analisa seu projeto e cria um arquivo AGENTS.md na raiz do projeto. Normalmente, é útil comitar esse arquivo para que o OpenCode (e colegas) compartilhem um contexto de projeto consistente.

Fluxos de trabalho principais do CLI (exemplos de cópia e colagem)

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 pequena função testável com contexto mínimo.

opencode run "Escreva uma função Go ParsePort(envVar string, defaultPort int) (int, error). Ela deve ler a variável de ambiente, parsear um inteiro, validar 1-65535 e retornar defaultPort se estiver vazia. Inclua 3 testes baseados em tabela."

Saída esperada:

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

Fluxo de trabalho: refatorar um arquivo com segurança (CLI + Agente de Plano)

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 bloco de patch unificado, (3) riscos/casos de borda para testar. Não execute comandos."

Saída esperada:

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

Fluxo de trabalho: perguntar sobre detalhes do repositório (CLI)

Objetivo: localizar detalhes de implementação rapidamente.

opencode run --agent explore \
  "Neste repositório, onde a autenticação é validada para solicitações de API? Liste os arquivos prováveis e explique o fluxo. Se estiver incerto, diga o que você 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/fornecedor.

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

Se você estiver criando scripts ou executando múltiplas chamadas de opencode run, você pode iniciar um servidor sem interface gráfica 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 por quê."

Saída esperada:

  • A mesma 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 tipo seguro JS/TS.

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: {
    // Formato da string do modelo é fornecedor/modelo (exemplo apenas)
    // 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);

// Crie uma sessão e prompt
const session = await opencode.client.session.create({ body: { title: "Demo de início rápido do SDK" } });

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

console.log(result.data);

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

Execute:

node scripts/opencode-sdk-demo.mjs

Forma esperada da saída:

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

Configuração mínima do OpenCode que você pode copiar

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

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

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

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

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

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

  // Opcional segurança: exige confirmação antes de edições/comandos
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Dica rápida (referência rápida)

Comandos que você usará diariamente

opencode                       # iniciar TUI
opencode run "..."             # execução não interativa (automatização)
opencode run --file path "..." # anexar arquivos ao prompt
opencode models --refresh      # atualizar lista de modelos
opencode auth login            # configurar credenciais do fornecedor
opencode serve                 # servidor HTTP sem interface gráfica (OpenAPI)
opencode web                   # servidor sem interface gráfica + interface web
opencode session list          # listar sessões
opencode stats                 # estatísticas de token/custo

Comandos do TUI que vale a pena memorizar

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

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

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

Tabela de dica rápida de uma página impressa do OpenCode

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

Tarefa Comando / atalho Notas
Iniciar TUI opencode O comportamento padrão é lançar a interface do terminal
Executar prompt de um único disparo opencode run "..." Modo não interativo para scripts/automatização
Anexar arquivo(s) ao prompt opencode run --file caminho/para/arquivo "..." Use múltiplas bandeiras --file para múltiplos arquivos
Escolher modelo para uma execução opencode run --model fornecedor/modelo "..." Strings de modelo são fornecedor/modelo
Escolher agente opencode run --agent plan "..." O plano foi projetado para trabalhos “sem alterações” mais seguros (restritos por permissão)
Listar modelos opencode models [fornecedor] Use --refresh para atualizar a lista armazenada
Configurar credenciais do fornecedor opencode auth login Armazena credenciais em ~/.local/share/opencode/auth.json
Listar fornecedores autenticados opencode auth list / opencode auth ls Confirma o que o OpenCode vê
Iniciar servidor sem interface gráfica opencode serve --port 4096 --hostname 127.0.0.1 Especificação 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 nome de usuário padrão é opencode a menos que seja substituído
Modo de interface web opencode web Inicia o servidor + abre o navegador
Exportar uma sessão opencode export [sessionID] Útil para arquivar ou compartilhar contexto
Importar uma sessão opencode import session.json Também pode importar de uma URL de compartilhamento
Verificar flags globais do CLI opencode --help / opencode --version --print-logs + --log-level para depuração
Conceito de tecla líder do TUI tecla líder padrão frequentemente ctrl+x Personalizável em tui.json

Fontes (oficiais primeiro)

Oficiais:

Referência de integração autoritativa:

Comparações/tutoriais reputáveis: