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

goose es un asistente de IA de uso general que se ejecuta en tu equipo. Además de trabajar con código, puede realizar búsquedas, redactar, automatizar tareas y organizar datos. Puedes usarlo desde la aplicación de escritorio, la terminal o una interfaz, y las versiones de escritorio y terminal comparten la misma configuración de modelos. Es adecuado para tareas de programación repetitivas y también puede conectarse a GitHub, bases de datos y archivos.

Preparativos antes de la instalación

goose ofrece dos formas de instalación: Desktop y CLI. Desktop es la versión de escritorio con interfaz gráfica, mientras que CLI se utiliza introduciendo comandos en la terminal. Ambas comparten la configuración principal, incluidos el Provider y el modelo. Un Provider puede entenderse como la configuración de conexión que indica a goose qué servicio de modelos debe utilizar.

Si quieres una ventana

goose Desktop

Descarga el zip para macOS
O usa brew cask
En Linux, usa el paquete de instalación

Si solo quieres el terminal

goose CLI

download_cli.sh
O Homebrew CLI
Después, goose session

Windows

Primero elige un entorno

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

En macOS puedes descargar la aplicación o usar Homebrew. Para el escritorio de Linux, utiliza el paquete correspondiente a tu distribución. En Windows, consulta primero los entornos de terminal indicados.

Antes de empezar, prepara el ID del modelo que aparece en la lista actual de modelos. El ID del modelo es el nombre que utiliza el servicio para identificar un modelo concreto y debe copiarse completo.

Instalación y primer inicio

Si quieres una interfaz gráfica

Para macOS se ofrecen dos métodos de instalación:

Descargar la aplicación desde la página de instalación. Allí encontrarás versiones para macOS Silicon y macOS Intel. Después de descargarla, descomprime el archivo zip y ejecuta la aplicación que contiene.
También puedes utilizar Homebrew:

brew install --cask block-goose

Este comando descarga la misma aplicación y también puede encargarse de las actualizaciones.

Si utilizas un Apple Mac M3 y no aparece ninguna ventana después de abrir la aplicación, comprueba que ~/.config tenga permisos de lectura y escritura. goose necesita este directorio para guardar los registros.

Para la versión de escritorio de Linux, descarga el paquete desde la página de instalación. Se ofrecen paquetes DEB (Ubuntu/Debian), RPM (RHEL/Fedora) y Flatpak. En Debian o Ubuntu, descarga el archivo DEB, abre el directorio donde lo guardaste, ejecuta sudo dpkg -i (filename).deb y después abre goose desde el menú de aplicaciones. Sustituye (filename) por el nombre real del archivo.

Para la versión de escritorio de Windows, descarga el archivo desde la página de instalación, descomprime el zip y ejecuta la aplicación que contiene.

Si solo quieres la terminal

En macOS y Linux, ejecuta:

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

Si no quieres realizar una configuración interactiva durante la instalación, añade CONFIGURE=false al principio:

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 instalación existente de la CLI, utiliza:

goose update

En Windows se requiere uno de estos tres entornos: Git Bash, incluido con Git for Windows y marcado como recomendado; MSYS2; o PowerShell, incluido con Windows 10 y 11. En Git Bash y MSYS2, utiliza el mismo comando download_cli.sh anterior. En PowerShell, descarga primero el script y después ejecútalo:

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

Si aparece un aviso indicando que goose no está en PATH, sigue las instrucciones de la página de instalación para añadir ~/.local/bin o %USERPROFILE%\.local\bin a la configuración del shell actual y vuelve a abrir la terminal. PATH es el conjunto de directorios en los que la terminal busca programas. Si el directorio no está incluido, es posible que no puedas ejecutar un programa escribiendo directamente su nombre aunque ya esté instalado.

El 2026-10-09, la versión de la CLI era la 1.54.0. De forma predeterminada, el script de instalación coloca el programa en ~/.local/bin. Puedes cambiar este directorio mediante la variable de entorno GOOSE_BIN_DIR. Después de cambiarlo, el script no actualizará automáticamente la configuración del shell y la terminal avisará de que el directorio no está en PATH. Añade ese directorio a PATH o ejecuta el programa mediante su ruta completa.

La primera vez que utilices goose, se te pedirá que configures un Provider. Puedes omitir los proveedores incluidos y añadir un Provider personalizado siguiendo la sección siguiente. En la terminal, entra en el directorio donde quieras trabajar y ejecuta:

goose session

Obtener los parámetros de conexión de OmniProxy

Obtén de tu propia instancia de OmniProxy la dirección, la clave y el nombre del modelo. El ejemplo de Provider personalizado utiliza un base_url que termina en /v1/chat/completions, así que aquí se seguirá el mismo formato:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   copia los ID completos de la lista actual de modelos de OmniProxy; separa varios ID con comas inglesas

Copia el nombre completo desde la lista actual de OmniProxy, incluidas las barras. El 2026-10-09, los dos ID de referencia incluidos en la documentación de los proveedores eran grok-4.7 de Grok y gpt-6-luna de la documentación de OpenAI. gpt-6-luna admite Chat Completions; dentro de Chat Completions, las llamadas a funciones solo son compatibles cuando reasoning_effort tiene el valor none. No copies nombres que no aparezcan en la lista.

Completar la configuración de la herramienta

Los Provider personalizados utilizan formatos compatibles con OpenAI, Anthropic u Ollama. Un formato compatible significa que la herramienta envía solicitudes conforme a una interfaz común determinada. Para conectar OmniProxy, selecciona OpenAI Compatible.

Versión de escritorio

Haz clic en el botón de 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.
En Provider Type, selecciona OpenAI Compatible. Puedes escribir OmniProxy en Display Name. En API URL, introduce la dirección de la sección anterior. Si se necesita una clave, marca la opción que exige una API Key e introduce la clave de OmniProxy. En Available Models, introduce los nombres de los modelos, separados por comas inglesas si hay más de uno.
Haz clic en Create Provider.

Actualmente, la versión de escritorio no permite definir encabezados de solicitud personalizados en esta ventana. Si necesitas encabezados, modifica el archivo de configuración después de crear el Provider.

Terminal

Ejecuta:

goose configure

Selecciona Custom Providers y después Add A Custom Provider. En API Type, selecciona OpenAI Compatible y sigue las indicaciones para introducir el nombre, la API URL, si se necesita una clave, los nombres de los modelos y si se admiten respuestas en streaming.

Al realizar la configuración manual en Windows, si se produce un error del llavero, selecciona la opción de no guardar la clave en keyring cuando se te pregunte y utiliza una variable de entorno. Después, vuelve a ejecutar goose configure. El llavero es un pequeño almacén seguro que utiliza el sistema para guardar claves.

Archivo de configuración

Los directorios indicados son:

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

Puedes basar el archivo en el siguiente ejemplo. Sustituye el nombre, la dirección y los modelos por los tuyos. Guarda la clave en la variable de entorno indicada 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
}

En context_limit, conserva un valor numérico como en el ejemplo. El contexto real depende del modelo y de OmniProxy; no consideres el valor de este ejemplo como el límite oficial del modelo. Antes de utilizarlo, 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

Sustituye el valor de --model por el ID completo que figure en la lista. goose session no tiene un subcomando start. También puedes especificar --provider y --model mediante las variables de entorno GOOSE_PROVIDER y GOOSE_MODEL. Aunque la pasarela no valide la clave, OMNIPROXY_API_KEY debe tener algún valor; puede ser una cadena de relleno utilizada únicamente en tu equipo. El 2026-10-09, esta configuración permitió leer el archivo.

Ventana

Settings

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

Terminal

goose configure

Selecciona Custom Providers
Después, selecciona añadir
Elige OpenAI Compatible como tipo

Archivo

custom_providers

En macOS y Linux está en ~/.config
En Windows está en APPDATA
Configura base_url según el ejemplo oficial

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

Verificar una tarea real

Entra en un directorio que contenga un archivo normal y ejecuta el comando goose session de la sección anterior. Pídele que lea la primera línea del archivo que indiques. Debe mostrar el contenido del archivo, no limitarse a indicar que la configuración se ha guardado.

Para leer archivos o ejecutar comandos, la sesión necesita la extensión Developer. La extensión Developer puede entenderse como el módulo de herramientas que permite a goose trabajar con archivos y comandos locales. Por lo general, la configuración predeterminada ya la incluye. Si goose responde que no dispone de herramientas para archivos, añade al comando:

--with-builtin developer

No añadas también --no-profile, ya que ese parámetro desactiva las extensiones predeterminadas.

El 2026-10-09, goose 1.54.0 pudo leer la primera línea del archivo indicado. La primera respuesta puede tardar alrededor de un minuto.

Después, comprueba el origen y el nombre del modelo en el registro de llamadas de OmniProxy.

Inicio

Puedes entrar en una sesión

goose session
Provider es el que acabas de añadir
El nombre del modelo aparece en la lista

Tarea

Realmente la ha realizado

Por ejemplo, muestra el directorio actual
Revisa su respuesta
No te limites a comprobar que se guardó correctamente

Registro

Es visible en la puerta de enlace

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

Después de guardar el Provider, utiliza una sesión real para comprobarlo.

Errores frecuentes

No se encuentra el comando goose: añade el directorio de instalación a PATH siguiendo la página de instalación y vuelve a abrir la terminal.
No aparece ninguna ventana en la versión de escritorio para M3: comprueba los permisos de lectura y escritura de ~/.config.
Falla el llavero: no guardes la clave en keyring; utiliza una variable de entorno.
El modelo no aparece en la lista: en la versión de escritorio puedes seleccionar Use custom model e introducir manualmente el nombre del modelo. goose configure no permite introducir nombres de modelos personalizados; para la terminal, utiliza la versión de escritorio o modifica directamente GOOSE_MODEL en la configuración.
No se puede conectar con la dirección: comprueba que la API URL termine en /v1/chat/completions, como en el ejemplo, y que OmniProxy esté en ejecución.
Indica que no puede leer archivos: añade la extensión Developer y no utilices --no-profile.
Devuelve unsupported Responses role: system: normalmente la dirección es correcta. Prueba otro ID completo de la lista de modelos.

Referencias oficiales

Para la instalación, consulta Install goose. Para los Provider personalizados, consulta goose providers. Los ID de modelos utilizados en los ejemplos aparecen en la página de modelos de xAI y en 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 demuestra compatibilidad total con el Agente. Verifica el origen y el modelo en el registro de llamadas de OmniProxy.

Fuentes oficiales · goose ↗