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

# Для ИИ-агентов

Как поручить подключение ИИ-агенту: готовый промпт для любого инструмента. Ниже — машинные адреса документации и навык, который агент ставит одной командой.

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

Отправьте этот промпт своему ИИ-агенту. Он настроит инструмент по инструкции ниже, а ключ попросит у вас.

```text
Подключи свой инструмент к JoinGonka Gateway — OpenAI- и Anthropic-совместимому API сети Gonka — по инструкции 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/ru/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/ru/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/ru/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/ru/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/ru/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/ru/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/ru/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/ru/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/ru/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/ru/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/ru/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/ru/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/ru/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/ru/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/ru/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/ru/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/ru/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/ru/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/ru/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/ru/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/ru/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/ru/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/ru/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/ru/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/ru/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/ru/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/ru/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/ru/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/ru/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/ru/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/ru/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/ru/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/ru/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/ru/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/ru/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/ru/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/ru/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/ru/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/ru/status). |

Все коды ответов и лимиты — в разделе [Ошибки и лимиты](https://gate.joingonka.ai/ru/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
```