# Como usar o Droid: guia passo a passo da CLI do Factory Droid

URL: https://agentvera.dev/pt/blog/how-to-use-droid/ · Publicado: 2026-11-14

Como usar o Factory Droid no terminal: instale, faça login, escolha o modelo, rode droid exec com níveis de autonomia e configure AGENTS.md, MCP e droids próprios.

**Resumo:**

- Instale com curl -fsSL https://app.factory.ai/cli | sh (ou brew install --cask droid), rode droid num projeto, faça login pelo navegador e descreva a tarefa. O Droid pergunta antes de editar arquivos ou rodar comandos.
- Em scripts e CI, o droid exec é somente leitura por padrão; --auto low permite edições, medium inclui instalações, builds, testes e commits, e high inclui pushes e deploys. Use FACTORY_API_KEY sem navegador.
- O plano Free funciona com a sua própria inferência (ChatGPT, Copilot, OpenRouter ou chaves de API); o Pro custa US$ 20 por mês em novembro de 2026. Regras vão no AGENTS.md; configurações e MCP, em ~/.factory/.

Para usar o Droid, o agente de código da Factory, você instala a CLI com `curl -fsSL https://app.factory.ai/cli | sh`, roda `droid` dentro de um projeto, faz login pelo navegador e descreve a tarefa. **O Droid pergunta antes de editar um arquivo ou rodar um comando; para scripts e CI existe o `droid exec`, que é somente leitura até você aumentar a autonomia dele.**

Este guia cobre a CLI do Droid em novembro de 2026 (versão 1.12): instalação, login, modelos, a sessão interativa, o `droid exec` e seus níveis de autonomia, AGENTS.md, servidores MCP, droids próprios e quanto custa.

## O que é o Droid

O Droid é o agente de código para terminal da [Factory](https://factory.com "Factory"). Ele lê o seu código, propõe mudanças e as aplica depois que você aprova. O mesmo agente também roda nos apps desktop e web da Factory, em integrações com IDEs e por meio de um SDK. A versão 1.0 saiu em 29 de outubro de 2026, e novas versões chegam várias vezes por semana.

O Droid não está preso a um único fornecedor de modelos. Ele oferece modelos da Anthropic, OpenAI, Google e xAI, além de modelos open-weight que a Factory agrupa como “Droid Core”, e você pode adicionar seus próprios endpoints.

## Passo 1: instale a CLI

No macOS ou Linux:

```bash
curl -fsSL https://app.factory.ai/cli | sh
```

Outras opções:

```bash
brew install --cask droid      # Homebrew
npm install -g droid           # npm
```

No Windows PowerShell:

```powershell
irm https://app.factory.ai/cli/windows | iex
```

No Linux, o login também precisa do `xdg-utils` (`sudo apt-get install xdg-utils`). Para atualizar depois, use `droid update`.

## Passo 2: faça login

```bash
cd my-project
droid
```

A primeira execução abre o navegador para você entrar com uma conta da Factory. Para CI e outras máquinas sem navegador, crie uma chave de API nas configurações da Factory e exporte-a:

```bash
export FACTORY_API_KEY=fk-...
```

## Passo 3: trabalhe em uma sessão

Descreva a tarefa com palavras simples. O Droid explica o que pretende fazer e depois pergunta antes de cada edição ou comando. Teclas e comandos úteis:

- `Shift+Tab` alterna entre o modo normal e o modo spec, em que o Droid escreve um plano antes de mudar o código.
- `!` roda um comando de shell por conta própria; `?` lista os atalhos.
- `/model` troca o modelo, `/settings` abre as configurações e `/review` pede uma revisão das mudanças.
- `/compress` encurta uma conversa longa; `/sessions` lista as anteriores.

Para voltar depois, rode `droid --resume` (ou `droid --resume <id>`). `droid search "checkout bug"` encontra uma sessão antiga pelo texto, e `--fork <id>` copia uma.

## Passo 4: escolha um modelo

Troque de modelo com `/model` em uma sessão, `-m` na linha de comando ou uma chave `model` nas configurações. Nos planos pagos, cada modelo conta contra o seu uso com um multiplicador: em novembro de 2026, o Claude Opus 5.5 conta 1,6x, o Claude Sonnet 5.5 0,8x e o Claude Haiku 5.5 0,04x. Use um modelo pequeno para edições de rotina e um grande para design e depuração.

Para usar sua própria chave, adicione um modelo próprio ao `~/.factory/settings.json`:

```json
{
  "customModels": [
    {
      "model": "claude-sonnet-5-5",
      "displayName": "Sonnet (my key)",
      "baseUrl": "https://api.anthropic.com",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "provider": "anthropic"
    }
  ]
}
```

`provider` pode ser `anthropic`, `openai`, `generic-chat-completion-api` ou `bedrock-converse`. As chaves ficam na sua máquina.

## Passo 5: droid exec e níveis de autonomia

O `droid exec` roda uma única tarefa sem chat, que é o que você quer em scripts e CI:

```bash
droid exec "summarize the changes on this branch"
droid exec --auto low "fix the failing unit test in price.test.ts"
droid exec -f task.md -o json --auto medium
```

Por padrão ele é somente leitura. Você amplia o que ele pode fazer:

| Nível | O que permite |
|---|---|
| (padrão) | Somente leitura |
| `--auto low` | Edição de arquivos |
| `--auto medium` | Também instalações, builds, testes, commit, checkout e pull |
| `--auto high` | Também pushes e deploys |

`--skip-permissions-unsafe` desliga todas as confirmações; deixe isso para contêineres descartáveis. Note que o código de saída 0 significa que o Droid terminou, não que a tarefa deu certo, então confira o resultado na CI. Para sessões interativas, você pode definir um nível padrão com `sessionDefaultSettings.autonomyLevel` e `permissionRules` mais finas (allow, ask, block) nas configurações.

## Passo 6: AGENTS.md e configurações

O Droid lê o `AGENTS.md` como as instruções do repositório. Mantenha-o curto: a stack, como rodar os testes, o que não mexer e o que significa “pronto”. Nosso guia sobre [CLAUDE.md e AGENTS.md](/pt/blog/claude-md-agents-md/ "CLAUDE.md e AGENTS.md") mostra o que colocar nele.

As configurações ficam em `~/.factory/settings.json` para você e em `.factory/settings.json` para o projeto, cada um com um `settings.local.json` para ajustes locais que você não commita.

## Passo 7: servidores MCP e droids próprios

Adicione servidores MCP pela linha de comando:

```bash
droid mcp add docs https://example.com/mcp --type http
droid mcp add memory "npx -y @modelcontextprotocol/server-memory"
```

Eles são salvos em `~/.factory/mcp.json` (ou `.factory/mcp.json` para o projeto) em `mcpServers`. Em uma sessão, `/mcp` gerencia esses servidores, incluindo logins OAuth.

Droids próprios são subagentes: um arquivo Markdown com um cabeçalho YAML (`name`, `description`, `model`, `tools` e mais) em `.factory/droids/` ou `~/.factory/droids/`. O Droid repassa trabalho a eles pela ferramenta Task, e `/droids` os gerencia. Um pequeno droid “escritor de testes” ou “revisor” num modelo barato é um bom primeiro droid.

## Quanto custa o Droid (em novembro de 2026)

| Plano | Preço | Observações |
|---|---|---|
| Free | US$ 0 | Você traz a inferência: ChatGPT, Copilot, OpenRouter ou suas próprias chaves |
| Pro | US$ 20/mês | Todos os modelos, app desktop, CLI e SDK |
| Plus | US$ 100/mês | Cerca de 5x o uso do Pro |
| Max | US$ 200/mês | Cerca de 10x o uso do Pro |
| Teams | US$ 60/mês + US$ 40/assento | Até 10 assentos |

Confira a [página de preços da Factory](https://factory.com/pricing "Preços da Factory") antes de decidir; os planos mudam com frequência.

## Erros comuns

- **Links antigos da documentação.** A documentação mudou de docs.factory.ai para [docs.factory.com](https://docs.factory.com "Documentação da Factory"); as URLs de instalação continuam usando app.factory.ai.
- **Rodar o exec com autonomia alta cedo demais.** Comece os jobs de CI com `--auto low` e aumente o nível só nas etapas que precisarem.
- **Confiar no código de saída 0.** Ele só quer dizer que a execução terminou. Confira os testes ou o diff depois.
- **`-r` significa duas coisas.** No `droid`, `-r` retoma uma sessão; no `droid exec`, define o esforço de raciocínio. Escreva `--resume` por extenso para evitar surpresas.

## Rodando o Droid ao lado de outras CLIs no AgentVera

Se o Droid é o seu único agente, os próprios apps da Factory podem bastar. Fica mais difícil quando o Droid roda ao lado do Claude Code, do Codex ou do Gemini CLI no mesmo projeto. O [AgentVera](/pt/ "AgentVera") é um app desktop que roda essas CLIs lado a lado em terminais reais, com as suas próprias instalações e logins. O [suporte ao Droid](/pt/agents/factory-droid/ "Factory Droid no AgentVera") funciona assim:

- **Uma sessão por agente.** O AgentVera encontra a sessão que o Droid cria e a reabre com `droid --resume <id>` nas próximas execuções, então a conversa sobrevive a um reinício do app.
- **Modelo, esforço e papel.** O modelo e o esforço que você escolhe para o agente são passados por um arquivo de configurações, e o papel do agente com `--append-system-prompt`.
- **Seu login ou suas chaves de API.** O Droid mantém o seu login da Factory. Em Configurações → Contas você pode adicionar contas com `FACTORY_API_KEY` e dar a cada agente a sua.
- **Painéis, worktrees e revisão.** Rode o Droid na grade do [workspace](/pt/features/workspace/ "Workspace") ao lado de outros agentes, cada um no seu próprio git worktree, e confira as mudanças com a [revisão de código](/pt/features/code-review/ "Revisão de código").

O plano gratuito inclui até 18 agentes, MCP, Git, Docker, SSH, revisão de código e economia de tokens. O Pro custa US$ 9,99 por mês; se você nunca teve um teste, seu primeiro login no app ativa o Pro por 7 dias sem cartão. Para experimentar, [baixe o AgentVera](/pt/download/ "Baixar o AgentVera").

## Conclusão

Para começar com o Droid bastam dois comandos: o script de instalação e `droid`. O que importa depois é o controle: mantenha as sessões interativas com aprovação, comece o `droid exec` com `--auto low`, coloque as regras do projeto no `AGENTS.md` e escolha um modelo por tarefa de olho no multiplicador de uso.

Fontes: [início rápido do Droid](https://docs.factory.com/cli/getting-started/quickstart "Início rápido do Droid"), [referência da CLI](https://docs.factory.com/docs/droid-cli/cli-reference "Referência da CLI do Droid"), [droid exec](https://docs.factory.com/docs/droid-exec/overview "droid exec"), [modelos](https://docs.factory.com/docs/models "Modelos do Droid"), [MCP](https://docs.factory.com/docs/harness/mcp "MCP no Droid"), [changelog](https://docs.factory.com/changelog/cli-updates "Changelog da CLI do Droid").

## Perguntas frequentes

**O Factory Droid é gratuito?** Existe um plano Free de US$ 0 em que você traz a inferência: faça login com ChatGPT, GitHub Copilot ou OpenRouter, ou adicione suas próprias chaves de API. Os planos pagos, em novembro de 2026, são Pro a US$ 20, Plus a US$ 100 e Max a US$ 200 por mês, com mais uso a cada nível.

**Posso usar minha própria chave de API com o Droid?** Sim. Adicione uma entrada customModels ao ~/.factory/settings.json com o nome do modelo, a URL base, o provedor e a chave (ela pode ser lida de uma variável de ambiente). As chaves ficam na sua máquina, e os modelos próprios funcionam na CLI e no app desktop.

**Qual a diferença entre droid e droid exec?** O droid abre uma sessão interativa que pergunta antes de cada edição ou comando. O droid exec roda uma única tarefa sem chat, para scripts e CI. Ele é somente leitura, a menos que você aumente a autonomia com --auto low, medium ou high.

**O Droid lê o AGENTS.md?** Sim. O AGENTS.md é o arquivo de instruções que o Droid lê em um repositório: coloque nele a stack, o comando de testes, as regras e o que não deve ser mexido.

**Como retomo uma sessão do Droid?** Rode droid --resume para escolher uma sessão recente, ou droid --resume <id> para uma específica. droid search "texto" encontra sessões antigas, e --fork <id> copia uma para você testar outro caminho.

---

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