OpenHands + JoinGonka Gateway: agent na własnym endpoincie

Projekt ma obecnie kilka interfejsów, a od tego, który z nich jest uruchomiony, zależy, gdzie szukać ustawień modelu. Same wartości są wszędzie takie same — różni się tylko ścieżka dostępu do nich.

Dla Agent Canvas potrzebne są Node.js i uv — na nim działa lokalny serwer agenta (szczegóły w instrukcji instalacji). Instrukcja wspomina o Node.js 22.12 lub nowszym, ale sam pakiet począwszy od wersji 1.17 wymaga Node.js 24 lub nowszego — zainstaluj 24, aby uniknąć ostrzeżenia o niekompatybilnej wersji. Jest też opcja w kontenerze: obraz ghcr.io/openhands/agent-canvas udostępnia interfejs pod http://localhost:8000/canvas i widzi tylko te katalogi, które zamontujesz.

Klucz JoinGonka. Zarejestruj się na gate.joingonka.ai/register, potwierdź adres i stwórz klucz z prefiksem jg- w sekcji „API-klucze”. Jeden klucz i jedno saldo działają dla wszystkich modeli w sieci. W liście narzędzi instalatora @joingonka/setup nie ma OpenHands, i nie jest to przeoczenie: jego ustawienia znajdują się w interfejsie oraz w bezpiecznym magazynie backendu, a nie w pliku tekstowym, który można łatwo edytować z zewnątrz.

Krok 1. Uruchom Agent Canvas i otwórz Settings > LLM. Kreator pierwszego uruchomienia proponuje własnego dostawcę OpenHands — ten krok można pominąć, do ustawień łatwo wrócić później.

Krok 2. Kliknij Add LLM Profile i przejdź do zakładki Advanced: zakładka Basic oferuje tylko dostawców i modele z wbudowanej listy.

Krok 3. Wypełnij trzy pola:

Krok 4. Zapisz profil. Przed zapisem Canvas sprawdza konfigurację zapytaniem z backendu: jeśli klucz zostanie odrzucony lub model będzie niedostępny, profil się nie zapisze, a zobaczysz komunikat o błędzie.

Krok 5. Rozpocznij nową konwersację i wyślij krótką wiadomość. Już otwarte rozmowy nadal działają na modelu, z którym zostały rozpoczęte.

Dlaczego openai/. LiteLLM określa dostawcę na podstawie prefiksu modelu. Prefiks openai/ oznacza nie „model od OpenAI”, a „komunikuj się z serwerem poprzez protokół OpenAI Chat Completions”. Odcinany jest tylko pierwszy segment, więc do bramki dociera właściwy identyfikator — deepseek-ai/DeepSeek-V4-Flash-0731. W dokumentacji OpenHands ten sam schemat pokazano na przykładzie openai/qwen/qwen3.6-35b-a3b. Bez prefiksu LiteLLM odmówi współpracy z komunikatem LLM Provider NOT provided.

Dlaczego /v1 i nic więcej. LiteLLM łączy się z serwerem przez oficjalnego klienta OpenAI, a ten sam dopisuje /chat/completions. Dlatego adres musi kończyć się na /v1: bez sufiksu zapytanie trafi obok API, z dodatkowym ogonem — na ścieżkę, która nie istnieje. I jeszcze jeden wymóg Canvas: adres musi być dostępny z backendu, a nie tylko z przeglądarki. Bramka to publiczny adres HTTPS, z kontenera Docker jest widoczny tak samo jak z hosta; techniki takie jak host.docker.internal są potrzebne tylko dla modeli na twojej maszynie.

Profile dla wszystkich trzech modeli. Załóż osobny profil dla każdego modelu sieci i nazwij je krótko — na przykład deepseek, glm i minimax (dokumentacja wspomina o limicie dziesięciu profili). Przełączać można się bezpośrednio w rozmowie, bez utraty kontekstu: przyciskiem wyboru profilu w polu wprowadzania lub komendą /model glm; /model bez argumentu wyświetli listę. Aby nie wklejać klucza w każdy profil, można go zapisać raz w bloku Provider Connections — jest on dostępny na lokalnym backendie.

Poprzedni interfejs w Docker. Pola są te same: Settings → zakładka LLM → włącz Advanced → Custom Model, Base URL, API Key → Save Changes.

CLI instaluje się jedną komendą przez uv, a przy pierwszym uruchomieniu sam przeprowadzi przez konfigurację modelu; później wraca się do niej przez Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

Do skryptów wygodniejsze są zmienne środowiskowe. Ważny szczegół: domyślnie CLI je ignoruje i stosuje tylko z flagą --override-with-envs — na jedno uruchomienie, niczego nie zapisując:

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

Ten sam zestaw działa bez interfejsu — dla CI i zadań wsadowych:

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

W trybie headless agent zawsze działa z automatycznym zatwierdzaniem, więc uruchamiaj go tam, gdzie może wszystko: w osobnym katalogu lub kontenerze. Flaga --json zamienia wyjście w strumień zdarzeń JSONL — wygodnie rozbierać go w potoku. Dokładnie tak sprawdzaliśmy to zestawienie 21 września 2026 na CLI 1.16.0: w nagłówku CLI wypisuje Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, następnie agent czyta plik i odpowiada konkretnie.

Zapisane ustawienia CLI leżą w ~/.openhands/agent_settings.json: model zmienia się tam przez edycję trzech pól bloku llm — model, api_key i base_url. Nie warto tworzyć pliku od zera: kreator pierwszego uruchomienia zapisuje tam też pozostałe ustawienia agenta, w tym kompresję historii, bez której długa rozmowa utknie w oknie kontekstu.

Jeśli wbudowujesz agenta we własny kod, te same trzy wartości przyjmuje 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"),
)

Cena modeli w sieci jest jednolita, więc wybór zależy od zachowania. Dla autonomicznego agenta kluczowe są dwie liczby. Okno kontekstowe: każdy krok wysyła historię od nowa, a im dłuższe okno, tym dłużej agent pracuje bez utraty danych. Limit odpowiedzi: krok, w którym agent zapisuje cały duży plik, musi mieścić się w jednej odpowiedzi. W tabeli znajdują się wyniki naszego testu tego samego zadania (odczyt pliku i znalezienie błędu) za pomocą OpenHands CLI 1.16.0 z SDK 1.21.0.

Działający schemat dla długiego zadania powtarza poradę z dokumentacji OpenHands — planowanie jednym modelem, wykonanie drugim. Rozpocznij rozmowę na profilu glm i poproś o plan bez wprowadzania zmian w plikach; następnie wyślij /model deepseek i wydaj polecenie wykonania. Historia, pliki i stan zadania są zachowywane przy przełączaniu. Profil minimax trzymaj jako trzeci: wygodnie się na niego przełączyć, gdy dwóm pozostałym w godzinach szczytu kończy się pojemność, a w Settings > Application można mu również powierzyć generowanie nagłówków rozmów.

Kompresja historii. Nawet okno liczące setki tysięcy tokenów przy wielogodzinnym zadaniu jest skończone. W OpenHands odpowiada za to kondenser: zwija stare zdarzenia w krótkie podsumowanie, co według dokumentacji zmniejsza opóźnienia i zużycie tokenów w długich rozmowach. W Agent Canvas konfiguruje się go w sekcji Settings > Condenser; w naszym teście CLI włączył go automatycznie, z progiem 80 zdarzeń.

Limity modelu. Okno kontekstowe i limit odpowiedzi OpenHands pobiera z wykazu LiteLLM, a identyfikatorów sieci Gonka w nim nie ma (sprawdziliśmy w LiteLLM 1.81), więc agent nie ma własnych wartości dla tych modeli. Nie przeszkadza to w pracy: bramka sama stosuje limit odpowiedzi zgodnie z tabelą powyżej. Jeśli chcesz określić limity jawnie — w SDK są to pola max_input_tokens i max_output_tokens, a w Canvas pełny zestaw pól profilu otwiera zakładka All. Szczegóły dotyczące domyślnego modelu znajdują się w przeglądzie DeepSeek V4 Flash.

Możesz upewnić się, że zapytania rzeczywiście przechodzą przez bramkę z dwóch stron. Od strony OpenHands — nowa rozmowa i krótkie zadanie, np. „przeczytaj README i streść w jednym zdaniu”: agent powinien wywołać narzędzie i odpowiedzieć. Od strony bramki — panel, sekcja „Użycie”: zapytanie pojawi się w podziale „Według modeli”, a w bloku „Według kluczy” zaktualizuje się czas ostatniego zapytania. Pusto oznacza, że rozmowa odbywa się na innym profilu: sprawdź, który z nich jest oznaczony jako aktywny.

Według dokumentacji OpenHands, liczba powtórzeń i pauzy między nimi przy błędzie 429 są konfigurowane zmiennymi LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT oraz LLM_RETRY_MAX_WAIT. Wartości domyślne w dokumentacji i SDK różnią się, dlatego kieruj się faktycznymi: w stanie rozmowy CLI 1.16.0 zaobserwowaliśmy 5 prób z pauzami od 8 do 64 sekund.

Przez JoinGonka Gateway tokeny kosztują $0.0069 za milion na wejściu i $0.021 za milion na wyjściu — cena jest identyczna dla wszystkich modeli sieci i jest pobierana na tej stronie ze źródła na żywo.

Szacunki w prawej kolumnie są oparte na cenach z września 2026; ekonomia agentów została szczegółowo omówiona w artykule o najtańszym API dla AI-agentów.

Limit wydatków. OpenHands zaleca ustawianie limitów wydatków — bramka ma to wbudowane w sam model płatności: saldo jest przedpłacone, a agent nie wyda więcej, niż masz na koncie. Saldo i dzienne zużycie widać w panelu. Dla CI i automatyzacji w tle stwórz osobny klucz, aby ich zużycie nie mieszało się z Twoim; klucze podrzędne z dziennym limitem są opisane w artykule o Management Keys.

Granica zaufania. Agent Canvas, uruchomiony przez npm, działa z uprawnieniami Twojego użytkownika i widzi cały system plików. W przypadku obcego kodu użyj wersji w Dockerze: agent zobaczy tylko zamontowany katalog. Jest to właściwość samego OpenHands i nie zależy od dostawcy modelu.

Korespondencja pozostaje u Ciebie. Historię rozmowy OpenHands przechowuje u siebie, w ~/.openhands, i wysyła ją do modelu z każdym krokiem; bramka nie przechowuje korespondencji — Twoje prompty i kod nie zostają na niej po otrzymaniu odpowiedzi.

Jeśli zadanie zawiera obrazy — zrzuty ekranu interfejsu, schematy — załóż dla niego osobny profil z modelem vision: modele sieci Gonka są tekstowe. Dla kodu, poleceń i plików nie jest to ograniczenie.