> Для ШІ-агентів: покрокова інструкція з налаштування — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), індекс документації — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Для ШІ-агентів

Як доручити підключення ШІ-агенту: готовий промпт для будь-якого інструмента. Нижче — машинні адреси документації та навичка, яку агент встановлює однією командою.

## Промпт для агента

Надішліть цей промпт своєму ШІ-агенту. Він налаштує інструмент за інструкцією нижче, а ключ попросить у вас.

```text
Підключи свій інструмент до JoinGonka Gateway — API мережі Gonka, сумісного з OpenAI та Anthropic — за інструкцією https://gate.joingonka.ai/docs/agents.md. Ключ я дам сам: не зберігай його у файлах репозиторію і не змінюй глобальні змінні середовища. Наприкінці перевір підключення коротким запитом і повідом результат.
```

Нижче — сама інструкція. Агент отримує її у вигляді Markdown за адресою [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Правила

- Ключ API створює людина — в особистому кабінеті на [gate.joingonka.ai](https://gate.joingonka.ai/keys). Не реєструйте акаунт і не створюйте ключі самі: попросіть ключ у користувача.
- Тримайте ключ у змінній середовища `JOINGONKA_API_KEY` своєї сесії термінала. Не записуйте його у файли під git, не комітьте і не виводьте у звіті.
- Не змінюйте глобальні змінні `OPENAI_*` і `ANTHROPIC_*` — ні в профілі оболонки, ні в системі: їх читають інші інструменти користувача. Ключ і адреса записуються в конфіг самого інструмента — так робить інсталятор.

## Факти

- Базова адреса для клієнтів OpenAI API: `https://gate.joingonka.ai/v1`
- Базова адреса для клієнтів Anthropic API, без `/v1`: `https://gate.joingonka.ai`
- Ключ передається в заголовку `Authorization: Bearer jg-…` або `x-api-key: jg-…`
- Ключ для запитів до моделей починається з `jg-`; ключ керування `gm-` до моделей не пускає.
- Рекомендована модель: `MiniMaxAI/MiniMax-M2.7`
- Список доступних моделей: `GET https://gate.joingonka.ai/v1/models`
- На ключ — до 120 запитів за хвилину, понад ліміт — відповідь 429 із заголовком `Retry-After`. Ліміти й таймаути — у відповіді `GET /v1/capabilities`, поле `limits`.

## Налаштування

Знайдіть інструмент користувача в таблиці в кінці розділу. Є значення `--tool` — налаштовуйте інсталятором, немає — вручну за гайдом.

### Через інсталятор

Одна команда без запитань: ключ — зі змінної середовища, модель — прапорцем. Інсталятор запише конфіг інструмента, збереже копію попереднього й перевірить підключення запитом до шлюзу.

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

| Прапорець | Що робить |
| --- | --- |
| `--tool <id>` | Який інструмент налаштувати — значення з таблиці інструментів. |
| `--model <id>` | Ідентифікатор моделі: рекомендована — `MiniMaxAI/MiniMax-M2.7`, усі доступні — `GET /v1/models`. |
| `--non-interactive` | Без запитань: ключ береться з `JOINGONKA_API_KEY`. |
| `--scope local` | Конфіг у поточному проєкті, а не в домашньому каталозі. Лише для Claude Code; файл конфіга додається в `.gitignore`. |
| `--no-verify` | Не перевіряти підключення після запису конфіга. |

| Код виходу | Що означає |
| --- | --- |
| `0` | Готово: конфіг записано, перевірний запит пройшов. Якщо перевірити не вдалося через мережу чи баланс, інсталятор друкує попередження, але теж виходить із кодом 0 — повідомте про це користувача. |
| `1` | Налаштування не вдалося, причина — у виводі: наприклад, невідоме значення `--tool`, не задано `JOINGONKA_API_KEY` або ключ не починається з `jg-`. |
| `2` | Конфіг записано, але перевірний запит не пройшов: перевірте ключ та ідентифікатор моделі. |

Якщо інструмент було запущено, перезапустіть його: конфіг читається при старті.

### Вручну

Для інструмента без інсталятора відкрийте його гайд (посилання в таблиці нижче) і задайте три значення:

- базова адреса — `https://gate.joingonka.ai/v1` для клієнтів OpenAI API або `https://gate.joingonka.ai` для клієнтів Anthropic API;
- ключ — у полі API-ключа в налаштуваннях інструмента;
- модель — `MiniMaxAI/MiniMax-M2.7` або іншу з `GET /v1/models`.

### Інструменти та гайди

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

## Перевірка

Перевірка ключа — запит балансу: він не витрачає токени, ключ береться з `JOINGONKA_API_KEY`:

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

Перевірка адреси, ключа й моделі — короткий запит до моделі:

```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}'
```

Відповідь `200` із текстом моделі — підключення працює. Інсталятор робить таку перевірку сам: після нього достатньо коду виходу 0.

## Якщо щось не так

Помилка приходить у полі `error` тіла відповіді — з типом і текстом причини.

| Відповідь | Що робити |
| --- | --- |
| `401 authentication_error` | Ключ не прийнято. Перевірте, що він скопійований повністю і переданий у `Authorization: Bearer` або `x-api-key`; новий ключ створює користувач. |
| `402 insufficient_funds` | На балансі немає коштів. Повідомте користувача: баланс поповнюється в особистому кабінеті. |
| `402 child_key_limit_exceeded` | Вичерпано ліміт дочірнього ключа. Потрібен інший ключ або більший ліміт — це вирішує власник ключа. |
| `403 forbidden` | Це ключ керування `gm-`: до моделей він не пускає. Потрібен ключ `jg-`. |
| `400 invalid_request_error` | Помилка в запиті. Якщо модель не знайдено, у тексті помилки є список доступних ідентифікаторів — візьміть звідти або з `GET /v1/models`. |
| `404 model_not_found` | Такої моделі зараз немає — виберіть іншу з `GET /v1/models`. |
| `429` | Забагато запитів або зайнята мережа. Зачекайте стільки секунд, скільки вказано в заголовку `Retry-After`, і повторіть. |
| `503 model_unavailable` | Мережа зараз не обслуговує модель. Переключіться на модель із тексту помилки або на іншу з `GET /v1/models`. |
| `504 upstream_timeout` | Мережа не почала відповідати вчасно. Повторіть запит; для довгих відповідей увімкніть `stream: true`. |
| `502` | Збій на боці шлюзу або мережі — ключ ні до чого. Повторіть пізніше; стан мережі — на сторінці [Статус мережі](https://gate.joingonka.ai/uk/status). |

Усі коди відповідей і ліміти — в розділі [Помилки та ліміти](https://gate.joingonka.ai/uk/docs/errors).

## Звіт

Наприкінці повідомте користувача:

- який інструмент налаштовано і який файл конфіга записано (шлях друкує інсталятор, копія попереднього — поруч);
- базова адреса та ідентифікатор моделі;
- результат перевірки: код відповіді та відповідь моделі — або чому перевірити не вдалося;
- що користувач має зробити сам: наприклад, перезапустити інструмент або поповнити баланс.

Ключ у звіт не додавайте.

## Машинні адреси

| Адреса | Що там |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Індекс документації для мовних моделей. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Уся документація одним файлом. |
| `/docs/<page>.md` | Markdown-версія сторінки документації: та сама адреса з `.md` у кінці ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) або запит сторінки із заголовком `Accept: text/markdown`. |
| `GET /v1/capabilities` | Можливості шлюзу та його ліміти — поле `limits`. |
| `GET /v1/models` | Моделі, доступні зараз. |
| `GET /api/pricing` | Ціни за моделями за 1M токенів і комісії. |
| `GET /v1/network-status` | Статус моделей та інциденти. |

## Навичка для агента

Інструкцію можна встановити агенту як навичку (skill) — тоді вона буде в нього під рукою й без промпту:

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