Goose + JoinGonka Gateway: свій провайдер і ключ у keyring

Крок 1: встановити Goose. Офіційні способи для CLI з документації проєкту:

# 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

Змінна CONFIGURE=false вимикає майстер goose configure, який скрипт інакше запускає одразу після встановлення: провайдера налаштує інсталятор. Якщо каталогу ~/.local/bin немає в PATH, скрипт так і скаже. Для Windows у тому ж репозиторії є скрипт download_cli.ps1, а настільний застосунок завантажується зі сторінки документації; він і CLI читають ті самі налаштування, тож усе нижче діє для обох. Перевірка — goose --version.

Крок 2: отримати ключ. Зареєструйтеся на gate.joingonka.ai/register, підтвердьте адресу та створіть ключ із префіксом jg- у розділі «API-ключі». Один ключ і один баланс діють для всіх моделей мережі.

Крок 3: запустити інсталятор.

npx @joingonka/setup --tool goose

Інсталятор запитає ключ — в аргументах командного рядка він не передається, щоб не осісти в історії оболонки, — і зробить таке:

• створить файл провайдера custom_providers/custom_joingonka.json з адресою шлюзу й трьома моделями мережі зі справжніми вікнами контексту, з правами 600. Імена custom_joingonka і CUSTOM_JOINGONKA_API_KEY — ті самі, що Goose сам виводить із назви «JoinGonka», тож ключ із майстра ляже куди треба;
• зробить JoinGonka провайдером за замовчуванням із моделлю DeepSeek V4 Flash — але тільки якщо провайдера ще не вибрано або вибрано наш із порожньою чи такою, що пішла з мережі, моделлю. Чужий вибір він не чіпає, а друкує команду, щоб спробувати: goose session --provider custom_joingonka --model …;
• покладе ключ у secrets.yaml, лише якщо сховище секретів у Goose напевно файлове; інакше прямо скаже, що залишився один крок, — подробиці в розділі про ключ;
• зробить резервні копії змінених файлів і наприкінці надішле живий запит на шлюз, щоб одразу перевірити ключ, адресу й модель.

Каталог налаштувань інсталятор знаходить так само, як сам Goose: ~/.config/goose на Linux і macOS, %APPDATA%\Block\goose\config на Windows, <root>/config за заданого GOOSE_PATH_ROOT. Іншу модель задає флаг --model зі скороченням deepseek, glm або minimax; явно вказана модель записується завжди. Режим без запитань бере ключ зі змінної оточення:

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

Усе, що робить інсталятор, можна написати власноруч. Провайдер — окремий JSON-файл ~/.config/goose/custom_providers/custom_joingonka.json; ім'я файлу збігається з полем 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
}

Окремої стелі відповіді для запису моделі Goose не передбачено. Для таких моделей він взагалі не передає обмеження в запиті — ми перевірили це за його журналом запитів, — і в потоковому режимі шлюз сам обмежує відповідь стелею моделі: 32 768 токенів у DeepSeek V4 Flash, 8192 у GLM-5.3 Flash та MiniMax M2.7. Глобальну змінну GOOSE_MAX_TOKENS для цього задавати не потрібно: вона одна на всі провайдери відразу.

Файл провайдера Goose читає суворим JSON-розбором: коментар або висяча кома — і провайдер зникає зі списку. Створити його можна і майстром (goose configure → Custom Providers), але вікно контексту майстер не запитує — його доведеться дописати власноруч.

Провайдер і модель за замовчуванням живуть у ~/.config/goose/config.yaml. Так їх записує сам Goose:

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

Стара розкладка — плоскі ключі GOOSE_PROVIDER та GOOSE_MODEL у корені файлу — теж працює: Goose читає її і сам переводить у нову при першому збереженні налаштувань, як у нас після goose configure. Інсталятор на порожньому файлі пише саме плоскі ключі — їх розуміє будь-яка версія. Однойменні змінні оточення важливіші за файл: якщо вони задані в оболонці, вибір з config.yaml не подіє, і інсталятор про це попередить.

У файлі провайдера у Goose є лише ім'я секрету — CUSTOM_JOINGONKA_API_KEY. Значення він шукає по черзі: у змінній середовища з цим ім'ям, потім у системному сховищі секретів (keyring, у macOS — Keychain), далі у файлі secrets.yaml поруч із конфігом. У файл секрети потрапляють, коли сховище у Goose файлове, і лежать там відкритим текстом, із правами 600. А в config.yaml Goose ключі не шукає взагалі (документація).

Файловим сховище стає, якщо keyring вимкнено — змінною GOOSE_DISABLE_KEYRING з будь-яким значенням або рядком GOOSE_DISABLE_KEYRING: true у config.yaml, — або він недоступний: сервер без графічної сесії, контейнер, CI. У другому випадку Goose пише в журнал «Keyring unavailable. Using file storage for secrets.» і сам переходить на файл — саме це ми бачили в контейнері. Писати в keyring інсталятор не вміє, а вимикати його за вас не стане: Goose перестав би бачити секрети, які там уже лежать. Звідси сценарії:

Крок, що залишився. Запустіть goose configure і дайте відповіді на питання майстра — так вони виглядали в нашому прогоні:

• What would you like to configure? → Configure Providers;
• Which model provider should we use? → JoinGonka (у нас він стояв першим);
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes, потім на Enter value for CUSTOM_JOINGONKA_API_KEY вставте ключ — замість символів з'являться квадратики. Ключ зберігається одразу;
• Would you like to configure advanced settings? → No;
• Select a model — список Goose отримує у шлюзу: MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash. Курсор стоїть на першому рядку — щоб залишити модель, вибрану інсталятором, виберіть стрілками DeepSeek V4 Flash. Після перевірочного запиту майстер завершиться рядком «Configuration saved successfully».

У Goose Desktop шлях такий: Settings → Models → Configure providers → JoinGonka → ключ → Submit. Не хочеться вставляти ключ руками — покладіть його у змінну й запустіть майстер із тієї ж оболонки: Goose напише «CUSTOM_JOINGONKA_API_KEY is set via environment variable» і запропонує зберегти значення:

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

А на один запуск ключ можна передати взагалі без збереження: CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session, у PowerShell — $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. Змінна середовища важливіша за збережене значення, але живе лише до закриття оболонки.

Спершу подивіться, які налаштування Goose бачить насправді:

goose info -v

У блоці «goose Configuration» мають бути рядки GOOSE_PROVIDER: custom_joingonka і GOOSE_MODEL з ідентифікатором моделі. Далі — разовий прогін без інтерактивної сесії: покладіть у порожній каталог файл з очевидною помилкою і попросіть її знайти.

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

Прапорець --no-session не зберігає прогін в історію. У шапці з'явиться рядок вигляду ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731, потім виклик інструмента — ▸ shell з командою cat calc.py — і відповідь зі знайденою помилкою. Іншу модель на один запуск задає --model: zai-org/GLM-5.3-Flash або MiniMaxAI/MiniMax-M2.7. У нашому прогоні 23 вересня 2026 цикл «запит → інструмент → результат → відповідь» пройшли всі три моделі мережі. Міркування моделей CLI Goose за замовчуванням приховує — показати їх можна змінною GOOSE_CLI_SHOW_THINKING=1, якщо вивід іде в термінал. З боку шлюзу запит видно в кабінеті: розділ «Використання», розбивка «За моделями» і «За ключами».

Якщо щось пішло не так, діагноз зазвичай читається прямо з повідомлення:

Агент витрачає токени інакше, ніж чат. Вже у стандартній конфігурації Goose надсилає моделі описи вісімнадцяти вбудованих інструментів, і в нашому прогоні кожен хід ніс близько 4,6 тисячі вхідних токенів ще до вашого запитання. Завдання «прочитати файл і знайти помилку» зайняло два-три ходи і 10-15 тисяч токенів, майже все — вхід; ще один короткий запит Goose робить сам, щоб придумати назву сесії. Непотрібні розширення вимикаються в goose configure → Toggle Extensions — це найпростіший спосіб скоротити вхід.

Через JoinGonka Gateway токени коштують $0.0069 за мільйон на вході та $0.021 за мільйон на виході — ціна однакова для всіх моделей мережі та підставляється на цій сторінці з живого джерела.

Оцінки у правій колонці — за цінами на вересень 2026. Для порівняння — як взагалі можна платити за моделі в Goose:

Точні витрати та залишок — у кабінеті, у розділах «Використання» та «Білінг». Чому за замовчуванням стоїть DeepSeek V4 Flash — із найбільшою стелею відповіді в мережі — детально розібрано в огляді моделі.

Режим підтверджень. За замовчуванням Goose працює в режимі auto — повністю автономно: сам редагує і видаляє файли, запускає команди і користується розширеннями, нічого не питаючи. На власному проєкті це зручно, на чужому коді режим краще посилити:

# inside a session
/mode smart_approve

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

Це властивість самого Goose, від провайдера моделі вона не залежить.

Зміна моделі. Усередині сесії — команда /model з ідентифікатором, наприклад /model zai-org/GLM-5.3-Flash; на один запуск — прапорець --model у goose run і goose session; назавжди — goose configure або рядок model у config.yaml. Провайдер при цьому залишається тим самим. Роздумуюча GLM-5.3 Flash добра для заплутаної логіки, але стеля її відповіді — 8192 токени, і частина його йде на роздуми — подробиці в огляді моделі.

Прогони без нагляду. goose run підходить для скриптів і CI: прапорець -q залишає у виводі лише відповідь моделі, --output-format json віддає результат для розбору. Обмежувачі --max-turns (скільки ходів агент робить без участі людини) і --max-tool-repetitions (скільки разів підряд можна викликати один інструмент з тими самими аргументами) страхують від зациклення.

Приватність. Анонімна статистика використання в Goose за замовчуванням вимкнена (GOOSE_TELEMETRY_ENABLED). Шлюз не зберігає вміст промптів і відповідей — у статистиці залишаються лише агрегати витрат.