OpenHands + JoinGonka Gateway: агент на своєму endpoint

У проєкту сьогодні кілька інтерфейсів, і від того, який з них запущений у вас, залежить, де шукати налаштування моделі. Самі значення всюди одні й ті самі — відрізняється лише шлях до них.

Для Agent Canvas потрібні Node.js та uv — на ньому працює локальний сервер агента (подробиці — в інструкції зі встановлення). Інструкція називає Node.js 22.12 або новіший, але сам пакет починаючи з версії 1.17 оголошує Node.js 24 і новіший — ставте 24, щоб не отримати попередження про несумісну версію. Є й варіант у контейнері: образ ghcr.io/openhands/agent-canvas віддає інтерфейс на http://localhost:8000/canvas і бачить лише ті каталоги, які ви змонтували.

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

Крок 1. Запустіть Agent Canvas та відкрийте Settings > LLM. Майстер першого запуску пропонує власного провайдера OpenHands — цей крок можна пропустити, до налаштувань легко повернутися пізніше.

Крок 2. Натисніть Add LLM Profile та перейдіть на вкладку Advanced: вкладка Basic пропонує лише провайдерів та моделі з вбудованого списку.

Крок 3. Заповніть три поля:

Крок 4. Збережіть профіль. Перед збереженням Canvas перевіряє конфігурацію запитом з бекенда: якщо ключ відхилено або модель недоступна, профіль не збережеться, а ви побачите текст помилки.

Крок 5. Розпочніть нову розмову та надішліть коротке повідомлення. Вже відкриті розмови продовжують працювати на тій моделі, з якої почалися.

Чому openai/. LiteLLM визначає провайдера за префіксом моделі. Префікс openai/ означає не «модель від OpenAI», а «говорити з сервером за протоколом OpenAI Chat Completions». Зрізається лише перший сегмент, тому до шлюзу доходить справжній ідентифікатор — deepseek-ai/DeepSeek-V4-Flash-0731. У документації OpenHands та ж схема показана на прикладі openai/qwen/qwen3.6-35b-a3b. Без префікса LiteLLM відмовиться працювати з повідомленням LLM Provider NOT provided.

Чому /v1 і нічого більше. LiteLLM ходить до сервера через офіційний клієнт OpenAI, а той сам дописує /chat/completions. Тому адреса повинна закінчуватися на /v1: без суфікса запит піде повз API, з зайвим хвостом — на шлях, якого не існує. І ще одна вимога Canvas: адреса має бути доступною з бекенда, а не лише з браузера. Шлюз — публічна HTTPS-адреса, з контейнера Docker її видно так само, як з хоста; прийоми на кшталт host.docker.internal потрібні лише для моделей на вашій машині.

Профілі під усі три моделі. Створіть по профілю на кожну модель мережі та назвіть їх коротко — наприклад deepseek, glm та minimax (документація говорить про ліміт у десять профілів). Перемикатися можна прямо в розмові, не втрачаючи контексту: кнопкою вибору профілю в полі введення або командою /model glm; /model без аргументу покаже список. Щоб не вставляти ключ у кожен профіль, його можна зберегти один раз у блоці Provider Connections — він доступний на локальному бекенді.

Колишній інтерфейс у Docker. Поля ті самі: Settings → вкладка LLM → увімкнути Advanced → Custom Model, Base URL, API Key → Save Changes.

CLI ставиться однією командою через uv і під час першого запуску сам проведе через налаштування моделі; пізніше до нього повертає Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Для скриптів зручніше змінні середовища. Важлива деталь: типово CLI їх ігнорує і застосовує лише з прапорцем --override-with-envs — на один запуск, нічого не зберігаючи:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

Той самий набір працює без інтерфейсу — для CI та пакетних задач:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

У headless-режимі агент завжди діє з авосхваленням, тому запускайте його там, де йому можна все: в окремому каталозі або контейнері. Прапорець --json перетворює вивід на потік подій JSONL — його зручно розбирати в конвеєрі. Саме так ми перевіряли зв'язку 21 вересня 2026 на CLI 1.16.0: у шапці CLI друкує Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, потім агент читає файл і відповідає по суті.

Збережені налаштування CLI лежать у ~/.openhands/agent_settings.json: модель у ньому змінюється правкою трьох полів блоку llm — model, api_key і base_url. Створювати файл з нуля не варто: майстер першого запуску пише туди й інші налаштування агента, зокрема стиснення історії, без якого довга розмова впреться в вікно контексту.

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

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

Ціна у моделей мережі одна, тому вибір — про поведінку. Автономному агенту важливі дві цифри. Вікно контексту: кожен крок заново відправляє історію, і чим вікно довше, тим довше агент працює без втрат. Стеля відповіді: крок, на якому агент пише великий файл цілком, повинен вміститися в одну відповідь. У таблиці — результати нашого прогону одного й того самого завдання (прочитати файл і знайти помилку) через OpenHands CLI 1.16.0 з SDK 1.21.0.

Робоча схема для довгого завдання повторює пораду з документації OpenHands — планувати однією моделлю, виконувати іншою. Почніть розмову на профілі glm і попросіть план без правок файлів; потім надішліть /model deepseek і дайте команду виконувати. Історія, файли та стан завдання при перемиканні зберігаються. Профіль minimax тримайте третім: на нього зручно перейти, коли у двох інших у годину пік закінчилася ємність, і йому ж у Settings > Application можна віддати генерацію заголовків розмов.

Стиснення історії. Навіть вікно в сотні тисяч токенів на багатогодинному завданні є кінцевим. В OpenHands за це відповідає конденсер: він згортає старі події в короткий резюме, що, за словами документації, знижує затримку та витрати токенів у довгих розмовах. В Agent Canvas він налаштовується в розділі Settings > Condenser; у нашому прогоні CLI увімкнув його сам, з порогом у 80 подій.

Ліміти моделі. Вікно контексту та стелю відповіді OpenHands бере з довідника LiteLLM, а ідентифікаторів мережі Gonka в ньому немає (ми перевірили на LiteLLM 1.81), тому своїх значень для цих моделей у агента немає. Роботі це не заважає: стелю відповіді шлюз застосовує сам, за таблицею вище. Якщо захочете задати ліміти явно — в SDK це поля max_input_tokens та max_output_tokens, а в Canvas повний набір полів профілю відкриває вкладка All. Подробиці про модель за замовчуванням — в огляді DeepSeek V4 Flash.

Переконатися, що запити дійсно йдуть через шлюз, можна з двох сторін. З боку OpenHands — нова розмова та коротке завдання на кшталт «прочитай README і перекажи одним реченням»: агент повинен викликати інструмент і відповісти. З боку шлюзу — кабінет, розділ «Використання»: запит з'явиться в розбивці «За моделями», а в блоці «За ключами» оновиться час останнього запиту. Пусто — значить, розмова йде на іншому профілі: перевірте, який з них позначений активним.

За документацією OpenHands кількість повторів і паузи між ними при 429 налаштовуються змінними LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT і LLM_RETRY_MAX_WAIT. Значення за замовчуванням у документації та в SDK розходяться, тому орієнтуйтеся на фактичні: у стані розмови CLI 1.16.0 ми бачили 5 спроб з паузами від 8 до 64 секунд.

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

Оцінки у правій колонці — за цінами на вересень 2026; як влаштована економіка агентів, докладно розібрано у статті про найдешевший API для AI-агентів.

Стеля витрат. OpenHands радить ставити ліміти витрат — у шлюзу він вбудований у саму модель оплати: баланс передплачений, і більше, ніж на рахунку, агент не витратить. Залишок і витрати по днях видно в кабінеті. Для CI та фонових автоматизацій заведіть окремий ключ, щоб їх витрати не змішувалися з вашими; дочірні ключі з денним лімітом описані у статті про Management Keys.

Межа довіри. Agent Canvas, запущений через npm, працює з правами вашого користувача і бачить усю файлову систему. Для чужого коду беріть варіант у Docker: агент побачить тільки змонтований каталог. Це властивість самого OpenHands, від провайдера моделі вона не залежить.

Листування залишається у вас. Історію розмови OpenHands зберігає у себе, в ~/.openhands, і надсилає її моделі з кожним кроком; шлюз листування не зберігає — ваші промпти та код не залишаються на ньому після відповіді.

Якщо у завданні є картинки — скриншоти інтерфейсу, схеми — заведіть для нього окремий профіль з vision-моделлю: моделі мережі Gonka текстові. Для коду, команд і файлів це не обмеження.