> Untuk agen AI: panduan pengaturan langkah demi langkah — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), indeks dokumentasi — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Untuk agen AI

Cara menyerahkan integrasi kepada agen AI: prompt siap pakai untuk tool apa pun. Di bawah ini — alamat dokumentasi yang dapat dibaca mesin dan skill yang dipasang agen dengan satu perintah.

## Prompt untuk agen

Kirim prompt ini ke agen AI Anda. Agen akan menyiapkan alat sesuai panduan di bawah, dan meminta kunci dari Anda.

```text
Hubungkan alat Anda ke JoinGonka Gateway — API jaringan Gonka yang kompatibel dengan OpenAI dan Anthropic — sesuai instruksi https://gate.joingonka.ai/docs/agents.md. Kunci akan saya berikan sendiri: jangan simpan di file repositori dan jangan ubah variabel lingkungan global. Di akhir, verifikasi koneksi dengan permintaan singkat dan laporkan hasilnya.
```

Berikut panduannya. Agen menerimanya dalam format Markdown di alamat [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Aturan

- Kunci API dibuat oleh manusia — di dasbor pribadi pada [gate.joingonka.ai](https://gate.joingonka.ai/keys). Jangan mendaftarkan akun atau membuat kunci sendiri: minta kunci dari pengguna.
- Simpan kunci di variabel lingkungan `JOINGONKA_API_KEY` pada sesi terminal Anda. Jangan menuliskannya ke file yang dilacak git, jangan commit, dan jangan tampilkan di laporan.
- Jangan mengubah variabel global `OPENAI_*` dan `ANTHROPIC_*` — baik di profil shell maupun di sistem: alat lain milik pengguna membacanya. Kunci dan alamat ditulis ke konfigurasi alat itu sendiri — itulah yang dilakukan penginstal.

## Fakta

- Alamat dasar untuk klien OpenAI API: `https://gate.joingonka.ai/v1`
- Alamat dasar untuk klien Anthropic API, tanpa `/v1`: `https://gate.joingonka.ai`
- Kunci dikirim melalui header `Authorization: Bearer jg-…` atau `x-api-key: jg-…`
- Kunci untuk mengakses model diawali dengan `jg-`; kunci pengelolaan `gm-` tidak memberi akses ke model.
- Model yang direkomendasikan: `MiniMaxAI/MiniMax-M2.7`
- Daftar model yang tersedia: `GET https://gate.joingonka.ai/v1/models`
- Per kunci — hingga 120 permintaan per menit, di atas batas — respons 429 dengan header `Retry-After`. Batas dan timeout — di respons `GET /v1/capabilities`, field `limits`.

## Konfigurasi

Temukan alat milik pengguna di tabel di akhir bagian. Jika ada nilai `--tool` — konfigurasikan dengan penginstal, jika tidak — secara manual mengikuti panduan.

### Lewat penginstal

Satu perintah tanpa pertanyaan: kunci — dari variabel lingkungan, model — lewat flag. Penginstal akan menulis konfigurasi alat, menyimpan salinan yang lama, dan memverifikasi koneksi dengan permintaan ke gateway.

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

| Flag | Fungsinya |
| --- | --- |
| `--tool <id>` | Alat mana yang disiapkan — nilai dari tabel alat. |
| `--model <id>` | ID model: yang direkomendasikan — `MiniMaxAI/MiniMax-M2.7`, semua yang tersedia — `GET /v1/models`. |
| `--non-interactive` | Tanpa pertanyaan: kunci diambil dari `JOINGONKA_API_KEY`. |
| `--scope local` | Konfigurasi di proyek saat ini, bukan di direktori home. Hanya untuk Claude Code; file konfigurasi ditambahkan ke `.gitignore`. |
| `--no-verify` | Jangan verifikasi koneksi setelah menulis konfigurasi. |

| Kode keluar | Artinya |
| --- | --- |
| `0` | Selesai: konfigurasi tertulis, permintaan verifikasi berhasil. Jika verifikasi gagal karena jaringan atau saldo, penginstal mencetak peringatan tetapi tetap keluar dengan kode 0 — beri tahu pengguna tentang ini. |
| `1` | Penyiapan gagal, penyebabnya ada di output: misalnya, nilai `--tool` tidak dikenal, `JOINGONKA_API_KEY` tidak diatur, atau kunci tidak diawali dengan `jg-`. |
| `2` | Konfigurasi tertulis, tetapi permintaan verifikasi gagal: periksa kunci dan ID model. |

Jika alat sedang berjalan, mulai ulang: konfigurasi dibaca saat start.

### Secara manual

Untuk alat tanpa penginstal, buka panduannya (tautan di tabel bawah) dan isi tiga nilai:

- alamat dasar — `https://gate.joingonka.ai/v1` untuk klien OpenAI API atau `https://gate.joingonka.ai` untuk klien Anthropic API;
- kunci — di field kunci API pada pengaturan alat;
- model — `MiniMaxAI/MiniMax-M2.7` atau lainnya dari `GET /v1/models`.

### Alat dan panduan

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

## Verifikasi

Verifikasi kunci — permintaan saldo: tidak menghabiskan token, kunci diambil dari `JOINGONKA_API_KEY`:

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

Verifikasi alamat, kunci, dan model — permintaan singkat ke model:

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

Respons `200` dengan teks dari model — koneksi berfungsi. Penginstal melakukan verifikasi ini sendiri: setelahnya cukup kode keluar 0.

## Jika ada masalah

Error muncul di field `error` pada body respons — dengan tipe dan teks penyebabnya.

| Respons | Yang harus dilakukan |
| --- | --- |
| `401 authentication_error` | Kunci tidak diterima. Periksa bahwa kunci disalin utuh dan dikirim di `Authorization: Bearer` atau `x-api-key`; kunci baru dibuat oleh pengguna. |
| `402 insufficient_funds` | Saldo tidak mencukupi. Beri tahu pengguna: saldo diisi di dasbor pribadi. |
| `402 child_key_limit_exceeded` | Batas kunci anak sudah habis. Perlu kunci lain atau batas yang lebih besar — itu keputusan pemilik kunci. |
| `403 forbidden` | Ini kunci pengelolaan `gm-`: tidak memberi akses ke model. Perlu kunci `jg-`. |
| `400 invalid_request_error` | Ada kesalahan pada permintaan. Jika model tidak ditemukan, teks error memuat daftar ID yang tersedia — ambil dari sana atau dari `GET /v1/models`. |
| `404 model_not_found` | Model tersebut sedang tidak tersedia — pilih yang lain dari `GET /v1/models`. |
| `429` | Terlalu banyak permintaan atau jaringan sedang sibuk. Tunggu sebanyak detik yang tertera di header `Retry-After`, lalu coba lagi. |
| `503 model_unavailable` | Jaringan sedang tidak melayani model tersebut. Beralih ke model yang disebutkan di teks error atau ke model lain dari `GET /v1/models`. |
| `504 upstream_timeout` | Jaringan tidak mulai merespons tepat waktu. Ulangi permintaan; untuk respons panjang aktifkan `stream: true`. |
| `502` | Gangguan di sisi gateway atau jaringan — kunci tidak ada hubungannya. Coba lagi nanti; status jaringan ada di halaman [Status jaringan](https://gate.joingonka.ai/id/status). |

Semua kode respons dan batas — di bagian [Error dan batas](https://gate.joingonka.ai/id/docs/errors).

## Laporan

Di akhir, beri tahu pengguna:

- alat mana yang disiapkan dan file konfigurasi mana yang ditulis (path dicetak oleh penginstal, salinan yang lama ada di sebelahnya);
- alamat dasar dan ID model;
- hasil pemeriksaan: kode respons dan balasan model — atau alasan pemeriksaan tidak bisa dilakukan;
- apa yang masih harus dilakukan pengguna sendiri: misalnya, memulai ulang alat atau mengisi saldo.

Jangan sertakan kunci di dalam laporan.

## Alamat untuk mesin

| Alamat | Isinya |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Indeks dokumentasi untuk model bahasa. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Seluruh dokumentasi dalam satu berkas. |
| `/docs/<page>.md` | Versi Markdown dari halaman dokumentasi: alamat yang sama dengan `.md` di akhir ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) atau permintaan halaman dengan header `Accept: text/markdown`. |
| `GET /v1/capabilities` | Kemampuan dan batas gateway — kolom `limits`. |
| `GET /v1/models` | Model yang tersedia saat ini. |
| `GET /api/pricing` | Harga per model untuk 1M token dan biaya. |
| `GET /v1/network-status` | Status model dan insiden. |

## Skill untuk agen

Instruksi ini bisa dipasang sebagai skill untuk agen Anda — sehingga selalu tersedia tanpa perlu prompt:

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