> Dla agentów AI: instrukcja konfiguracji krok po kroku — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), indeks dokumentacji — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Dla agentów AI

Jak przekazać integrację agentowi AI: gotowy prompt dla dowolnego narzędzia. Poniżej — maszynowo czytelne adresy dokumentacji i skill, który agent instaluje jednym poleceniem.

## Prompt dla agenta

Wyślij ten prompt swojemu agentowi AI. Skonfiguruje narzędzie według poniższej instrukcji, a o klucz poprosi Ciebie.

```text
Podłącz własne narzędzie do JoinGonka Gateway — API sieci Gonka zgodnego z OpenAI i Anthropic — według instrukcji https://gate.joingonka.ai/docs/agents.md. Klucz podam sam: nie zapisuj go w plikach repozytorium i nie zmieniaj globalnych zmiennych środowiskowych. Na koniec sprawdź połączenie krótkim zapytaniem i poinformuj o wyniku.
```

Poniżej znajduje się sama instrukcja. Agent otrzymuje ją w formacie Markdown pod adresem [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Zasady

- Klucz API tworzy człowiek — w panelu klienta na [gate.joingonka.ai](https://gate.joingonka.ai/keys). Nie zakładaj konta ani nie twórz kluczy samodzielnie: poproś użytkownika o klucz.
- Trzymaj klucz w zmiennej środowiskowej `JOINGONKA_API_KEY` swojej sesji terminala. Nie zapisuj go w plikach objętych git, nie commituj i nie wypisuj w raporcie.
- Nie zmieniaj globalnych zmiennych `OPENAI_*` i `ANTHROPIC_*` — ani w profilu powłoki, ani w systemie: czytają je inne narzędzia użytkownika. Klucz i adres są zapisywane w konfiguracji samego narzędzia — tak robi instalator.

## Fakty

- Adres bazowy dla klientów OpenAI API: `https://gate.joingonka.ai/v1`
- Adres bazowy dla klientów Anthropic API, bez `/v1`: `https://gate.joingonka.ai`
- Klucz przekazywany jest w nagłówku `Authorization: Bearer jg-…` lub `x-api-key: jg-…`
- Klucz do zapytań do modeli zaczyna się od `jg-`; klucz zarządzania `gm-` nie wpuszcza do modeli.
- Zalecany model: `MiniMaxAI/MiniMax-M2.7`
- Lista dostępnych modeli: `GET https://gate.joingonka.ai/v1/models`
- Na klucz — do 120 zapytań na minutę, powyżej limitu — odpowiedź 429 z nagłówkiem `Retry-After`. Limity i limity czasu — w odpowiedzi `GET /v1/capabilities`, pole `limits`.

## Konfiguracja

Znajdź narzędzie użytkownika w tabeli na końcu sekcji. Jest wartość `--tool` — konfiguruj instalatorem, nie ma — ręcznie według przewodnika.

### Przez instalator

Jedna komenda bez pytań: klucz — ze zmiennej środowiskowej, model — flagą. Instalator zapisze konfigurację narzędzia, zachowa kopię poprzedniej i sprawdzi połączenie zapytaniem do bramy.

```bash
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive
```

| Flaga | Co robi |
| --- | --- |
| `--tool <id>` | Które narzędzie skonfigurować — wartość z tabeli narzędzi. |
| `--model <id>` | Identyfikator modelu: zalecany — `MiniMaxAI/MiniMax-M2.7`, wszystkie dostępne — `GET /v1/models`. |
| `--non-interactive` | Bez pytań: klucz pobierany z `JOINGONKA_API_KEY`. |
| `--scope local` | Konfiguracja w bieżącym projekcie, a nie w katalogu domowym. Tylko dla Claude Code; plik konfiguracji jest dodawany do `.gitignore`. |
| `--no-verify` | Nie sprawdzaj połączenia po zapisaniu konfiguracji. |

| Kod wyjścia | Co oznacza |
| --- | --- |
| `0` | Gotowe: konfiguracja zapisana, zapytanie sprawdzające przeszło. Jeśli weryfikacja nie powiodła się z powodu sieci lub salda, instalator wyświetla ostrzeżenie, ale również kończy z kodem 0 — poinformuj o tym użytkownika. |
| `1` | Konfiguracja nie powiodła się, przyczyna — w danych wyjściowych: na przykład nieznana wartość `--tool`, nie ustawiono `JOINGONKA_API_KEY` lub klucz nie zaczyna się od `jg-`. |
| `2` | Konfiguracja zapisana, ale zapytanie sprawdzające nie powiodło się: sprawdź klucz i identyfikator modelu. |

Jeśli narzędzie było uruchomione, zrestartuj je: konfiguracja jest czytana przy starcie.

### Ręcznie

Dla narzędzia bez instalatora otwórz jego przewodnik (link w tabeli poniżej) i ustaw trzy wartości:

- adres bazowy — `https://gate.joingonka.ai/v1` dla klientów OpenAI API lub `https://gate.joingonka.ai` dla klientów Anthropic API;
- klucz — w polu klucza API w ustawieniach narzędzia;
- model — `MiniMaxAI/MiniMax-M2.7` lub inny z `GET /v1/models`.

### Narzędzia i przewodniki

| Narzędzie | `--tool` |
| --- | --- |
| [Cursor](https://joingonka.ai/pl/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/pl/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/pl/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/pl/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/pl/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/pl/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/pl/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/pl/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/pl/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/pl/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/pl/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/pl/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/pl/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/pl/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/pl/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/pl/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/pl/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/pl/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/pl/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/pl/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/pl/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/pl/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/pl/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/pl/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/pl/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/pl/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/pl/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/pl/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/pl/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/pl/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/pl/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/pl/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/pl/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/pl/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/pl/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/pl/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/pl/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/pl/knowledge/mimo-code/) | `mimo-code` |

## Weryfikacja

Weryfikacja klucza — zapytanie o saldo: nie zużywa tokenów, klucz pobierany z `JOINGONKA_API_KEY`:

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

Weryfikacja adresu, klucza i modelu — krótkie zapytanie do modelu:

```bash
curl -s https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'
```

Odpowiedź `200` z tekstem modelu — połączenie działa. Instalator sam wykonuje taką weryfikację: po nim wystarczy kod wyjścia 0.

## Jeśli coś jest nie tak

Błąd przychodzi w polu `error` treści odpowiedzi — z typem i tekstem przyczyny.

| Odpowiedź | Co zrobić |
| --- | --- |
| `401 authentication_error` | Klucz nie został przyjęty. Sprawdź, czy jest skopiowany w całości i przekazany w `Authorization: Bearer` lub `x-api-key`; nowy klucz tworzy użytkownik. |
| `402 insufficient_funds` | Na saldzie brak środków. Poinformuj użytkownika: saldo można zasilić w panelu klienta. |
| `402 child_key_limit_exceeded` | Wyczerpany limit klucza podrzędnego. Potrzebny inny klucz lub większy limit — decyduje o tym właściciel klucza. |
| `403 forbidden` | To klucz zarządzania `gm-`: nie wpuszcza do modeli. Potrzebny klucz `jg-`. |
| `400 invalid_request_error` | Błąd w zapytaniu. Jeśli nie znaleziono modelu, w treści błędu jest lista dostępnych identyfikatorów — weź stamtąd lub z `GET /v1/models`. |
| `404 model_not_found` | Takiego modelu teraz nie ma — wybierz inny z `GET /v1/models`. |
| `429` | Zbyt wiele zapytań lub zajęta sieć. Poczekaj tyle sekund, ile podano w nagłówku `Retry-After`, i powtórz. |
| `503 model_unavailable` | Sieć teraz nie obsługuje modelu. Przełącz się na model z treści błędu lub na inny z `GET /v1/models`. |
| `504 upstream_timeout` | Sieć nie zaczęła odpowiadać na czas. Powtórz zapytanie; dla długich odpowiedzi włącz `stream: true`. |
| `502` | Awaria po stronie bramy lub sieci — klucz nie ma z tym nic wspólnego. Powtórz później; stan sieci — na stronie [Status sieci](https://gate.joingonka.ai/pl/status). |

Wszystkie kody odpowiedzi i limity — w sekcji [Błędy i limity](https://gate.joingonka.ai/pl/docs/errors).

## Raport

Na koniec poinformuj użytkownika:

- które narzędzie zostało skonfigurowane i jaki plik konfiguracji zapisano (ścieżkę wyświetla instalator, kopia poprzedniej — obok);
- adres bazowy i identyfikator modelu;
- wynik weryfikacji: kod odpowiedzi i odpowiedź modelu — albo dlaczego nie udało się zweryfikować;
- co użytkownik musi zrobić sam: na przykład zrestartować narzędzie lub doładować saldo.

Nie umieszczaj klucza w raporcie.

## Adresy maszynowe

| Adres | Co się tam znajduje |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Indeks dokumentacji dla modeli językowych. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Cała dokumentacja w jednym pliku. |
| `/docs/<page>.md` | Wersja Markdown strony dokumentacji: ten sam adres z `.md` na końcu ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) lub żądanie strony z nagłówkiem `Accept: text/markdown`. |
| `GET /v1/capabilities` | Możliwości bramy i jej limity — pole `limits`. |
| `GET /v1/models` | Modele dostępne obecnie. |
| `GET /api/pricing` | Ceny za modele za 1M tokenów i prowizje. |
| `GET /v1/network-status` | Status modeli i incydenty. |

## Umiejętność dla agenta

Instrukcję można zainstalować agentowi jako umiejętność (skill) — wtedy będzie miał ją pod ręką, nawet bez promptu:

```bash
npx skills add https://gate.joingonka.ai
```