Tutorial del agente de código goose: instalación, fuentes de modelos, configuración de API y costes

goose es un agente de código de IA de código abierto (Apache-2.0) que puede leer y modificar archivos y ejecutar comandos desde el terminal o la aplicación de escritorio. Empezar solo requiere tres pasos: instalarlo, elegir una fuente de modelos (provider) y abrir una sesión de trabajo para asignarle una tarea. Es gratuito; el coste procede del modelo que conectes. Este tutorial sigue la documentación oficial del 1 de octubre de 2026 y explica la instalación, las tres vías de pago, cómo conectarlo a un endpoint compatible con OpenAI (incluida la trampa /v1 más habitual) y las operaciones comunes. La versión más reciente es v1.52.0, publicada el 23 de septiembre de 2026.

Primero, aclaremos el nombre. Esta página trata sobre el agente de programación de goose-docs.ai, cuyo repositorio está en aaif-goose/goose. Antes se llamaba block/goose y en el mes 4 de 2026 pasó a estar bajo la Agentic AI Foundation de la Linux Foundation. No es goose.ai: ese es otro servicio de inferencia alojado, cuyos precios tampoco tienen relación con lo que se explica aquí. Actualmente, goose no tiene una interfaz en chino tradicional, por lo que los nombres de los menús que aparecen a continuación se mantienen en su inglés original.

Instalación

Oficialmente se ofrecen una versión de escritorio (goose Desktop) y una versión de línea de comandos (goose CLI); ambas leen la misma configuración.

# goose Desktop(macOS)
brew install --cask block-goose

# goose CLI（macOS / Linux / Windows 的 Git Bash）
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

# 只安裝、先不進入設定
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# 或用 Homebrew 裝 CLI
brew install block-goose-cli

En Windows puedes descargar la versión de escritorio desde el sitio oficial; para la CLI se recomienda ejecutar la misma orden de instalación en Git Bash (PowerShell también sirve). El nombre del paquete de Homebrew sigue siendo block-goose; esto se debe a que el cambio de nombre no se ha propagado completamente al paquete de instalación y no significa que el proyecto siga en manos de Block.

Primer inicio: elegir la fuente del modelo

La primera vez que abras goose Desktop aparecerá una pantalla de bienvenida; la CLI entrará automáticamente en el modo de configuración (para modificarlo después puedes ejecutar goose configure). La página de instalación enumera tres opciones:

• OpenRouter Login: inicia sesión con tu cuenta de OpenRouter y configura el modelo automáticamente.
• Tetrate Agent Router Service Login: inicia sesión en Tetrate; la documentación indica que la primera autenticación automática a través de goose proporciona $10 de crédito gratuito, tanto a usuarios nuevos como existentes.
• Manual Configuration: elige el proveedor y proporciona la clave manualmente. Para conectarte a un endpoint compatible con OpenAI (como Kunavo), elige esta opción.

Tres vías de pago: elige la correcta antes de configurar

La explicación de la vía ACP procede de la documentación de proveedores ACP de goose, que también advierte que el ID de sesión de ACP y el de goose son diferentes y que los campos de telemetría pueden no coincidir. Si ya tienes una suscripción y solo quieres ahorrar costes de API, empieza por esta vía.

Conectarse a un endpoint compatible con OpenAI: no añadir /v1 a la URL de host

Este es el punto en el que más gente se atasca. goose no acepta una única base URL completa, sino que la divide en «host» y «ruta». Según la documentación de proveedores, OPENAI_HOST es la «URL de endpoint personalizada (por defecto, api.openai.com)» y OPENAI_BASE_PATH es la «ruta de solicitud que se añade después del host (por defecto, v1/chat/completions)»; al conectarte a un proxy, debes establecer OPENAI_HOST como «la dirección raíz del proxy (sin ruta)». Con Kunavo, por ejemplo:

# goose Desktop → Settings → Models → Configure providers → OpenAI
API Key           sk-kn-...
Host URL          https://api.kunavo.com      ← 只寫網域，不加 /v1
Organization ID   （留空）
Project           （留空）

# 或用環境變數（CLI 也讀）
export OPENAI_API_KEY=sk-kn-...
export OPENAI_HOST=https://api.kunavo.com
# OPENAI_BASE_PATH 不要設：預設就是 v1/chat/completions

En goose Desktop está en Settings → Models → Configure providers → OpenAI; en la CLI, goose configure → Configure Providers → OpenAI. Organization ID y Project son para cuentas propias de OpenAI, así que puedes dejarlos vacíos. Si la URL de host se escribe como https://api.kunavo.com/v1, la solicitud se convierte en /v1/v1/chat/completions; la propia documentación dice que «404 suele significar que OPENAI_BASE_PATH no es correcto para tu proxy»: el problema es la ruta, no la clave. En cambio, si aparece 401 «No api key passed in», la clave no se ha leído, por ejemplo porque se escribió en config.yaml (goose lo ignora).

Otra vía más limpia es convertirlo en un proveedor independiente dentro de la lista. goose lee archivos de definición JSON de la carpeta custom_providers; Kunavo proporciona un archivo generado a partir de la tabla de precios en tiempo real, que solo incluye modelos compatibles con llamadas a herramientas y solo especifica el nombre de la variable de la clave, sin incluir la clave:

# macOS / Linux:goose 會讀這個資料夾裡所有 JSON
mkdir -p ~/.config/goose/custom_providers
curl -fsSL https://kunavo.com/goose/kunavo.json \
  -o ~/.config/goose/custom_providers/kunavo.json

# 檔案裡只有變數名稱，金鑰另外設定
export KUNAVO_API_KEY=sk-kn-...
goose session start --provider kunavo

La carpeta de Windows es %APPDATA%\Block\goose\config\custom_providers\. Después de colocar el archivo, Configure providers de goose Desktop mostrará Kunavo; la clave puede guardarse en el llavero del sistema en lugar de en una variable de entorno. Según el código fuente de goose, los ID que empiezan por gpt-5 o gpt-6 utilizan /v1/responses, y los demás utilizan /v1/chat/completions; Kunavo ofrece ambos. También puedes crearlo manualmente: Configure providers → Add Custom Provider, selecciona el tipo OpenAI Compatible y establece la URL de API en https://api.kunavo.com/v1. La página de configuración completa en inglés está en goose integration guide.

Explicación honesta: la configuración anterior se ha recopilado a partir de la documentación y el código fuente de goose; Kunavo no ha ejecutado goose realmente contra su propio endpoint: no se han probado sesiones, streaming ni intercambios de herramientas. Conserva la vía que ya te funciona y empieza probándolo con una tarea pequeña que lea y escriba archivos.

Operaciones comunes

• Abrir una sesión: goose session (puedes asignarle el nombre -n 名稱); después, reanúdala con goose session --resume -n 名稱; goose session list muestra el historial.
• Cambiar el modo de autorización: escribe /mode dentro de la sesión y podrás elegir auto, approve, chat o smart_approve. Si quieres que te pregunte antes de cada paso, usa approve.
• Elegir un modelo: goose configure no permite introducir nombres de modelo personalizados; para los ID que no aparecen en la lista, escríbelos en goose Desktop o establece GOOSE_MODEL en config.yaml.
• Archivo de instrucciones del proyecto: goose lee .goosehints y AGENTS.md de forma predeterminada (controlado por CONTEXT_FILE_NAMES); escribe allí las reglas del proyecto para poder llevarlas también al cambiar a otro agente.
• No elijas modelos que no admitan llamadas a herramientas: la documentación dice que esos modelos «solo pueden completar chats» y que las extensiones también deben estar desactivadas.

Cuánto cuesta aproximadamente una sesión de trabajo

Lo siguiente esaritmética de tokens con fines ilustrativos, no el coste real de una tarea ni un límite de facturación. Supongamos que una sesión de trabajo de un agente envía en total 400,000 tokens de entrada sin caché y recibe 25,000 tokens de salida a lo largo de varias rondas (el agente vuelve a enviar el contexto en cada ronda, por lo que la entrada es especialmente grande). Los precios unitarios proceden de los precios actuales por millón de tokens de la tabla de precios de Kunavo.

Sobre la caché: la documentación de goose indica que, al usar Claude mediante los proveedores Anthropic, Amazon Bedrock, Databricks, OpenRouter y LiteLLM, añade automáticamente la marca cache_control de Anthropic. Claude utilizado mediante el proveedor OpenAI genérico no aparece en esa lista, por lo que goose no añade esas marcas; por eso la tabla anterior supone que no hay descuento por caché, una estimación conservadora. Los importes de la tabla de precios de Kunavo son mínimos de facturación, no máximos: cuando el upstream informa de un coste, la factura toma el mayor entre el «importe de la tabla de precios» y el «coste del upstream × el margen aplicable».

Pagar desde Taiwán

Kunavo es prepago, cobra por token y no tiene cuota mensual. La recarga mínima es de $10; el pago se realiza mediante Stripe. En Taiwán se aceptan tarjetas de crédito (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay y Link; JKO Pay y LINE Pay no están disponibles. Consulta la información de facturación; cuando estés listo, puedes crear una cuenta y generar una clave. Para comparar otros agentes, consulta en inglés goose alternatives y goose vs Claude Code.

Preguntas frecuentes

Comprobado el 1 de octubre de 2026: documentación de instalación, proveedores, proveedores ACP, comandos de CLI y variables de entorno de goose (rama main de aaif-goose/goose), además de la versión y el estado de archivado según la API de GitHub. Kunavo no ha ejecutado goose realmente contra su propio endpoint; los precios proceden de la tabla de precios en tiempo real y todos los importes de ejemplo son aritmética de tokens con fines ilustrativos.