# Como usar o opencode: guia passo a passo URL: https://agentvera.dev/pt/blog/how-to-use-opencode/ · Publicado: 2026-10-27 Como usar o opencode: instale, conecte um provedor, escolha um modelo, alterne entre Build e Plan e configure opencode.json, AGENTS.md, MCP e comandos. **Resumo:** - Instale o opencode com o script oficial ou via npm, rode opencode em um projeto, conecte um provedor com /connect e escolha um modelo com /models; qualquer provedor funciona, inclusive modelos locais. - Tab alterna entre o agente Build, que edita e roda comandos, e o agente Plan, que não pode editar seu código e serve para pensar uma mudança antes de fazê-la. - As configurações ficam em opencode.json (global e por projeto) e as regras do projeto em AGENTS.md; servidores MCP vão na chave mcp e comandos personalizados em .opencode/commands/. 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](/pt/glossary/coding-agent/ "O que é 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 | Plataforma | Comando | | --- | --- | | macOS, Linux | `curl -fsSL https://opencode.ai/install \| bash` | | Qualquer plataforma com Node.js | `npm install -g opencode-ai` | | macOS, Linux (Homebrew, versão 1) | `brew install anomalyco/tap/opencode` | | Windows | `choco install opencode` ou `scoop install 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: ```bash 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`: ```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](/pt/blog/local-llm-coding-agent/ "Agente 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. | Comando | Atalho | O que faz | | --- | --- | --- | | `/connect` | | Adiciona um provedor | | `/models` | `ctrl+x m` | Escolhe um modelo | | `/new` | `ctrl+x n` | Inicia uma nova sessão | | `/sessions` | `ctrl+x l` | Abre uma sessão anterior | | `/compact` | `ctrl+x c` | Resume a sessão para liberar contexto | | `/undo` | `ctrl+x u` | Desfaz a última mensagem e suas alterações em arquivos | | `/redo` | `ctrl+x r` | Refaz o que você desfez | | `/editor` | `ctrl+x e` | Escreve um prompt longo no seu `$EDITOR` | | `/export` | `ctrl+x x` | Exporta a conversa como Markdown | | `/init` | | Cria ou atualiza o `AGENTS.md` | | `/exit` | `ctrl+x q` | Sai | 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 ` 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](/pt/glossary/subagent/ "O que é um 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: ```json { "$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: ```json { "$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. ```markdown # 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](/pt/blog/claude-md-agents-md/ "Como escrever CLAUDE.md e AGENTS.md") explica o que deve entrar no arquivo. ## Passo 7: servidores MCP [Servidores MCP](/pt/blog/what-is-mcp-server/ "O que é um servidor 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: ```json { "$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 ` faz o login manualmente. `opencode mcp debug ` 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: ```markdown --- 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](/pt/agents/opencode/ "opencode no AgentVera") 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](/pt/features/mcp-manager/ "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](/pt/features/workspace/ "Workspace"), cada agente no seu próprio [git worktree](/pt/glossary/git-worktree/ "O que é um 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](/pt/features/code-review/ "Revisão de código automática"), e nos [flows](/pt/features/flows/ "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](/pt/download/ "Baixar o AgentVera") para experimentar. Se a sua equipe também roda o Claude no CI, [Claude Code GitHub Actions](/pt/blog/claude-code-github-actions/ "Claude Code GitHub Actions") cobre esse lado, e [Como usar o Codex CLI](/pt/blog/how-to-use-codex-cli/ "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. ## Perguntas frequentes **O opencode é gratuito?** A CLI é gratuita para instalar. Você paga pelos modelos que usa por meio do seu provedor: uma chave de API cobrada por token, uma assinatura que você já tem, como GitHub Copilot ou ChatGPT Plus/Pro, ou o OpenCode Zen. Modelos locais via Ollama não custam nada além do seu próprio hardware. **Quais modelos o opencode pode usar?** Qualquer provedor que ele suporta: Anthropic, OpenAI, Google, GitHub Copilot, OpenRouter, OpenCode Zen e muitos outros, além de modelos locais por meio de um servidor compatível com OpenAI, como o Ollama. Rode opencode models para listar o que seus provedores conectados oferecem. **Qual a diferença entre os agentes Build e Plan?** Build é o padrão e tem todas as ferramentas, então edita arquivos e roda comandos. Plan não pode editar seu código; ele só pode escrever planos em Markdown em .opencode/plans/. Use o Plan para pensar uma mudança e depois pressione Tab para passar ao Build e executá-la. **O opencode lê o CLAUDE.md?** Sim, como alternativa. Se o projeto não tem AGENTS.md, o opencode lê o CLAUDE.md, e também recorre ao ~/.claude/CLAUDE.md para regras globais. Defina OPENCODE_DISABLE_CLAUDE_CODE=1 para desativar essas alternativas do Claude Code. **Onde o opencode guarda suas configurações e logins?** As configurações globais ficam em ~/.config/opencode/opencode.json e as do projeto em opencode.json na raiz do projeto; os dois são mesclados. As credenciais de provedor do /connect ficam em ~/.local/share/opencode/auth.json. --- **Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/