Встановлення goose і налаштування власного Provider

goose — універсальний AI-асистент, який працює на вашому комп’ютері. Крім програмування, він може виконувати пошук, писати тексти, автоматизувати завдання й упорядковувати дані. Ним можна користуватися через версію для робочого столу, термінал або інтерфейс API. Версії для робочого столу й термінала використовують спільну конфігурацію моделей. Він підходить для повторюваних завдань із програмування, а також може підключатися до GitHub, баз даних і файлів.

Підготовка до встановлення

goose пропонує два способи встановлення: Desktop і CLI. Desktop — версія для робочого столу з графічним вікном, а CLI — версія, якою керують командами в терміналі. Обидві версії використовують спільну основну конфігурацію, включно з Provider і моделями. Provider можна розуміти як параметри з’єднання, які вказують goose, яким сервісом моделей користуватися.

Потрібне вікно

goose Desktop

Для macOS завантажте zip
Або скористайтеся brew cask
Для Linux використовуйте інсталяційний пакет

Потрібен лише термінал

goose CLI

download_cli.sh
Або Homebrew CLI
Потім goose session

Windows

Спочатку виберіть середовище

Git Bash або MSYS2
Також можна використовувати PowerShell
Якщо команда не знайдена, додайте її до PATH

У macOS можна скористатися завантаженням або Homebrew. Для версії Desktop у Linux використовуйте пакет свого дистрибутива. У Windows спочатку перевірте офіційно зазначені середовища термінала.

Перед початком підготуйте ID моделі з поточного списку моделей. ID моделі — це назва, за якою сервіс моделей розпізнає конкретну модель. Під час використання її потрібно копіювати повністю.

Встановлення та перший запуск

Якщо потрібне вікно програми

Для macOS запропоновано два способи встановлення:

Завантажити програму зі сторінки встановлення. Там доступні версії macOS Silicon і macOS Intel. Після завантаження розпакуйте zip-файл і запустіть програму з нього.
Або скористатися Homebrew:

brew install --cask block-goose

Ця команда завантажує ту саму програму й також може допомагати з оновленнями.

Якщо на Apple Mac M3 після відкриття не з’являється вікно, перевірте, чи доступний каталог ~/.config для читання та запису. goose використовує цей каталог для запису журналів.

Версію Desktop для Linux завантажте зі сторінки встановлення. Доступні формати DEB для Ubuntu/Debian, RPM для RHEL/Fedora та Flatpak. Для Debian або Ubuntu виконайте такі дії: завантажте DEB, перейдіть до каталогу, у якому він збережений, виконайте sudo dpkg -i (filename).deb, а потім відкрийте goose з меню програм. Замініть (filename) фактичною назвою файлу.

Версію Desktop для Windows завантажте зі сторінки встановлення, розпакуйте zip-файл і запустіть програму з нього.

Якщо потрібен лише термінал

У macOS і Linux виконайте:

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

Щоб не проходити інтерактивне налаштування під час встановлення, додайте на початку CONFIGURE=false:

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

У macOS також можна виконати:

brew install block-goose-cli

Щоб оновити вже встановлений CLI, виконайте:

goose update

У Windows потрібне одне з трьох середовищ: Git Bash, що постачається разом із Git for Windows і позначене як рекомендоване, MSYS2 або вбудований у Windows 10/11 PowerShell. У Git Bash і MSYS2 використовуйте ту саму команду download_cli.sh, що наведена вище. У PowerShell спочатку завантажте сценарій, а потім запустіть його:

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

Якщо з’явиться повідомлення, що goose відсутній у PATH, дотримуйтеся вказівок на сторінці встановлення: додайте ~/.local/bin або %USERPROFILE%\.local\bin до конфігурації поточної оболонки, а потім знову відкрийте термінал. PATH — це набір каталогів, у яких термінал шукає програми. Якщо каталог не додано, програму може бути встановлено, але її не вдасться запустити простим введенням назви.

Станом на 2026-10-09 версія CLI — 1.54.0. За замовчуванням сценарій встановлення розміщує програму в ~/.local/bin. Змінити цей каталог можна за допомогою змінної середовища GOOSE_BIN_DIR. Після зміни сценарій не додасть каталог до конфігурації оболонки автоматично, тому термінал повідомить, що каталог відсутній у PATH. Додайте його до PATH або запускайте програму за повним шляхом.

Під час першого використання goose запропонує налаштувати Provider. Можна пропустити вбудованих постачальників і додати власний Provider за інструкціями з наступного розділу. У терміналі перейдіть до каталогу, у якому хочете працювати, і виконайте:

goose session

Отримання параметрів з’єднання з OmniProxy

Підготуйте адресу, ключ і назву моделі зі свого OmniProxy. В офіційному прикладі власного Provider значення base_url закінчується на /v1/chat/completions, тому тут використовується такий самий формат:

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   скопіюйте з поточного списку моделей OmniProxy; кілька значень розділяйте комами

Повністю скопіюйте назву моделі з поточного списку OmniProxy, зберігаючи також усі похилі риски. Станом на 2026-10-09 у документації постачальників як приклади наведено два ID: grok-4.7 для Grok і gpt-6-luna у документації OpenAI. gpt-6-luna підтримує Chat Completions; виклики функцій у Chat Completions підтримуються лише тоді, коли reasoning_effort має значення none. Не копіюйте назви, яких немає у вашому списку.

Введення конфігурації інструмента

Власний Provider використовує формат, сумісний з OpenAI, Anthropic або Ollama. Сумісний формат означає, що інструмент надсилає запити через відповідний загальний інтерфейс. Для підключення OmniProxy виберіть OpenAI Compatible.

Версія Desktop

Натисніть кнопку у верхньому лівому куті, щоб відкрити бічну панель.
Натисніть Settings.
Натисніть Models.
Натисніть Configure providers.
У нижній частині вікна натисніть Add Custom Provider.
У полі Provider Type виберіть OpenAI Compatible. У Display Name можна вказати OmniProxy. У API URL введіть адресу з попереднього розділу. Якщо потрібен ключ, позначте вимогу API Key і введіть ключ OmniProxy. У Available Models введіть назви моделей, розділяючи кілька значень комами.
Натисніть Create Provider.

Наразі у версії Desktop не можна визначати власні заголовки запитів у цьому вікні. Якщо заголовки потрібні, після створення відредагуйте конфігураційний файл.

Термінал

Виконайте:

goose configure

Виберіть Custom Providers, а потім Add A Custom Provider. Для API Type виберіть OpenAI Compatible, після чого за підказками введіть назву, API URL, зазначте потребу в ключі, введіть назви моделей і вкажіть, чи підтримуються потокові відповіді.

Якщо під час ручного налаштування у Windows виникає помилка сховища ключів, на запит про збереження в keyring виберіть варіант не зберігати ключ і натомість скористайтеся змінною середовища. Потім знову виконайте goose configure. Сховище ключів — це невелике захищене системне сховище для секретних ключів.

Конфігураційний файл

Використовуються такі каталоги:

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

Файл можна створити за наведеним прикладом. Замініть назву, адресу й моделі власними значеннями. Ключ зберігайте у змінній середовища, зазначеній у api_key_env, і не записуйте справжній ключ безпосередньо у файл:

{
  "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
}

Для context_limit залиште числове значення, як у прикладі. Фактичний контекст залежить від моделі та OmniProxy, тому не вважайте наведене число офіційним обмеженням цієї моделі. Перед використанням виконайте:

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

Після переходу до робочого каталогу виконайте:

goose session --provider omniproxy --model grok-4.7

Замініть значення --model повним ID зі списку. Команда goose session не має підкоманди start. Параметри --provider і --model також можна задати змінними середовища GOOSE_PROVIDER та GOOSE_MODEL. Навіть якщо шлюз не перевіряє ключ, OMNIPROXY_API_KEY усе одно має містити значення — ним може бути довільний рядок-заповнювач, який використовується лише локально. Станом на 2026-10-09 за такого налаштування файл було прочитано.

Вікно

Settings

Settings на бічній панелі
Сторінка Models
Add Custom Provider

Термінал

goose configure

Виберіть Custom Providers
Потім виберіть додавання
Як тип виберіть OpenAI Compatible

Файл

custom_providers

У macOS і Linux — у ~/.config
У Windows — в APPDATA
Задайте base_url за офіційним прикладом

Усі три способи створюють конфігурацію одного типу. Для типу Provider виберіть OpenAI Compatible.

Перевірка на реальному завданні

Перейдіть до каталогу зі звичайним файлом і запустіть goose session, як описано в попередньому розділі. Попросіть асистента прочитати перший рядок указаного вами файлу. Він має вивести вміст файлу, а не лише повідомити, що конфігурацію збережено.

Щоб читати файли або виконувати команди, у сеансі потрібне розширення Developer. Його можна розуміти як модуль інструментів, що дає goose змогу працювати з локальними файлами й командами. Зазвичай воно входить до стандартної конфігурації. Якщо goose відповідає, що не має інструмента для роботи з файлами, додайте до команди:

--with-builtin developer

Не додавайте водночас --no-profile, оскільки цей параметр вимикає стандартні розширення.

Станом на 2026-10-09 goose 1.54.0 успішно прочитав перший рядок указаного файлу. Перша відповідь може тривати приблизно хвилину.

Після цього перевірте джерело й назву моделі в журналі викликів OmniProxy.

Запуск

Сеанс відкривається

goose session
Provider — щойно доданий
Назва моделі є у списку

Завдання

Він справді виконав дію

Наприклад, вивів вміст поточного каталогу
Перегляньте його відповідь
Не обмежуйтеся повідомленням про успішне збереження

Журнал

Шлюз бачить запит

Адреса має відповідати прикладу в документації
Не записуйте ключ у репозиторій
ID моделі збігається зі списком

Після збереження Provider перевірте конфігурацію за допомогою реального сеансу.

Поширені помилки

Команду goose не знайдено: дотримуйтеся вказівок на сторінці встановлення, додайте каталог встановлення до PATH, а потім знову відкрийте термінал.
У версії Desktop на M3 немає вікна: перевірте дозволи на читання й запис для ~/.config.
Помилка сховища ключів: не зберігайте ключ у keyring, а скористайтеся змінною середовища.
Моделі немає у списку: у версії Desktop можна вибрати Use custom model і ввести назву моделі вручну. У goose configure не можна вводити власну назву моделі; для термінала скористайтеся версією Desktop або безпосередньо змініть GOOSE_MODEL у конфігурації.
Не вдається підключитися до адреси: переконайтеся, що API URL, як у прикладі, закінчується на /v1/chat/completions, а OmniProxy запущено.
Асистент повідомляє, що не може прочитати файл: додайте розширення Developer і не використовуйте --no-profile.
Повертається unsupported Responses role: system: адреса зазвичай правильна. Виберіть інший повний ID зі списку моделей.

Офіційні матеріали

Інструкції зі встановлення наведено в Install goose. Налаштування власного Provider описано в goose providers. Використані в прикладах ID моделей наведено на сторінці моделей xAI і сторінці GPT-6 Luna.

Замістіть усі заповнювачі значеннями з вашої власної конфігурації OmniProxy. Ніколи не публікуйте справжній ключ.

Збережений результат або HTTP 200 самі по собі не доводять повну сумісність Агента. Перевірте джерело та модель у журналі викликів OmniProxy.

Офіційні джерела · goose ↗