Início Rápido do 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

O OpenCode é um agente de codificação de IA de código aberto que você pode executar no terminal (TUI + CLI), com superfícies opcionais de desktop e IDE. Este é o 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 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 — verifique sempre a documentação oficial da CLI e o changelog (linkado abaixo).

Este artigo faz parte de Ferramentas de Desenvolvimento com IA: O Guia Completo para Desenvolvimento Impulsionado por IA. Se você também mantém um assistente auto-hospedado como o Nous Hermes, a tabela de consulta 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 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 do 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últiplas etapas em um ambiente sandboxed, veja o Início Rápido do Assistente de Codificação OpenHands.

Para o agente com foco 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.

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

opencode com LLM qwen3.5 27b auto-hospedado

Pré-requisitos

Você terá:

  • 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.

Instale o 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 via Node.js
npm install -g opencode-ai

# Homebrew (recomendado pelo OpenCode para as liberaçõ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 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 a instalação

opencode --version
opencode --help

Formato de saída esperado (varia por 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 deseja uma pilha mais leve sem Python (PS: o ollama é implementado em Go), o llama.cpp vale a pena tentar. Aproveitei muito a oportunidade de configurar camadas descarregadas (offloaded), a facilidade de uso dos modelos no 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 têm bom desempenho dentro do OpenCode — em tarefas de codificação e precisão de saída estruturada — veja minha comparação prática de LLMs para o OpenCode.

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

A partir do seu repositório:

cd /caminho/para/seu/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 colegas de equipe) compartilhem um contexto de projeto consistente.

Fluxos de trabalho principais da CLI (exemplos de 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 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, analisar um int, validar 1-65535 e retornar defaultPort se estiver vazia. Inclua 3 testes orientados a tabela."

Saída esperada:

  • Uma explicação além de blocos de código (função + testes). O código exato varia por modelo/provedor e 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 extremos a 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, reenvie 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 estiver inseguro, diga o que verificou."

Saída esperada:

  • Um breve mapa 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 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 por quê."

Saída esperada:

  • A mesma do 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 por tipo.

Instalação:

npm install @opencode-ai/sdk

Exemplo: iniciar servidor + cliente, depois enviar 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 executando 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 envie um prompt
const session = await opencode.client.session.create({ body: { title: "Demonstração 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);

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

Executar:

node scripts/opencode-sdk-demo.mjs

Formato de saída esperado:

  • “Servidor executando 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 do 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 "pequeno modelo" 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"
  }
}

Tabela de consulta rápida (referência breve)

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

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 consulta rápida do OpenCode de uma página imprimível

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 "..." As 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 a frio 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 multiagente

Uma vez que o OpenCode esteja em execução, o próximo passo natural é o Oh My Opencode — um plugin da comunidade que envolve o OpenCode em um harness multiagente. A ideia principal: digite ultrawork (ou ulw) em uma sessão e um orquestrador (Sisyphus) assume, delegando subtarefas 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 de assinatura do Claude por terceiros — uma medida tomada em janeiro de 2026, um mês antes da mesma restrição atingir 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 agentes construídas sobre computação por assinatura.

Fontes (oficiais primeiro)

Oficiais:

Referência de integração autoritativa:

Comparações/tutoriais confiáveis:

Subscrever

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