OpenCode Quickstart: Instale, Configure e Use o Agente de Código 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 adicionais de desktop e IDE. Esta é a Instalação Rápida do OpenCode: instale, verifique, conecte 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 valores padrão podem mudar — sempre verifique as documentações oficiais do CLI e o changelog (linkados abaixo).

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

O que é o OpenCode (e onde se encaixa)

O OpenCode foi projetado para codificação agente-first, com terminal, mantendo-se flexível entre fornecedores/modelos. Na prática, é uma camada de fluxo de trabalho que pode:

  • iniciar uma interface de usuário do terminal ao executar opencode
  • executar prompts não interativos “one-shot” via opencode run (scripts/automatização)
  • expor um servidor HTTP sem interface 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ê estiver montando um cluster /ai-devtools/, o OpenCode é uma boa opção para um subcluster, pois 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).

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

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 um fornecedor (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 fornecedor e autenticar (alguns fluxos abrem um navegador/login no dispositivo).

Caminho B: CLI opencode auth login (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 um arquivo .env no seu projeto.

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

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. 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 fechamentos funcionam em JavaScript"

Fluxo de trabalho: gerar código (CLI)

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

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 com base 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 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 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: 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 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: acelere execuções repetidas do CLI com um servidor persistente

Se você estiver criando scripts ou executando múltiplas chamadas de opencode run, pode iniciar um servidor sem interface 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 refatorias 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 (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 esta alinhada 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: valores padrão do servidor do OpenCode (usados 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 (OpenAPI)
opencode web                   # servidor sem interface + interface web
opencode session list          # listar sessões
opencode stats                 # estatísticas de tokens/custos

Comandos do TUI que vale a pena memorizar

/connect   # conectar 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 tecla “leader” padrão (TUI)

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

Perguntas frequentes (pronto para esquema)

O que é o OpenCode?

O OpenCode é um agente de IA de código aberto projetado para funcionar no seu terminal (TUI + CLI) com superfícies adicionais de desktop/IDE.

O OpenCode é gratuito?

A ferramenta é de código aberto. O custo de uso depende do modelo/fornecedor ao qual você se conecta. Alguns fornecedores podem oferecer autenticação baseada em assinatura ou camadas gratuitas.

Como posso executar o OpenCode sem abrir o TUI?

Use opencode run "..." para o modo não interativo (útil para scripts/automatização).

Onde o OpenCode armazena as credenciais do fornecedor?

opencode auth login armazena as credenciais em ~/.local/share/opencode/auth.json.

O OpenCode tem uma API / SDK?

Sim. O OpenCode pode executar um servidor HTTP sem interface (opencode serve) com uma especificação OpenAPI em /doc, e fornece um SDK oficial JS/TS: @opencode-ai/sdk.

Posso usar o GitHub Copilot com o OpenCode?

O GitHub anunciou que o Copilot suporta autenticação com o OpenCode via uma integração formal. A disponibilidade exata depende do seu plano do Copilot e do fluxo atual de autenticação do fornecedor.

Tabela de dicas de uma página imprimível do OpenCode

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

Tarefa Comando / atalho Notas
Iniciar TUI opencode O comportamento padrão é iniciar a interface do terminal
Executar prompt one-shot opencode run "..." Modo não interativo para scripts/automatização
Anexar arquivo(s) ao prompt opencode run --file path/to/file "..." Use múltiplos --file para múltiplos arquivos
Escolher modelo para uma execução opencode run --model fornecedor/modelo "..." As strings de modelo são fornecedor/modelo
Escolher agente opencode run --agent plan "..." O plano foi projetado para trabalhos mais seguros sem alterações (restrito 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 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 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 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
Ver global flags do CLI opencode --help / opencode --version --print-logs + --log-level para depuração
Conceito de tecla “leader” do TUI tecla de líder padrão geralmente ctrl+x Personalizável em tui.json

Fontes (oficiais primeiro)

Oficiais:

Referência de integração autoritativa:

Comparações/tutoriais reputáveis: