# Cómo usar Goose: guía paso a paso de la CLI de Goose

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

Cómo usar Goose, el agente de IA de código abierto: instala la CLI, ejecuta goose configure, elige un modo, añade extensiones MCP, escribe AGENTS.md y usa recipes.

**En resumen:**

- Instala la CLI de Goose con un comando curl (o brew install block-goose-cli), deja que goose configure elija proveedor y modelo, y luego ejecuta goose session dentro de un proyecto y describe la tarea.
- Goose arranca en modo auto y ejecuta herramientas sin preguntar. Cambia a approve o smart_approve con /mode, o define GOOSE_MODE, antes de soltarlo en un repositorio real.
- Las reglas del proyecto van en AGENTS.md o .goosehints, los servidores MCP son extensiones en ~/.config/goose/config.yaml y goose run --recipe repite una tarea desde un archivo YAML.

Para usar Goose, instalas la CLI con `curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash`, respondes a las preguntas de `goose configure` para elegir proveedor y modelo, y luego ejecutas `goose session` dentro de un proyecto y describes lo que quieres. **Goose arranca en modo auto, así que ejecuta comandos sin preguntar hasta que cambies al modo approve.**

Esta guía cubre cada paso de la CLI de Goose a noviembre de 2026 (versión 1.58): instalación, configuración, modos, sesiones, extensiones, archivos de instrucciones y recipes, además de los errores que más tiempo hacen perder.

## Qué es Goose

Goose es un agente de IA de uso general que se ejecuta en tu máquina. Viene como CLI, como app de escritorio para macOS, Linux y Windows y como API, todo escrito en Rust. No depende de ningún modelo: tú aportas un proveedor como Anthropic, OpenAI, Gemini, OpenRouter o un modelo local, y Goose se encarga de las llamadas a herramientas, las ediciones y el trabajo en la shell.

Block creó Goose y lo cedió a la [Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation "Agentic AI Foundation"), bajo la Linux Foundation, en diciembre de 2025, junto con MCP y AGENTS.md. En abril de 2026 el repositorio se trasladó a [aaif-goose/goose](https://github.com/aaif-goose/goose "Goose en GitHub") y la documentación a [goose-docs.ai](https://goose-docs.ai "Documentación de Goose"). Los enlaces antiguos a `block/goose` y `block.github.io/goose` siguen redirigiendo. Se publica bajo Apache-2.0 y sale una versión nueva más o menos cada semana.

## Paso 1: instala la CLI

En macOS, Linux o Git Bash en Windows:

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

En macOS también puedes usar Homebrew. Los nombres de los paquetes todavía dicen “block”:

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

En Windows PowerShell:

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

El binario de Windows se instala en `%USERPROFILE%\.local\bin`, que quizá tengas que añadir al `PATH`. Más adelante actualizas con `goose update`. La CLI y la app de escritorio comparten una misma configuración, así que los proveedores y extensiones que configures en una aparecen en la otra.

## Paso 2: ejecuta goose configure

La primera ejecución lanza `goose configure` por sí sola. Tienes tres caminos: iniciar sesión en OpenRouter, iniciar sesión en Tetrate Agent Router Service o configurarlo a mano eligiendo un proveedor, pegando su clave y nombrando un modelo. Desde la versión 1.54 también pregunta en qué modo empezar.

Las claves se guardan en el llavero del sistema (el Llavero en macOS). Si no hay llavero, o defines `GOOSE_DISABLE_KEYRING`, van a un archivo `secrets.yaml` en texto plano. También puedes exportarlas:

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

Una clave escrita en `config.yaml` se ignora. Vuelve a ejecutar `goose configure` cuando quieras para cambiar de proveedor, añadir o activar y desactivar extensiones, o abrir los ajustes de modo y permisos de herramientas.

Si ya pagas Claude Code o ChatGPT Plus/Pro, echa un vistazo a los [proveedores ACP](https://goose-docs.ai/docs/guides/acp-providers "Proveedores ACP de Goose"): permiten que Goose use ese inicio de sesión en lugar de una clave de API.

## Paso 3: inicia una sesión

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

Describe la tarea con palabras sencillas. Teclas y comandos útiles dentro de una sesión:

- `Ctrl+J` añade una línea nueva; `Ctrl+C` detiene la petición en curso, o sale si la línea está vacía.
- `/mode`, `/model`, `/extension` y `/builtin` cambian la configuración sin salir.
- `/compact` acorta la conversación cuando se hace larga; `/clear` empieza de cero.
- `/status` muestra la sesión, incluido su ID.

Para volver más tarde, ejecuta `goose session -r -n checkout-fix`. `goose session list` muestra todas las sesiones, y `--fork` copia una para que pruebes otra dirección sin perder la original.

## Paso 4: elige un modo antes del trabajo real

Goose tiene cuatro modos:

| Modo | Qué hace |
|---|---|
| `auto` (predeterminado) | Ejecuta todas las herramientas sin preguntar |
| `approve` | Pregunta antes de cada llamada a una herramienta |
| `smart_approve` | Pregunta solo en las llamadas que considera arriesgadas |
| `chat` | Sin herramientas; solo conversación |

Cambia con `/mode approve` dentro de una sesión, define `GOOSE_MODE` o elige un modo predeterminado en `goose configure`. Para un control más fino, define permisos por herramienta en `goose configure`; se guardan en `permission.yaml`. En un repositorio que te importa, empieza en `approve` o `smart_approve` y aflójalo cuando confíes en la configuración.

## Paso 5: extensiones y servidores MCP

Las extensiones son la forma en que Goose obtiene herramientas, y cada servidor MCP es una extensión. La extensión Developer (shell y edición de archivos) está activada por defecto. Entre las demás integradas están Computer Controller, Memory y Auto Visualiser.

Para añadir una de forma permanente, ejecuta `goose configure` → **Add Extension** y elige un servidor de línea de comandos (stdio) o remoto (Streamable HTTP). Para una sola sesión:

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

Las extensiones guardadas están bajo `extensions:` en `~/.config/goose/config.yaml` (Windows: `%APPDATA%\Block\goose\config\config.yaml`). Los servidores SSE ya no son compatibles; usa Streamable HTTP.

## Paso 6: AGENTS.md y .goosehints

Goose lee `AGENTS.md` y después `.goosehints` en cada nivel, desde la carpeta de trabajo hasta la raíz de git, y recoge los anidados a medida que trabaja en subcarpetas. Un archivo global en `~/.config/goose/.goosehints` se aplica a todos los proyectos.

Si tu proyecto ya tiene un `CLAUDE.md`, no hace falta copiarlo:

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

Mantén el archivo corto: el stack, cómo ejecutar los tests, qué no tocar y qué significa “terminado”. Nuestra guía de [CLAUDE.md y AGENTS.md](/es/blog/claude-md-agents-md/ "CLAUDE.md y AGENTS.md") explica qué poner en él.

## Paso 7: goose run y recipes

Para tareas puntuales sin chat, usa `goose run`:

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

Una recipe es un archivo YAML que guarda una tarea con sus instrucciones, extensiones y parámetros, para que un compañero o un trabajo programado pueda repetirla:

```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` comprueba un archivo antes de compartirlo. Otros dos comandos que conviene conocer: `goose review` pide una revisión con IA de tu diff de git, y `goose info -v` muestra la versión y dónde están la configuración, las sesiones y los logs.

## Errores comunes

- **Dejar el modo auto activado.** El predeterminado ejecuta comandos de shell sin preguntar. Cambia de modo antes de la primera tarea en un repositorio real.
- **Seguir documentación antigua.** Los tutoriales de 2025 apuntan a `block/goose` y `block.github.io`. Los comandos casi siempre siguen funcionando, pero la documentación actual está en goose-docs.ai.
- **Poner claves en config.yaml.** Goose las ignora ahí. Usa el llavero, `goose configure` o variables de entorno.
- **Usar los proveedores CLI obsoletos.** Para trabajar con un inicio de sesión de Claude Code o ChatGPT, configura un proveedor ACP.
- **Sesiones largas.** La compactación automática mantiene el contexto bajo control, pero una sesión nueva con nombre para cada tarea mantiene las respuestas más precisas.

## Goose junto a otras CLI en AgentVera

Goose tiene su propia app de escritorio, y si Goose es el único agente que usas, puede que no necesites más. La cosa se complica cuando Goose trabaja junto a Claude Code, Codex o Gemini CLI en el mismo proyecto. [AgentVera](/es/ "AgentVera") es una app de escritorio que ejecuta estas CLI lado a lado en terminales reales, con tus propias instalaciones y claves. El [soporte de Goose](/es/agents/goose/ "Goose en AgentVera") funciona así:

- **Una sesión con nombre por agente.** Cada agente Goose recibe su propio nombre de sesión, y AgentVera la reabre con `goose session --resume --name` en los siguientes arranques, así que la conversación sobrevive a un reinicio de la app.
- **Tu proveedor y tus claves.** Goose sigue usando el proveedor de `goose configure`. En Ajustes → Cuentas puedes añadir cuentas con clave de API (Anthropic, OpenAI, OpenRouter, Google) para los agentes Goose.
- **Modelo, esfuerzo y rol.** El modelo que eliges se pasa con `--model`, el nivel de esfuerzo mediante `GOOSE_THINKING_EFFORT` y el rol del agente con `--system`.
- **MCP y el navegador.** Los servidores del [gestor de MCP](/es/features/mcp-manager/ "Gestor de MCP") de AgentVera se pasan como `--with-extension` o `--with-streamable-http-extension`, así que los configuras una sola vez para todas las CLI.
- **Paneles, worktrees y revisión.** Ejecuta Goose en la cuadrícula del [workspace](/es/features/workspace/ "Workspace") junto a otros agentes, cada uno en su propio git worktree, y comprueba sus cambios con la revisión de código.

El plan gratuito incluye hasta 18 agentes, MCP, Git, Docker, SSH, revisión de código y ahorro de tokens. Pro cuesta 9,99 $ al mes; si nunca has tenido una prueba, tu primer inicio de sesión en la app activa Pro durante 7 días sin tarjeta. Para probarlo, [descarga AgentVera](/es/download/ "Descargar AgentVera").

## Conclusión

Para empezar con Goose bastan tres comandos: la instalación, `goose configure` y `goose session`. Los ajustes que más importan vienen justo después: pasar del modo auto a approve, añadir las extensiones que necesitas y darle al proyecto un `AGENTS.md`. Cuando una tarea se repita, guárdala como recipe.

Fuentes: [instalación de Goose](https://goose-docs.ai/docs/getting-started/installation "Instalar Goose"), [comandos de la CLI](https://goose-docs.ai/docs/guides/goose-cli-commands "Comandos de la CLI de Goose"), [permisos](https://goose-docs.ai/docs/guides/managing-tools/goose-permissions "Modos de permisos de Goose"), [extensiones](https://goose-docs.ai/docs/getting-started/using-extensions "Usar extensiones"), [archivos de hints](https://goose-docs.ai/docs/guides/context-engineering/using-goosehints "Usar .goosehints"), [versiones](https://github.com/aaif-goose/goose/releases "Versiones de Goose").

## Preguntas frecuentes

**¿Goose es gratis?** Sí. Goose es de código abierto bajo la licencia Apache-2.0 y no cuesta nada. Pagas a tu proveedor de modelos por los tokens que usa, o ejecutas un modelo local con Ollama, LM Studio o Docker Model Runner sin coste de tokens.

**¿Quién desarrolla Goose ahora?** Block creó Goose y lo cedió a la Agentic AI Foundation (AAIF), bajo la Linux Foundation, en diciembre de 2025. Desde abril de 2026 el código está en github.com/aaif-goose/goose y la documentación en goose-docs.ai.

**¿Puede Goose usar mi suscripción de Claude Code o ChatGPT?** Sí, mediante los proveedores ACP, que permiten a Goose usar un inicio de sesión existente de Claude Code o ChatGPT Plus/Pro. Los antiguos proveedores CLI que hacían esto quedan obsoletos en favor de los proveedores ACP.

**¿Goose lee AGENTS.md o CLAUDE.md?** Goose lee AGENTS.md y después .goosehints en cada nivel, desde la carpeta de trabajo hasta la raíz de git. Para cargar también CLAUDE.md o .cursorrules, añádelos a la variable de entorno CONTEXT_FILE_NAMES.

**¿Goose pregunta antes de ejecutar comandos?** No por defecto. El modo predeterminado es auto, que ejecuta herramientas sin preguntar. El modo approve pregunta antes de cada llamada a una herramienta, smart_approve solo en las arriesgadas y el modo chat desactiva las herramientas.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/