# Como usar o Goose: guia passo a passo da CLI do Goose

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

Como usar o Goose, o agente de IA open source: instale a CLI, rode goose configure, escolha um modo, adicione extensões MCP, escreva o AGENTS.md e rode recipes.

**Resumo:**

- Instale a CLI do Goose com um comando curl (ou brew install block-goose-cli), deixe o goose configure escolher provedor e modelo, depois rode goose session dentro de um projeto e descreva a tarefa.
- O Goose começa no modo auto e roda ferramentas sem perguntar. Mude para approve ou smart_approve com /mode, ou defina GOOSE_MODE, antes de soltá-lo em um repositório de verdade.
- As regras do projeto ficam no AGENTS.md ou no .goosehints, servidores MCP são extensões em ~/.config/goose/config.yaml, e goose run --recipe repete uma tarefa a partir de um arquivo YAML.

Para usar o Goose, você instala a CLI com `curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash`, responde às perguntas do `goose configure` para escolher um provedor e um modelo, depois roda `goose session` dentro de um projeto e descreve o que quer. **O Goose começa no modo auto, então roda comandos sem perguntar até você mudar para o modo approve.**

Este guia cobre cada etapa da CLI do Goose em novembro de 2026 (versão 1.58): instalação, configuração, modos, sessões, extensões, arquivos de instruções e recipes, além dos erros que mais fazem as pessoas perderem tempo.

## O que é o Goose

O Goose é um agente de IA de uso geral que roda na sua máquina. Ele vem como CLI, como app desktop para macOS, Linux e Windows e como API, tudo feito em Rust. Ele não depende de um modelo específico: você traz um provedor como Anthropic, OpenAI, Gemini, OpenRouter ou um modelo local, e o Goose cuida das chamadas de ferramentas, das edições e do trabalho no shell.

A Block criou o Goose e o doou à [Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation "Agentic AI Foundation"), sob a Linux Foundation, em dezembro de 2025, junto com o MCP e o AGENTS.md. Em abril de 2026 o repositório foi para [aaif-goose/goose](https://github.com/aaif-goose/goose "Goose no GitHub") e a documentação para [goose-docs.ai](https://goose-docs.ai "Documentação do Goose"). Links antigos para `block/goose` e `block.github.io/goose` continuam redirecionando. Ele é distribuído sob Apache-2.0, e sai uma versão nova mais ou menos toda semana.

## Passo 1: instale a CLI

No macOS, no Linux ou no Git Bash no Windows:

```bash
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash
```

No macOS você também pode usar o Homebrew. Os nomes dos pacotes ainda dizem “block”:

```bash
brew install block-goose-cli        # CLI
brew install --cask block-goose     # desktop app
```

No Windows PowerShell:

```powershell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"; .\download_cli.ps1
```

O binário do Windows vai para `%USERPROFILE%\.local\bin`, que talvez você precise adicionar ao `PATH`. Para atualizar depois, use `goose update`. A CLI e o app desktop compartilham uma única configuração, então provedores e extensões definidos em um aparecem no outro.

## Passo 2: rode o goose configure

A primeira execução abre o `goose configure` sozinha. Você tem três caminhos: entrar no OpenRouter, entrar no Tetrate Agent Router Service ou configurar manualmente, escolhendo um provedor, colando a chave dele e informando um modelo. Desde a versão 1.54 ele também pergunta em qual modo começar.

As chaves vão para o chaveiro do sistema (o Keychain no macOS). Se não houver chaveiro, ou se você definir `GOOSE_DISABLE_KEYRING`, elas vão para um arquivo `secrets.yaml` em texto puro. Você também pode exportá-las:

```bash
export ANTHROPIC_API_KEY=...
export GOOSE_PROVIDER=anthropic
export GOOSE_MODEL=claude-sonnet-5-5
```

Uma chave escrita no `config.yaml` é ignorada. Rode o `goose configure` de novo quando quiser para trocar de provedor, adicionar ou ligar e desligar extensões, ou abrir as configurações de modo e de permissões das ferramentas.

Se você já paga pelo Claude Code ou pelo ChatGPT Plus/Pro, veja os [provedores ACP](https://goose-docs.ai/docs/guides/acp-providers "Provedores ACP do Goose"): eles permitem que o Goose use esse login em vez de uma chave de API.

## Passo 3: inicie uma sessão

```bash
cd my-project
goose session -n checkout-fix
```

Descreva a tarefa com palavras simples. Teclas e comandos úteis dentro de uma sessão:

- `Ctrl+J` adiciona uma nova linha; `Ctrl+C` interrompe o pedido atual, ou sai se a linha estiver vazia.
- `/mode`, `/model`, `/extension` e `/builtin` mudam a configuração sem sair.
- `/compact` encurta a conversa quando ela fica longa; `/clear` começa do zero.
- `/status` mostra a sessão, incluindo o ID dela.

Para voltar depois, rode `goose session -r -n checkout-fix`. `goose session list` mostra todas as sessões, e `--fork` copia uma para você tentar outro caminho sem perder a original.

## Passo 4: escolha um modo antes do trabalho de verdade

O Goose tem quatro modos:

| Modo | O que faz |
|---|---|
| `auto` (padrão) | Roda todas as ferramentas sem perguntar |
| `approve` | Pergunta antes de cada chamada de ferramenta |
| `smart_approve` | Pergunta só nas chamadas que considera arriscadas |
| `chat` | Sem ferramentas; só conversa |

Mude com `/mode approve` dentro de uma sessão, defina `GOOSE_MODE` ou escolha um padrão no `goose configure`. Para um controle mais fino, defina permissões por ferramenta no `goose configure`; elas ficam salvas em `permission.yaml`. Em um repositório que importa para você, comece em `approve` ou `smart_approve` e afrouxe quando confiar na configuração.

## Passo 5: extensões e servidores MCP

É pelas extensões que o Goose ganha ferramentas, e todo servidor MCP é uma extensão. A extensão Developer (shell e edição de arquivos) vem ligada por padrão. Entre as outras embutidas estão Computer Controller, Memory e Auto Visualiser.

Para adicionar uma de vez, rode `goose configure` → **Add Extension** e escolha um servidor de linha de comando (stdio) ou remoto (Streamable HTTP). Para uma única sessão:

```bash
goose session --with-extension "memory:npx -y @modelcontextprotocol/server-memory"
goose session --with-streamable-http-extension https://example.com/mcp
```

As extensões salvas ficam em `extensions:` no `~/.config/goose/config.yaml` (Windows: `%APPDATA%\Block\goose\config\config.yaml`). Servidores SSE não são mais suportados; use Streamable HTTP.

## Passo 6: AGENTS.md e .goosehints

O Goose lê o `AGENTS.md` e depois o `.goosehints` em cada nível, da pasta de trabalho até a raiz do git, e inclui os aninhados à medida que trabalha em subpastas. Um arquivo global em `~/.config/goose/.goosehints` vale para todos os projetos.

Se o seu projeto já tem um `CLAUDE.md`, não precisa copiá-lo:

```bash
export CONTEXT_FILE_NAMES='["AGENTS.md", ".goosehints", "CLAUDE.md"]'
```

Mantenha o arquivo curto: a stack, como rodar os testes, o que não mexer e o que “pronto” significa. Nosso guia de [CLAUDE.md e AGENTS.md](/pt/blog/claude-md-agents-md/ "CLAUDE.md e AGENTS.md") explica o que colocar nele.

## Passo 7: goose run e recipes

Para tarefas avulsas sem chat, use `goose run`:

```bash
goose run -t "add a unit test for the price formatter"
goose run -i task.md --output-format json
```

Uma recipe é um arquivo YAML que salva uma tarefa com suas instruções, extensões e parâmetros, para que um colega ou um job agendado possa repeti-la:

```bash
goose run --recipe release-notes.yaml --params version=2.4.0
goose schedule add --schedule-id weekly-notes --cron "0 0 9 * * 1" --recipe-source release-notes.yaml
```

`goose recipe validate` confere um arquivo antes de você compartilhá-lo. Outros dois comandos que vale conhecer: `goose review` pede uma revisão por IA do seu diff do git, e `goose info -v` mostra a versão e onde ficam a configuração, as sessões e os logs.

## Erros comuns

- **Deixar o modo auto ligado.** O padrão roda comandos de shell sem perguntar. Mude de modo antes da primeira tarefa em um repositório de verdade.
- **Seguir documentação antiga.** Tutoriais de 2025 apontam para `block/goose` e `block.github.io`. Os comandos quase sempre ainda funcionam, mas a documentação atual está em goose-docs.ai.
- **Colocar chaves no config.yaml.** O Goose as ignora ali. Use o chaveiro, o `goose configure` ou variáveis de ambiente.
- **Usar os provedores CLI descontinuados.** Para rodar com um login do Claude Code ou do ChatGPT, configure um provedor ACP.
- **Sessões longas.** A compactação automática mantém o contexto sob controle, mas uma sessão nova e nomeada por tarefa mantém as respostas mais precisas.

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

O Goose tem seu próprio app desktop, e se ele é o único agente que você usa, isso pode bastar. Fica mais difícil quando o Goose 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 chaves. O [suporte ao Goose](/pt/agents/goose/ "Goose no AgentVera") funciona assim:

- **Uma sessão nomeada por agente.** Cada agente Goose recebe seu próprio nome de sessão, e o AgentVera a reabre com `goose session --resume --name` nas próximas execuções, então a conversa sobrevive a um reinício do app.
- **Seu provedor e suas chaves.** O Goose continua usando o provedor do `goose configure`. Em Configurações → Contas você pode adicionar contas com chave de API (Anthropic, OpenAI, OpenRouter, Google) para agentes Goose.
- **Modelo, esforço e papel.** O modelo que você escolhe é passado com `--model`, o nível de esforço via `GOOSE_THINKING_EFFORT` e o papel do agente com `--system`.
- **MCP e o navegador.** Os servidores do [gerenciador de MCP](/pt/features/mcp-manager/ "Gerenciador de MCP") do AgentVera são passados como `--with-extension` ou `--with-streamable-http-extension`, então você os configura uma vez para todas as CLIs.
- **Painéis, worktrees e revisão.** Rode o Goose 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.

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 Goose bastam três comandos: a instalação, `goose configure` e `goose session`. As configurações que mais importam vêm logo depois: trocar o modo auto pelo approve, adicionar as extensões de que você precisa e dar ao projeto um `AGENTS.md`. Quando uma tarefa se repetir, salve-a como recipe.

Fontes: [instalação do Goose](https://goose-docs.ai/docs/getting-started/installation "Instalar o Goose"), [comandos da CLI](https://goose-docs.ai/docs/guides/goose-cli-commands "Comandos da CLI do Goose"), [permissões](https://goose-docs.ai/docs/guides/managing-tools/goose-permissions "Modos de permissão do Goose"), [extensões](https://goose-docs.ai/docs/getting-started/using-extensions "Usando extensões"), [arquivos de hints](https://goose-docs.ai/docs/guides/context-engineering/using-goosehints "Usando o .goosehints"), [versões](https://github.com/aaif-goose/goose/releases "Versões do Goose").

## Perguntas frequentes

**O Goose é gratuito?** Sim. O Goose é open source sob a licença Apache-2.0 e não custa nada. Você paga ao seu provedor de modelos pelos tokens usados, ou roda um modelo local pelo Ollama, LM Studio ou Docker Model Runner sem custo de tokens.

**Quem desenvolve o Goose hoje?** A Block criou o Goose e o doou à Agentic AI Foundation (AAIF), sob a Linux Foundation, em dezembro de 2025. Desde abril de 2026 o código fica em github.com/aaif-goose/goose e a documentação em goose-docs.ai.

**O Goose pode usar minha assinatura do Claude Code ou do ChatGPT?** Sim, pelos provedores ACP, que permitem ao Goose usar um login existente do Claude Code ou do ChatGPT Plus/Pro. Os antigos provedores CLI que faziam isso foram descontinuados em favor dos provedores ACP.

**O Goose lê AGENTS.md ou CLAUDE.md?** O Goose lê o AGENTS.md e depois o .goosehints em cada nível, da pasta de trabalho até a raiz do git. Para carregar também o CLAUDE.md ou o .cursorrules, adicione-os à variável de ambiente CONTEXT_FILE_NAMES.

**O Goose pergunta antes de rodar comandos?** Não por padrão. O modo padrão é auto, que roda ferramentas sem perguntar. O modo approve pergunta antes de cada chamada de ferramenta, o smart_approve só nas arriscadas, e o modo chat desliga as ferramentas.

---

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