Como usar o opencode: guia passo a passo

Para usar o opencode, instale-o com um comando, rode opencode na pasta de um projeto, conecte um provedor de modelos com /connect, escolha um modelo com /models e descreva o que você quer. O agente padrão, Build, lê seu código, edita arquivos e roda comandos. Pressione Tab para passar ao agente Plan quando quiser pensar uma mudança sem tocar no código.

Esse é o ciclo básico. Este guia cobre o resto: provedores e modelos locais, os comandos da TUI que você vai usar todo dia, os dois agentes nativos, o opencode.json, o AGENTS.md, servidores MCP, comandos personalizados e como rodar o opencode ao lado de outros agentes. Tudo aqui segue a documentação oficial do opencode em outubro de 2026.

O que é o opencode

O opencode é um agente de código para o terminal que não está preso a uma única empresa de IA. O Claude Code usa modelos da Anthropic e o Codex usa modelos da OpenAI. O opencode é construído sobre o AI SDK e o Models.dev, então funciona com dezenas de provedores e com modelos locais. Você pode usar um modelo para planejar e outro para construir, e trocar de provedor sem aprender uma ferramenta nova.

Uma observação sobre versões: o opencode 2 já foi lançado, com documentação própria. As duas versões instalam um comando chamado opencode, e não dá para manter as duas com esse nome. Este guia segue a versão 1, que é o que o pacote npm opencode-ai instala. Quase tudo vale também para a versão 2. Se você instalou pela fórmula core do Homebrew ou pelo repositório principal do Arch, provavelmente tem a versão 2, então consulte a documentação correspondente.

Passo 1: instale o opencode

bun, pnpm e yarn global add opencode-ai também funcionam. No Windows, a documentação recomenda rodar o opencode dentro do WSL para a melhor experiência. Um terminal moderno como WezTerm, Alacritty, Ghostty ou Kitty renderiza melhor a TUI.

O opencode nunca se atualiza sozinho em segundo plano. Dentro de uma sessão, /update instala uma versão 1 mais nova, ou oferece a atualização para a versão 2 quando você já está na última versão 1. No shell, opencode upgrade faz o mesmo.

Passo 2: conecte um provedor e escolha um modelo

Entre em um projeto e inicie o opencode:

cd my-project
opencode

Depois rode /connect e escolha um provedor. Você pode fazer o mesmo no shell com opencode auth login. As credenciais ficam salvas em ~/.local/share/opencode/auth.json, e opencode auth list mostra o que está conectado. O opencode também lê chaves de API de variáveis de ambiente e de um arquivo .env no projeto.

Algumas opções comuns:

• OpenCode Zen: uma lista selecionada de modelos que a equipe do opencode testou com o agente. Entre em opencode.ai/auth, adicione o pagamento, copie a chave e cole no /connect. A documentação recomenda essa opção para novos usuários.
• Anthropic: cole uma chave de API do Claude Console. O login com uma assinatura Claude Pro ou Max não é oferecido. A Anthropic não permite que ferramentas de terceiros usem esses planos dessa forma, e o opencode deixou de distribuir os plugins que faziam isso.
• OpenAI: escolha “ChatGPT Plus/Pro” para entrar pelo navegador, ou informe uma chave de API manualmente.
• GitHub Copilot: entre com um código de dispositivo em github.com/login/device. Alguns modelos exigem um plano do Copilot mais alto.
• Modelos locais: adicione um provedor personalizado apontando para um servidor compatível com OpenAI (veja abaixo).

Com um provedor conectado, /models (ou ctrl+x m) abre o seletor de modelos. No shell, opencode models lista todos os modelos que seus provedores oferecem, e opencode models anthropic lista os modelos de um provedor. Os modelos são escritos como provider/model, por exemplo anthropic/claude-sonnet-5-5. Muitos modelos têm variantes, como um esforço de raciocínio maior, e ctrl+t alterna entre elas.

Modelos locais com Ollama

Um modelo local é um provedor personalizado no opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

Se as chamadas de ferramenta falharem com um modelo local, a documentação sugere aumentar o num_ctx do Ollama para algo entre 16k e 32k. Uma janela de contexto pequena costuma ser a causa. Para escolher o modelo local em si, veja agentes de código com LLM local.

Passo 3: o básico da TUI

A tela do opencode é um chat com o seu projeto. As poucas coisas que você vai usar o tempo todo:

• @ faz uma busca aproximada de arquivos e os adiciona à sua mensagem.
• ! no início da linha roda um comando de shell, por exemplo !npm test, e coloca a saída na conversa.
• ctrl+x é a tecla líder. A maioria dos atalhos é ctrl+x seguido de uma letra.
• Você pode arrastar imagens para o terminal para incluí-las.

O /undo depende do Git para reverter alterações em arquivos, então o projeto deve ser um repositório Git. Para continuar de onde parou pelo shell, opencode -c reabre a última sessão e opencode -s <id> abre uma específica. Para scripts e CI, opencode run "your prompt" executa uma única tarefa sem a TUI.

Passo 4: os agentes Build e Plan

O opencode tem dois agentes principais, e Tab alterna entre eles:

• Build é o padrão. Ele tem todas as ferramentas habilitadas: edita arquivos, roda comandos de shell e chama servidores MCP.
• Plan é restrito. Ele não pode editar seu código; os únicos arquivos que pode escrever são planos em Markdown em .opencode/plans/. Ele pode fazer perguntas para esclarecer.

Um bom hábito para qualquer coisa não trivial é começar no Plan, combinar uma abordagem, depois pressionar Tab e pedir ao Build que a execute. Há também dois subagentes que você chama com @: @general para pesquisas e mudanças em várias etapas, e @explore para buscas rápidas, somente leitura, no código. Cada um roda em uma sessão filha. ctrl+x seguido da seta para baixo entra nela, e a seta para cima volta à sessão pai. O verbete do glossário sobre subagente explica por que isso economiza contexto.

Uma armadilha: o Plan não limita o bash sozinho. Comandos de shell seguem suas configurações de permissão. Além disso, um "edit": "allow" no nível superior da sua configuração também vale para o Plan, porque as regras correspondentes posteriores vencem. Se você quer o Plan travado, defina as permissões dele diretamente:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "ask"
      }
    }
  }
}

Você pode criar seus próprios agentes com opencode agent create, ou como arquivos Markdown em .opencode/agents/ (por projeto) ou ~/.config/opencode/agents/ (global). O nome do arquivo vira o nome do agente. O frontmatter define description, mode (primary ou subagent), model e permission.

Passo 5: o arquivo de configuração

O opencode lê o opencode.json (ou opencode.jsonc, que aceita comentários). Há dois lugares comuns:

• Global: ~/.config/opencode/opencode.json, para os seus padrões.
• Projeto: opencode.json na raiz do projeto, versionado junto com o código.

Os arquivos são mesclados, não substituídos, e as configurações do projeto vencem onde houver sobreposição. Uma configuração de projeto prática:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "npm test *": "allow"
    }
  },
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

• model é o modelo padrão. small_model é usado em tarefas leves, como títulos de sessão.
• permission aceita allow, ask ou deny por ferramenta, com padrões para o bash. O último padrão correspondente vence, então coloque "*" primeiro.
• instructions adiciona outros arquivos de regras além do AGENTS.md. Globs e URLs funcionam.

Os valores podem vir do ambiente com {env:VAR} ou de um arquivo com {file:path}, então as chaves nunca precisam ficar na configuração. Por padrão, a maioria das ações é permitida. Ler arquivos .env e mexer em pastas fora do projeto pedem confirmação antes. opencode --auto aprova tudo o que não estiver explicitamente negado, então use só em um lugar onde você se sentiria tranquilo deixando o agente rodar sem supervisão.

Configurações da TUI, como tema e atalhos de teclado, ficam em um tui.json separado.

Passo 6: AGENTS.md

O AGENTS.md guarda as regras do seu projeto: como compilar, testar e rodar o lint, as convenções a seguir, as pastas que não devem ser tocadas. Rode /init e o opencode analisa o projeto e escreve um para você. Leia, enxugue e faça commit.

# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- API handlers live in src/api/; one file per route.
- Never edit files in src/generated/.

Regras globais para todos os projetos ficam em ~/.config/opencode/AGENTS.md. Se você vem do Claude Code, o opencode recorre a um CLAUDE.md do projeto quando não há AGENTS.md, e também lê ~/.claude/CLAUDE.md e ~/.claude/skills/. Defina OPENCODE_DISABLE_CLAUDE_CODE=1 para desativar isso. Como escrever CLAUDE.md e AGENTS.md explica o que deve entrar no arquivo.

Passo 7: servidores MCP

Servidores MCP dão novas ferramentas ao opencode: um navegador, um rastreador de issues, busca em documentação. Eles ficam na chave mcp. Um servidor local é um comando que o opencode inicia; um servidor remoto é uma URL:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    },
    "my-remote": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_MCP_TOKEN}"
      }
    }
  }
}

opencode mcp add adiciona um servidor de forma interativa, e opencode mcp list mostra o que está configurado e se conecta. Servidores remotos que usam OAuth fazem login automaticamente, e opencode mcp auth <name> faz o login manualmente. opencode mcp debug <name> ajuda quando um servidor não conecta.

Cada servidor adiciona suas ferramentas ao contexto de cada requisição, e alguns grandes, como o servidor MCP do GitHub, adicionam bastante. Ative só os servidores de que você precisa, e use "enabled": false para manter um configurado, mas desligado.

Passo 8: comandos personalizados

Um comando personalizado é um prompt que você digitaria de novo toda vez. Coloque um arquivo Markdown em .opencode/commands/ (por projeto) ou ~/.config/opencode/commands/ (global); o nome do arquivo vira o comando:

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

Salvo como .opencode/commands/test.md, isso vira /test. Comandos aceitam argumentos: $ARGUMENTS é tudo o que vem depois do nome do comando, $1, $2 e assim por diante são argumentos individuais, !`git diff --staged` insere a saída de um comando de shell, e @src/file.ts inclui um arquivo. Você também pode definir comandos na chave command do opencode.json com um template. Se um comando personalizado tiver o mesmo nome de um nativo, o nativo vence.

Armadilhas comuns

• “No provider” na primeira execução. Nada está conectado ainda. Rode /connect.
• Edições no modo Plan. Um "edit": "allow" global também chega ao Plan. Defina agent.plan.permission explicitamente.
• O /undo não reverte arquivos. A pasta não é um repositório Git.
• Duas versões do opencode brigando. O Homebrew core instala a versão 2 e o npm instala a versão 1 com o mesmo nome de comando. Confira opencode --version e mantenha só uma.
• Sessões lentas e caras. Servidores MCP demais, ou uma sessão longa. Desligue servidores e use /compact ou /new.

Rodando o opencode em painéis do AgentVera

Uma sessão do opencode é fácil de acompanhar. Vários agentes ao mesmo tempo, alguns no opencode, outros no Claude Code ou Codex, é quando as abas do terminal começam a atrapalhar. O AgentVera é um app desktop que roda essas CLIs lado a lado em terminais reais, usando as suas próprias instalações e logins. O suporte ao opencode funciona assim:

• Seus provedores, seu login. Você entra nos provedores dentro do próprio opencode (/connect ou opencode auth login), e todo provedor conectado, inclusive modelos locais, aparece na lista de modelos do AgentVera, agrupado por provedor. As variantes de modelo aparecem como opções de esforço. Se o opencode não estiver instalado, o AgentVera o instala com npm i -g opencode-ai.
• Uma sessão por agente. Cada agente opencode tem sua própria sessão, então duplicar um agente cria um fork da conversa em vez de compartilhá-la. O /compact funciona normalmente.
• Seu opencode.json fica intocado. O papel do agente, os servidores MCP que você adicionou no gerenciador de MCP do AgentVera e o navegador do AgentVera são passados como configuração extra e mesclados com a sua.
• Painéis e worktrees. Rode o opencode ao lado do Claude Code na grade do workspace, cada agente no seu próprio git worktree, para que um não pise nos arquivos do outro.
• Revisão e flows. Agentes opencode funcionam com a revisão de código automática, e nos flows (Pro e Team) a resposta de um agente pode ir para outro automaticamente. Por exemplo, um modelo barato planeja e um mais forte constrói.

A grade, os worktrees, a revisão de código e o gerenciador de MCP estão no plano gratuito. Baixe o AgentVera para experimentar. Se a sua equipe também roda o Claude no CI, Claude Code GitHub Actions cobre esse lado, e Como usar o Codex CLI é o mesmo guia para o agente da OpenAI.

Conclusão

Para usar o opencode, instale-o, rode opencode em um projeto, conecte um provedor com /connect e escolha um modelo com /models. Use o Plan para pensar e o Build para mudar o código, alternando entre eles com Tab. Coloque seus padrões no opencode.json, as regras do projeto no AGENTS.md, suas ferramentas em mcp e os prompts repetidos em .opencode/commands/. Depois disso, usar o opencode é basicamente escolher o modelo certo para cada tarefa, e ele deixa você trocar quando quiser.