Introdução ao OpenCode: Instale, Configure e Use o Agente de Codificação por 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 interfaces opcionais para desktop e IDEs. Este é o Início Rápido do OpenCode: instalar, verificar, conectar um modelo/provedor e executar 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 verifique os documentos oficiais da CLI e o changelog (vinculados abaixo).

Este artigo faz parte de Ferramentas de Desenvolvimento com IA: O Guia Completo para Desenvolvimento com IA. Se você também mantiver um assistente auto-hospedado como o Nous Hermes, a folha de referência rápida da CLI do Agente Hermes mapeia o conjunto de comandos hermes ao lado deste início rápido do OpenCode.

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

O OpenCode é projetado para codificação agêntica com foco em terminal, mantendo-se flexível quanto a provedores/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 você quiser compará-lo com outro assistente agêntico de código aberto que pode executar planos de múltiplas etapas em um ambiente sandbox, veja o Início Rápido do Assistente de Codificação OpenHands.

Para o agente com foco em terminal da Anthropic, com a mesma abordagem 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.

Para uma abordagem deliberadamente minimalista da mesma ideia de agente de terminal — quatro ferramentas padrão, sem sandbox embutido, o resto via extensões — veja a avaliação do Agente de Codificação Pi.

opencode com LLM auto-hospedado qwen3.5 27b

Pré-requisitos

Você vai 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.

Instalar 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 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 do AUR)
paru -S opencode-bin

Notas para Windows (o guia oficial recomenda comumente o WSL para 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 instalação

opencode --version
opencode --help

Formato de saída esperado (varia 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 (dois caminhos práticos)

Caminho A: TUI /connect (interativo)

Inicie o OpenCode:

opencode

Em seguida, execute:

/connect

Siga as etapas da interface para selecionar um provedor e autenticar (alguns fluxos abrem um login de navegador/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 de LLM local (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 fino sobre memória e tempo de execução, ou quer uma pilha mais leve sem Python (a propósito, o ollama é implementado em Go), vale a pena tentar o llama.cpp. Apreciei muito a oportunidade de configurar camadas descarregadas, a facilidade de uso dos modelos em formato GGUF e a compatibilidade muito melhor/mais rápida implementada com novos modelos, como o Qwen3.5. Se você quiser saber quais modelos realmente funcionam 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.

Começar um projeto corretamente (primeira execução recomendada)

A partir do seu repositório:

cd /path/to/your/repo
opencode

Em seguida, inicie:

/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 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 "Explain how closures work in JavaScript"

Para padrões de fluxo de trabalho de linha de comando — encaminhar saída do git, alvos de Makefile e CI, políticas de permissão para execuções não supervisionadas — e os modos de falha esperados, veja o guia prático da CLI do OpenCode. Ele se baseia neste início rápido em vez de repeti-lo.

Fluxo de trabalho: gerar código (CLI)

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

opencode run "Write a Go function ParsePort(envVar string, defaultPort int) (int, error). It should read the env var, parse an int, validate 1-65535, and return defaultPort if empty. Include 3 table-driven tests."

Saída esperada:

  • Uma explicação mais blocos de código (função + testes). 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: confirmar que o agente plan mais restritivo executa antes de você confiar nele.

opencode run --agent plan --file ./src/auth.ts \
  "Refactor this file to reduce complexity. Output a short plan only. Do not run commands."

Saída esperada: uma seção de plano, sem edições de arquivo, sem comandos executados.

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

Objetivo: confirmar que o agente explore pode localizar detalhes de implementação.

opencode run --agent explore \
  "Where is authentication validated for API requests in this repository?"

Saída esperada: um breve mapa de caminhos de arquivo e uma descrição do fluxo.

Ambos são testes de fumaça de tiro único. Para a versão de produção restrita das mesmas tarefas — saída explícita de riscos/casos extremos, patches unified-diff, prompts de exploração conscientes de permissões e o que fazer quando o modelo não se conforma — veja a seção “Melhores Casos de Uso da CLI do OpenCode” do guia prático da CLI do OpenCode.

Fluxo de trabalho: acelerar execuções repetidas da CLI 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 "Summarize the repo structure and main entrypoints."
opencode run --attach http://localhost:4096 "Now propose 3 high-impact refactors and why."

Saída esperada:

  • 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 com segurança de tipos.

Instalar:

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 é provider/model (apenas exemplo)
    // model: "anthropic/claude-3-5-sonnet-20241022",
  },
});

console.log(`Server running at: ${opencode.server.url}`);

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

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

const result = await opencode.client.session.prompt({
  path: { id: session.data.id },
  body: {
    parts: [{ type: "text", text: "Generate a small README section describing this repo." }],
  },
});

console.log(result.data);

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

Executar:

node scripts/opencode-sdk-demo.mjs

Formato de saída esperado:

  • “Server running at …”
  • 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 da versão do SDK)

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

O OpenCode suporta configuração 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 (provider/model). Mantenha isso alinhado com o que `opencode models` mostra.
  "model": "provider/model",

  // Opcional: um "small model" mais barato para tarefas leves (títulos, etc.)
  "small_model": "provider/small-model",

  // 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"
  }
}

Para uma política de permissão mais completa voltada para trabalhos não supervisionados opencode run, veja o guia prático da CLI do OpenCode.

Folha de referência rápida (referência rápida)

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/custo

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 de terminal. Muitos atalhos são “Líder + tecla”.

Tabela de folhetos de referência rápida do OpenCode em uma página imprimível

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

Tarefa Comando / atalho Notas
Iniciar TUI opencode O comportamento padrão é lançar a interface de 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 múltiplos arquivos
Escolher modelo para uma execução opencode run --model provider/model "..." Strings de modelo são provider/model
Escolher agente opencode run --agent plan "..." Plan é projetado para trabalho mais seguro “sem mudanças” (restrito por permissão)
Listar modelos opencode models [provider] 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 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 sobrescrito
Modo de interface web opencode web Inicia servidor + abre 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
Ver flags globais da CLI opencode --help / opencode --version --print-logs + --log-level para depuração
Conceito de tecla líder TUI tecla líder padrão frequentemente ctrl+x Personalizável em tui.json

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

Uma vez que o OpenCode está em execução, 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, delegando sub-tarefas a agentes especializados que executam em paralelo, cada um na família de modelos para a qual seus prompts são ajustados.

Três artigos o cobrem em profundidade:

O OpenCode foi uma das primeiras ferramentas afetadas pela política da Anthropic de bloquear o acesso a assinaturas Claude de terceiros — uma medida tomada em janeiro de 2026, um mês antes da mesma restrição atingir o OpenClaw. A cronologia do surgimento e queda do OpenClaw documenta ambos os eventos e o padrão mais amplo que eles representam para ferramentas de agentes construídas sobre computação por assinatura.

Fontes (oficiais primeiro)

Oficiais:

Referência de integração autoritativa:

Comparativos/tutorial confiáveis:

Subscrever

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