Goose + JoinGonka Gateway: su propio proveedor y clave en keyring

Paso 1: instalar Goose. Los métodos oficiales para la CLI según la documentación del proyecto:

# macOS and Linux: the script puts the binary in ~/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# macOS, Homebrew
brew install block-goose-cli

La variable CONFIGURE=false desactiva el asistente goose configure, que si no el script lanza justo después de la instalación: el proveedor lo configurará el instalador. Si el directorio ~/.local/bin no está en el PATH, el script te lo dirá. Para Windows hay un script download_cli.ps1 en el mismo repositorio, y la aplicación de escritorio se descarga desde la página de documentación; tanto ella como la CLI leen la misma configuración, así que todo lo de abajo vale para ambas. Para comprobar: goose --version.

Paso 2: obtener la clave. Regístrate en gate.joingonka.ai/register, confirma tu dirección y crea una clave con el prefijo jg- en la sección «API keys». Una sola clave y un solo saldo sirven para todos los modelos de la red.

Paso 3: ejecutar el instalador.

npx @joingonka/setup --tool goose

El instalador te pedirá la clave —no se pasa como argumento en la línea de comandos, para que no quede en el historial del shell— y hará lo siguiente:

• creará el archivo de proveedor custom_providers/custom_joingonka.json con la dirección del gateway y tres modelos de la red con sus ventanas de contexto reales, con permisos 600. Los nombres custom_joingonka y CUSTOM_JOINGONKA_API_KEY son los mismos que Goose deriva por su cuenta del nombre «JoinGonka», así que la clave del asistente irá a parar donde debe;
• hará de JoinGonka el proveedor predeterminado con el modelo DeepSeek V4 Flash, pero solo si aún no hay proveedor elegido o si el elegido es el nuestro con un modelo vacío o que ya no está en la red. No toca la elección ajena, sino que imprime el comando para probarlo: goose session --provider custom_joingonka --model …;
• guardará la clave en secrets.yaml, solo si el almacén de secretos de Goose es con certeza de tipo archivo; si no, te dirá directamente que queda un paso, con los detalles en la sección sobre la clave;
• hará copias de seguridad de los archivos modificados y al final enviará una petición real al gateway para comprobar de inmediato la clave, la dirección y el modelo.

El instalador localiza el directorio de configuración igual que el propio Goose: ~/.config/goose en Linux y macOS, %APPDATA%\Block\goose\config en Windows, <root>/config cuando se define GOOSE_PATH_ROOT. Otro modelo se especifica con el flag --model con la abreviatura deepseek, glm o minimax; un modelo indicado explícitamente siempre se escribe. El modo sin preguntas toma la clave de una variable de entorno:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool goose --model glm --non-interactive

Todo lo que hace el instalador se puede escribir manualmente. El proveedor es un archivo JSON independiente ~/.config/goose/custom_providers/custom_joingonka.json; el nombre del archivo coincide con el campo name:

{
  "name": "custom_joingonka",
  "engine": "openai",
  "display_name": "JoinGonka",
  "description": "JoinGonka Gateway — Gonka AI inference (OpenAI-compatible)",
  "api_key_env": "CUSTOM_JOINGONKA_API_KEY",
  "base_url": "https://gate.joingonka.ai/v1/chat/completions",
  "models": [
    { "name": "deepseek-ai/DeepSeek-V4-Flash-0731", "context_limit": 380000 },
    { "name": "zai-org/GLM-5.3-Flash", "context_limit": 390000 },
    { "name": "MiniMaxAI/MiniMax-M2.7", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

No existe un límite de respuesta independiente para la entrada de un modelo de Goose. Para tales modelos, no transmite el límite en la solicitud —lo verificamos a través de su registro de solicitudes— y en modo de streaming, el gateway limita la respuesta según el límite del modelo: 32 768 tokens para DeepSeek V4 Flash, 8192 para GLM-5.3 Flash y MiniMax M2.7. No es necesario establecer la variable global GOOSE_MAX_TOKENS para esto: es única para todos los proveedores a la vez.

Goose lee el archivo del proveedor mediante un análisis JSON estricto: un comentario o una coma colgante y el proveedor desaparece de la lista. También se puede crear mediante el asistente (goose configure → Custom Providers), pero el asistente no pregunta por la ventana de contexto, por lo que deberá añadirse manualmente.

El proveedor y el modelo predeterminados viven en ~/.config/goose/config.yaml. Así es como el propio Goose los escribe:

active_provider: custom_joingonka
providers:
  custom_joingonka:
    enabled: true
    model: deepseek-ai/DeepSeek-V4-Flash-0731
    configured: true

El diseño antiguo —claves planas GOOSE_PROVIDER y GOOSE_MODEL en la raíz del archivo— también funciona: Goose lo lee y lo traduce al nuevo formato la primera vez que guarda la configuración, como hicimos después de goose configure. El instalador escribe exactamente las claves planas en un archivo vacío; cualquier versión las entiende. Las variables de entorno con el mismo nombre tienen prioridad sobre el archivo: si están definidas en la shell, la selección de config.yaml no tendrá efecto, y el instalador emitirá una advertencia al respecto.

En el archivo del proveedor de Goose solo existe el nombre del secreto: CUSTOM_JOINGONKA_API_KEY. Su valor lo busca en orden: en la variable de entorno con ese nombre, luego en el almacén de secretos del sistema (keyring; en macOS, Keychain) y después en el archivo secrets.yaml junto a la configuración. Los secretos llegan a ese archivo cuando el almacén de Goose es de tipo archivo, y allí quedan en texto plano, con permisos 600. En config.yaml, en cambio, Goose no busca claves en absoluto (documentación).

El almacén pasa a ser de archivo si el keyring está desactivado —con la variable GOOSE_DISABLE_KEYRING con cualquier valor o la línea GOOSE_DISABLE_KEYRING: true en config.yaml— o si no está disponible: un servidor sin sesión gráfica, un contenedor, CI. En el segundo caso Goose escribe en el registro «Keyring unavailable. Using file storage for secrets.» y pasa por sí solo al archivo: exactamente lo que vimos en el contenedor. El instalador no sabe escribir en el keyring, y tampoco lo va a desactivar por ti: Goose dejaría de ver los secretos que ya están allí. De ahí estos escenarios:

El paso que queda. Ejecuta goose configure y responde a las preguntas del asistente, que en nuestra ejecución fueron así:

• What would you like to configure? → Configure Providers;
• Which model provider should we use? → JoinGonka (en nuestro caso aparecía primero);
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes, y luego en Enter value for CUSTOM_JOINGONKA_API_KEY pega la clave: en lugar de los caracteres aparecerán cuadraditos. La clave se guarda de inmediato;
• Would you like to configure advanced settings? → No;
• Select a model: Goose obtiene la lista de la puerta de enlace: MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash. El cursor está en la primera línea; para conservar el modelo elegido por el instalador, selecciona con las flechas DeepSeek V4 Flash. Tras una petición de comprobación, el asistente terminará con la línea «Configuration saved successfully».

En Goose Desktop la ruta es: Settings → Models → Configure providers → JoinGonka → clave → Submit. Si no quieres pegar la clave a mano, ponla en una variable y lanza el asistente desde la misma shell: Goose mostrará «CUSTOM_JOINGONKA_API_KEY is set via environment variable» y propondrá guardar el valor:

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

Y para una sola ejecución puedes pasar la clave sin guardarla siquiera: CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session; en PowerShell, $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. La variable de entorno tiene prioridad sobre el valor guardado, pero solo vive hasta que se cierra la shell.

Primero, mira qué configuración ve Goose realmente:

goose info -v

En el bloque «goose Configuration» deben aparecer las líneas GOOSE_PROVIDER: custom_joingonka y GOOSE_MODEL con el identificador del modelo. Después, una ejecución puntual sin sesión interactiva: coloca en un directorio vacío un archivo con un error evidente y pídele que lo encuentre.

goose run --no-session -t "Read calc.py and tell me in one sentence whether it has a bug."

El flag --no-session no guarda la ejecución en el historial. En la cabecera aparecerá una línea como ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731, luego la llamada a la herramienta — ▸ shell con el comando cat calc.py — y la respuesta con el error encontrado. Otra modelo para una sola ejecución se define con --model: zai-org/GLM-5.3-Flash o MiniMaxAI/MiniMax-M2.7. En nuestra prueba del 23 de septiembre de 2026, los tres modelos de la red completaron el ciclo «petición → herramienta → resultado → respuesta». Por defecto, el CLI de Goose oculta el razonamiento de los modelos; puedes mostrarlo con la variable GOOSE_CLI_SHOW_THINKING=1 si la salida va a la terminal. Desde el lado de la pasarela, la petición es visible en el panel: sección «Uso», desglose «Por modelos» y «Por claves».

Si algo sale mal, el diagnóstico normalmente se lee directamente en el mensaje:

Un agente consume tokens de manera diferente a un chat. Ya en la configuración estándar, Goose envía al modelo las descripciones de dieciocho herramientas integradas, y en nuestra ejecución, cada paso conllevaba alrededor de 4.6 mil tokens de entrada antes incluso de su pregunta. La tarea de «leer un archivo y encontrar un error» tomó de dos a tres pasos y entre 10 y 15 mil tokens, casi todo de entrada; Goose realiza una solicitud corta adicional por sí mismo para inventar un nombre para la sesión. Las extensiones innecesarias se desactivan en goose configure → Toggle Extensions: es la forma más sencilla de reducir la entrada.

A través de JoinGonka Gateway, los tokens cuestan $0.0069 por millón en la entrada y $0.021 por millón en la salida; el precio es igual para todos los modelos de la red y se muestra en esta página desde una fuente en tiempo real.

Las estimaciones en la columna derecha se basan en los precios de septiembre de 2026. Como comparación, así es como se puede pagar por los modelos en Goose:

El consumo exacto y el saldo restante se encuentran en el panel, en las secciones «Uso» y «Facturación». Por qué DeepSeek V4 Flash es la opción predeterminada —con el mayor límite de respuesta en la red— se explica detalladamente en el análisis del modelo.

Modo de confirmaciones. Por defecto, Goose funciona en modo auto — totalmente autónomo: edita y borra archivos por su cuenta, ejecuta comandos y usa extensiones sin preguntar nada. En tu propio proyecto es cómodo, pero con código ajeno es mejor endurecer el modo:

# inside a session
/mode smart_approve

# permanently, as a line in config.yaml
GOOSE_MODE: smart_approve

Esto es propio de Goose, no depende del proveedor de la modelo.

Cambio de modelo. Dentro de la sesión, el comando /model con el identificador, por ejemplo /model zai-org/GLM-5.3-Flash; para una sola ejecución, el flag --model de goose run y goose session; de forma permanente, goose configure o la línea model en config.yaml. El proveedor sigue siendo el mismo. La GLM-5.3 Flash, que razona, es buena para lógica enrevesada, pero su tope de respuesta es de 8192 tokens, y parte de ellos se van en el razonamiento — detalles en el análisis de la modelo.

Ejecuciones sin supervisión. goose run es ideal para scripts y CI: el flag -q deja en la salida solo la respuesta de la modelo, --output-format json entrega el resultado para parsearlo. Los limitadores --max-turns (cuántos turnos hace el agente sin intervención humana) y --max-tool-repetitions (cuántas veces seguidas se puede llamar a una misma herramienta con los mismos argumentos) protegen contra bucles.

Privacidad. Las estadísticas anónimas de uso en Goose están desactivadas por defecto (GOOSE_TELEMETRY_ENABLED). La pasarela no almacena el contenido de los prompts ni de las respuestas — en las estadísticas solo quedan agregados de consumo.