Início Rápido do OpenCode: Instale, Configure e Use o Agente de Codificação 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 Guia de Início Rápido do OpenCode: instalação, verificação, conexão de um modelo/provedor e execução de fluxos de trabalho reais (CLI + API).

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

Este artigo faz parte de Ferramentas de Desenvolvimento com IA: O Guia Completo para Desenvolvimento com IA.

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

O OpenCode é projetado para codificação agêntica focada no terminal, mantendo-se flexível em relação a provedores/modelos. Na prática, é uma camada de fluxo de trabalho que pode:

  • iniciar uma interface de usuário 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ê deseja compará-lo com outro assistente agêntico de código aberto que pode executar planos de múltiplos passos em um ambiente isolado, consulte Guia de Início Rápido do Assistente de Codificação OpenHands.

Para o agente focado no terminal da Anthropic com a mesma abordagem de “modelo local via HTTP” (Ollama ou llama.cpp, permissões, preços), consulte 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.

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 geralmente recomenda 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 (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 (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 de 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 granular sobre memória e tempo de execução, ou quer uma pilha mais leve sem Python (BTW, o ollama é implementado em Go), o llama.cpp vale a pena experimentar. Aproveitei muito a oportunidade de configurar camadas offloadadas, a facilidade de uso dos modelos em formato GGUF e a compatibilidade muito melhor/melhor 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 — consulte 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 confirmar 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 "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 variável de ambiente, analisar um int, validar 1-65535 e retornar defaultPort se estiver vazia. Inclua 3 testes orientados por tabela."

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: 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 de diff unificado, (3) riscos/casos de borda 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 ao 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 repetidas da CLI com um servidor persistente

Se você estiver criando scripts ou executando várias 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 por quê."

Saída esperada:

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

Instalar:

npm install @opencode-ai/sdk

Exemplo: iniciar servidor + cliente, então fazer 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(`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 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: "Gere uma pequena seção de README descrevendo este repositório." }],
  },
});

console.log(result.data);

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

Executar:

node scripts/opencode-sdk-demo.mjs

Formato de 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 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 do 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": "provider/model",

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

  // Opcional: valores padrão 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"
  }
}

Lista rápida de comandos (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 alteração
/redo      # refazer uma alteração
/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 lista rápida de comandos do OpenCode para impressão em uma página

Esta versão é intencionalmente 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 “sem alterações” mais seguro (com permissões restritas)
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 sobrescrito
Modo 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 geralmente 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 estiver em execução, o próximo passo natural é Oh My Opencode — um plugin da comunidade que envolve o OpenCode em uma estrutura multi-agente. A ideia principal: digite ultrawork (ou ulw) em uma sessão e um orquestrador (Sisyphus) assume o controle, delegando sub-tarefas a agentes especialistas que executam em paralelo, cada um na família de modelos para a qual seus prompts são ajustados.

Três artigos cobrem isso em profundidade:

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

Fontes (oficiais primeiro)

Oficial:

Referência de integração autoritativa:

Comparações/tutoriais reputados:

Assinar

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