Instalación de goose y configuración de un proveedor personalizado

goose es un asistente de IA de propósito general que se ejecuta en tu ordenador. Además de programar, puede manejar investigación, escritura, automatización y organización de datos. Puedes usarlo a través de la aplicación de escritorio, el terminal o la API, y las versiones de escritorio y de terminal comparten la misma configuración de modelo. Es adecuado para tareas de programación repetitivas y también puede conectarse a GitHub, bases de datos y archivos.

Antes de empezar

goose ofrece dos opciones de instalación: Escritorio y CLI. Escritorio es la versión gráfica con una ventana, mientras que CLI se utiliza introduciendo comandos en un terminal. Ambas comparten la misma configuración central, incluyendo el Proveedor y el modelo. Un Proveedor es la configuración de conexión que le dice a goose qué servicio de modelo utilizar.

Quieres una ventana

goose Desktop

Descargar el zip en macOS
O usar brew cask
Usar el paquete instalador en Linux

Solo terminal

goose CLI

download_cli.sh
O la CLI de Homebrew
Luego ejecutar goose session

Windows

Elegir un entorno primero

Git Bash o MSYS2
También puedes usar PowerShell
Si no se encuentra el comando, añadirlo a PATH

En macOS, puedes instalarlo descargando la aplicación o usando Homebrew. En Linux, utiliza el paquete de tu distribución para la versión de escritorio. En Windows, comprueba primero los entornos de terminal compatibles.

Antes de empezar, ten listo el ID del modelo de la lista de modelos actual. Un ID de modelo es el nombre que utiliza el servicio de modelo para identificar un modelo específico, y debes copiar el ID completo al utilizarlo.

Instalación y lanzamiento por primera vez

Si quieres una ventana gráfica

Existen dos métodos de instalación documentados para macOS:

Descárgalo desde la página de instalación. La página proporciona versiones para macOS Silicon y macOS Intel. Después de descargar, extrae el archivo zip y ejecuta la aplicación en su interior.
Alternativamente, utiliza Homebrew:

brew install --cask block-goose

Esto descarga la misma aplicación y también puede gestionar actualizaciones.

Si estás utilizando un Apple Mac M3 y no aparece ninguna ventana después de abrir la aplicación, comprueba si ~/.config es legible y escribible. goose utiliza este directorio para escribir registros.

Para la versión de escritorio de Linux, descárgala desde la página de instalación. Los paquetes disponibles son DEB para Ubuntu/Debian, RPM para RHEL/Fedora y Flatpak. En Debian o Ubuntu, descarga el archivo DEB, abre el directorio donde se guardó, ejecuta sudo dpkg -i (filename).deb y luego abre goose desde el menú de aplicaciones. Reemplaza (filename) con el nombre real del archivo.

Para la versión de escritorio de Windows, descárgala desde la página de instalación, extrae el archivo zip y ejecuta la aplicación en su interior.

Si solo quieres la versión de terminal

En macOS y Linux, ejecuta:

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

Para omitir la configuración interactiva durante la instalación, añade CONFIGURE=false antes de bash:

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

En macOS, también puedes ejecutar:

brew install block-goose-cli

Para actualizar una CLI instalada, ejecuta:

goose update

En Windows, se requiere uno de los siguientes tres entornos: Git Bash, que se incluye con Git para Windows y está marcado como recomendado; MSYS2; o PowerShell incluido con Windows 10/11. En Git Bash y MSYS2, utiliza el mismo comando download_cli.sh mostrado anteriormente. En PowerShell, descarga el script primero y luego ejecútalo:

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

Si se te dice que goose no está en PATH, sigue la página de instalación y añade ~/.local/bin o %USERPROFILE%\.local\bin a la configuración actual del shell, luego reabre el terminal. PATH es un conjunto de directorios que el terminal busca para encontrar programas. Si el directorio de instalación no está incluido, es posible que no puedas ejecutar un programa instalado introduciendo su nombre directamente.

A fecha de 09-10-2026, la versión de CLI era 1.54.0. Por defecto, el script de instalación coloca el programa en ~/.local/bin. Puedes cambiar este directorio con la variable de entorno GOOSE_BIN_DIR. Si lo cambias, el script no actualizará automáticamente la configuración del shell, y el terminal informará de que el directorio no está en PATH. Añade ese directorio a PATH o ejecuta goose utilizando su ruta completa.

La primera vez que utilices goose, te pedirá que configures un Proveedor. Puedes omitir los proveedores integrados y añadir un Proveedor personalizado como se describe en la siguiente sección. En el terminal, navega al directorio donde quieres trabajar y ejecuta:

goose session

Obtener valores de conexión de OmniProxy

Prepara la dirección, la clave y el nombre del modelo de tu propia instancia de OmniProxy. El ejemplo de Proveedor personalizado utiliza un base_url que termina en /v1/chat/completions, por lo que esta guía sigue el mismo formato:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   Copy from the current OmniProxy model list; separate multiple models with commas

Copia el nombre completo del modelo de la lista actual de OmniProxy, incluyendo cualquier barra inclinada. A fecha de 09-10-2026, dos IDs de referencia en la documentación del proveedor eran grok-4.7 para Grok y gpt-6-luna de la documentación de OpenAI. gpt-6-luna admite Chat Completions; la llamada a funciones en Chat Completions solo se admite cuando reasoning_effort se establece en none. No copies un nombre que no aparezca en la lista.

Introducir la configuración de la herramienta

Un Proveedor personalizado puede utilizar un formato compatible con OpenAI, Anthropic u Ollama. Un formato compatible significa que la herramienta envía solicitudes de acuerdo con una especificación de API común. Al conectarte a OmniProxy, selecciona OpenAI Compatible.

Escritorio

Haz clic en el botón en la esquina superior izquierda para abrir la barra lateral.
Haz clic en Settings.
Haz clic en Models.
Haz clic en Configure providers.
Haz clic en Add Custom Provider en la parte inferior de la ventana.
Para Provider Type, selecciona OpenAI Compatible. Puedes establecer Display Name en OmniProxy. Introduce la dirección de la sección anterior en API URL. Si se requiere una clave, selecciona la opción que requiere una API Key e introduce tu clave de OmniProxy. En Available Models, introduce los nombres de los modelos, separando varios nombres con comas.
Haz clic en Create Provider.

La versión de escritorio actualmente no puede definir encabezados de solicitud personalizados en esta ventana. Si necesitas encabezados de solicitud, edita el archivo de configuración después de crear el Proveedor.

Terminal

Ejecuta:

goose configure

Selecciona Custom Providers, luego selecciona Add A Custom Provider. Para API Type, selecciona OpenAI Compatible, luego sigue las instrucciones para introducir el nombre, la URL de la API, si se requiere una clave, los nombres de los modelos y si se admiten respuestas en streaming.

Al configurar manualmente en Windows, si el llavero (keychain) informa de un error, las instrucciones de instalación dicen que rechaces guardar la clave en el llavero y utilices una variable de entorno en su lugar. Luego ejecuta goose configure de nuevo. El llavero es un pequeño sistema de almacenamiento seguro utilizado por el sistema operativo para almacenar secretos.

Archivo de configuración

Los directorios documentados son:

macOS y Linux: ~/.config/goose/custom_providers/
Windows: %APPDATA%\Block\goose\config\custom_providers\

Puedes basar el archivo en el ejemplo proporcionado. Reemplaza el nombre, la dirección y los modelos con tus propios valores. Almacena la clave en la variable de entorno especificada por api_key_env; no escribas la clave real en el archivo:

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Mantén un valor numérico para context_limit, como se muestra en el ejemplo. El límite de contexto real depende del modelo y de OmniProxy; no trates el número de ejemplo como el límite oficial del modelo. Antes de usarlo, ejecuta:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

Después de entrar en el directorio de trabajo, ejecuta:

goose session --provider omniproxy --model grok-4.7

Reemplaza el valor de --model con el ID completo de la lista. goose session no tiene un subcomando start. También puedes establecer --provider y --model a través de las variables de entorno GOOSE_PROVIDER y GOOSE_MODEL. Incluso si la pasarela no valida las claves, OMNIPROXY_API_KEY debe tener un valor. Puede ser una cadena de marcador de posición utilizada solo en tu ordenador local. Esta configuración leyó correctamente un archivo en las pruebas del 09-10-2026.

Ventana

Settings

Settings en la barra lateral
Página de Models
Add Custom Provider

Terminal

goose configure

Seleccionar Custom Providers
Luego seleccionar add
Elegir OpenAI Compatible como tipo

Archivo

custom_providers

En macOS y Linux, está bajo ~/.config
En Windows, está bajo APPDATA
Establecer base_url según el ejemplo oficial

Los tres métodos crean el mismo tipo de configuración. Selecciona OpenAI Compatible como tipo de Proveedor.

Verificar con una tarea real

Abre un directorio que contenga un archivo regular y ejecuta goose session como se muestra en la sección anterior. Pídele que lea la primera línea de un archivo que especifiques. Debería devolver el contenido del archivo en lugar de solo decir que la configuración se guardó.

Para leer archivos o ejecutar comandos, la sesión necesita la extensión Developer. La extensión Developer es un módulo de herramientas que permite a goose trabajar con archivos y comandos locales. Generalmente se incluye en la configuración predeterminada. Si goose dice que no tiene herramientas de archivo, añade lo siguiente al comando:

--with-builtin developer

No añadas también --no-profile, porque esa opción desactiva las extensiones predeterminadas.

En las pruebas del 09-10-2026, goose 1.54.0 leyó correctamente la primera línea del archivo especificado. La primera respuesta puede tardar alrededor de un minuto.

Luego comprueba los registros de solicitudes de OmniProxy para confirmar el origen y el nombre del modelo.

Lanzar

Se abre una sesión

goose session
El proveedor es el que se acaba de añadir
El nombre del modelo está en la lista

Tarea

Realmente completó la tarea

Por ejemplo, listar el directorio actual
Revisar su respuesta
No confiar solo en un guardado exitoso

Registros

Visibles en la pasarela

Usar la dirección del ejemplo de la documentación
No poner la clave en el repositorio
El ID del modelo coincide con la lista

Después de guardar el Proveedor, confírmalo con una sesión real.

Errores comunes

No se puede encontrar el comando goose: Añade el directorio de instalación a PATH como se describe en la página de instalación, luego reabre el terminal.
No aparece ninguna ventana en la versión de escritorio en un Mac M3: Comprueba los permisos de lectura y escritura para ~/.config.
El llavero falla: No guardes la clave en el llavero; utiliza una variable de entorno en su lugar.
El modelo no está en la lista: En la versión de escritorio, selecciona Use custom model e introduce el nombre del modelo manualmente. goose configure no puede aceptar un nombre de modelo personalizado. Para el uso en terminal, cambia a la versión de escritorio o edita GOOSE_MODEL directamente en la configuración.
No se puede alcanzar la dirección: Confirma que la URL de la API termina en /v1/chat/completions, como en el ejemplo, y que OmniProxy está en ejecución.
Dice que no puede leer archivos: Añade la extensión Developer y no utilices --no-profile.
Devuelve unsupported Responses role: system: La dirección suele ser correcta. Cambia a otro ID completo de la lista de modelos.

Referencias oficiales

Para la instalación, consulta Instalar goose. Para proveedores personalizados, consulta proveedores de goose. Para los IDs de modelos utilizados en los ejemplos, consulta la página de modelos de xAI y GPT-6 Luna.

Reemplaza cada marcador de posición con valores de tu propia configuración de OmniProxy. Nunca publiques una clave real.

Un resultado guardado o HTTP 200 por sí solo no prueba la compatibilidad total del Agente. Comprueba el origen y el modelo en el registro de llamadas de OmniProxy.

Fuentes oficiales · goose ↗