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 computadora. 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, la terminal o la API, y las versiones de escritorio y 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 comenzar

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

¿Quieres una ventana?

goose Desktop

Descarga el zip en macOS
O usa brew cask
Usa el paquete instalador en Linux

Solo terminal

goose CLI

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

Windows

Elige un entorno primero

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

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

Antes de comenzar, 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 usarlo.

Instalación y primer inicio

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, usa Homebrew:

brew install --cask block-goose

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

Si estás usando un Apple Mac M3 y no aparece ninguna ventana después de abrir la aplicación, verifica 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, agrega 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, usa el mismo comando download_cli.sh que se muestra arriba. 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 te dicen que goose no está en PATH, sigue la página de instalación y agrega ~/.local/bin o %USERPROFILE%\.local\bin a la configuración actual del shell, luego reabre la terminal. PATH es un conjunto de directorios en los que la terminal busca programas. Si el directorio de instalación no está incluido, es posible que no puedas ejecutar un programa instalado ingresando su nombre directamente.

A fecha del 09-10-2026, la versión de CLI era 1.54.0. De forma predeterminada, 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 la terminal informará que el directorio no está en PATH. Agrega ese directorio a PATH o ejecuta goose usando su ruta completa.

La primera vez que uses goose, te pedirá que configures un Proveedor. Puedes omitir los proveedores integrados y agregar un Proveedor personalizado como se describe en la siguiente sección. En la 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 usa 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 diagonal. A fecha del 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 está configurado en none. No copies un nombre que no aparezca en la lista.

Ingresar la configuración de la herramienta

Un Proveedor personalizado puede usar 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. Ingresa 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 ingresa tu clave de OmniProxy. En Available Models, ingresa 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 ingresar el nombre, la URL de la API, si se requiere una clave, los nombres de los modelos y si se admiten respuestas de transmisión (streaming).

Al configurar manualmente en Windows, si el llavero (keychain) informa un error, las instrucciones de instalación dicen que rechaces guardar la clave en el llavero y uses una variable de entorno en su lugar. Luego ejecuta goose configure nuevamente. 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 ingresar al 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 puerta de enlace no valida las claves, OMNIPROXY_API_KEY aún debe tener un valor. Puede ser una cadena de marcador de posición utilizada solo en tu computadora local. Esta configuración leyó con éxito 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, agrega lo siguiente al comando:

--with-builtin developer

No agregues también --no-profile, porque esa opción deshabilita las extensiones predeterminadas.

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

Luego revisa los registros de solicitudes de OmniProxy para confirmar la fuente y el nombre del modelo.

Iniciar

Se abre una sesión

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

Tarea

Realmente completó la tarea

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

Registros

Visibles en la puerta de enlace

Usar la dirección del ejemplo de la documentación
No pongas 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: Agrega el directorio de instalación a PATH como se describe en la página de instalación, luego reabre la terminal.
No aparece ninguna ventana en la versión de escritorio en un Mac M3: Verifica los permisos de lectura y escritura para ~/.config.
El llavero falla: No guardes la clave en el llavero; usa 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 ingresa el nombre del modelo manualmente. goose configure no puede aceptar un nombre de modelo personalizado. Para uso en terminal, cambia a la versión de escritorio o edita GOOSE_MODEL directamente en la configuración.
No se puede acceder a la dirección: Confirma que la URL de la API termine en /v1/chat/completions, como en el ejemplo, y que OmniProxy esté en ejecución.
Dice que no puede leer archivos: Agrega la extensión Developer y no uses --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 completa del Agente. Verifica el origen y el modelo en el registro de llamadas de OmniProxy.

Fuentes oficiales · goose ↗