> Für KI-Agenten: Schritt-für-Schritt-Anleitung zur Einrichtung — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), Dokumentationsindex — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Für KI-Agenten

Wie man die Anbindung an einen KI-Agenten übergibt: ein fertiger Prompt für jedes Tool. Unten — maschinenlesbare Dokumentationsadressen und ein Skill, den der Agent mit einem einzigen Befehl installiert.

## Prompt für den Agenten

Senden Sie diesen Prompt an Ihren KI-Agenten. Er richtet das Tool nach der folgenden Anleitung ein und fragt Sie nach dem Schlüssel.

```text
Verbinde eigenes Tool mit dem JoinGonka Gateway – der OpenAI- und Anthropic-kompatiblen API des Gonka-Netzwerks – gemäß der Anleitung https://gate.joingonka.ai/docs/agents.md. Den Schlüssel gebe ich selbst an: Speichere ihn nicht in Repository-Dateien und ändere keine globalen Umgebungsvariablen. Prüfe am Ende die Verbindung mit einer kurzen Anfrage und melde das Ergebnis.
```

Unten steht die Anleitung selbst. Der Agent ruft sie als Markdown unter [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md) ab.

## Regeln

- Den API-Schlüssel erstellt ein Mensch — im Kundenbereich auf [gate.joingonka.ai](https://gate.joingonka.ai/keys). Registrieren Sie kein Konto und legen Sie keine Schlüssel selbst an: Bitten Sie den Nutzer um den Schlüssel.
- Halten Sie den Schlüssel in der Umgebungsvariable `JOINGONKA_API_KEY` Ihrer Terminal-Sitzung. Schreiben Sie ihn nicht in Dateien unter Git, committen Sie ihn nicht und geben Sie ihn nicht im Bericht aus.
- Ändern Sie nicht die globalen Variablen `OPENAI_*` und `ANTHROPIC_*` — weder im Shell-Profil noch systemweit: Andere Tools des Nutzers lesen sie. Schlüssel und Adresse werden in der Konfigurationsdatei des Tools selbst gespeichert — genau das macht der Installer.

## Fakten

- Basis-URL für OpenAI-API-Clients: `https://gate.joingonka.ai/v1`
- Basis-URL für Anthropic-API-Clients, ohne `/v1`: `https://gate.joingonka.ai`
- Der Schlüssel wird im Header `Authorization: Bearer jg-…` oder `x-api-key: jg-…` übergeben
- Der Schlüssel für Modellanfragen beginnt mit `jg-`; der Verwaltungsschlüssel `gm-` lässt keine Modellzugriffe zu.
- Empfohlenes Modell: `MiniMaxAI/MiniMax-M2.7`
- Liste der verfügbaren Modelle: `GET https://gate.joingonka.ai/v1/models`
- Pro Schlüssel — bis zu 120 Anfragen pro Minute, über dem Limit — Antwort 429 mit dem Header `Retry-After`. Limits und Timeouts — in der Antwort `GET /v1/capabilities`, Feld `limits`.

## Einrichtung

Finden Sie das Tool des Nutzers in der Tabelle am Ende des Abschnitts. Gibt es den Wert `--tool` — richten Sie es mit dem Installer ein, sonst — manuell nach dem Guide.

### Über den Installer

Ein Befehl ohne Rückfragen: Der Schlüssel kommt aus der Umgebungsvariable, das Modell aus dem Flag. Der Installer schreibt die Tool-Konfiguration, sichert eine Kopie der alten und prüft die Verbindung mit einer Anfrage an das Gateway.

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

| Flag | Was es bewirkt |
| --- | --- |
| `--tool <id>` | Welches Tool eingerichtet wird — Wert aus der Tool-Tabelle. |
| `--model <id>` | Modell-ID: empfohlen — `MiniMaxAI/MiniMax-M2.7`, alle verfügbaren — `GET /v1/models`. |
| `--non-interactive` | Ohne Rückfragen: Der Schlüssel wird aus `JOINGONKA_API_KEY` gelesen. |
| `--scope local` | Konfiguration im aktuellen Projekt statt im Home-Verzeichnis. Nur für Claude Code; die Konfigurationsdatei wird zu `.gitignore` hinzugefügt. |
| `--no-verify` | Verbindung nach dem Schreiben der Konfiguration nicht prüfen. |

| Exit-Code | Bedeutung |
| --- | --- |
| `0` | Fertig: Konfiguration geschrieben, Test-Anfrage erfolgreich. Wenn die Prüfung wegen Netzwerk oder Guthaben nicht möglich war, gibt der Installer eine Warnung aus, beendet sich aber trotzdem mit Code 0 — informieren Sie den Nutzer darüber. |
| `1` | Die Einrichtung ist fehlgeschlagen, der Grund steht in der Ausgabe: zum Beispiel ein unbekannter Wert für `--tool`, `JOINGONKA_API_KEY` nicht gesetzt oder der Schlüssel beginnt nicht mit `jg-`. |
| `2` | Konfiguration geschrieben, aber die Test-Anfrage ist fehlgeschlagen: Prüfen Sie Schlüssel und Modell-ID. |

Wenn das Tool bereits lief, starten Sie es neu: Die Konfiguration wird beim Start gelesen.

### Manuell

Öffnen Sie für ein Tool ohne Installer dessen Guide (Link in der Tabelle unten) und setzen Sie drei Werte:

- Basisadresse — `https://gate.joingonka.ai/v1` für OpenAI-API-Clients oder `https://gate.joingonka.ai` für Anthropic-API-Clients;
- Schlüssel — im Feld API-Schlüssel in den Tool-Einstellungen;
- Modell — `MiniMaxAI/MiniMax-M2.7` oder ein anderes aus `GET /v1/models`.

### Tools und Guides

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

## Prüfung

Schlüsselprüfung — Abfrage des Guthabens: Sie verbraucht keine Tokens, der Schlüssel kommt aus `JOINGONKA_API_KEY`:

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

Prüfung von Adresse, Schlüssel und Modell — eine kurze Anfrage an das Modell:

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

Antwort `200` mit Modelltext — die Verbindung funktioniert. Der Installer führt eine solche Prüfung selbst durch: Danach genügt Exit-Code 0.

## Wenn etwas nicht stimmt

Der Fehler kommt im Feld `error` des Antwort-Bodys — mit Typ und Text der Ursache.

| Antwort | Was zu tun ist |
| --- | --- |
| `401 authentication_error` | Der Schlüssel wurde nicht akzeptiert. Prüfen Sie, ob er vollständig kopiert und in `Authorization: Bearer` oder `x-api-key` übergeben wurde; einen neuen Schlüssel legt der Nutzer an. |
| `402 insufficient_funds` | Auf dem Guthaben sind keine Mittel. Informieren Sie den Nutzer: Das Guthaben wird im Kundenbereich aufgeladen. |
| `402 child_key_limit_exceeded` | Das Limit des Unterschlüssels ist ausgeschöpft. Es braucht einen anderen Schlüssel oder ein höheres Limit — das entscheidet der Schlüsselbesitzer. |
| `403 forbidden` | Das ist der Verwaltungsschlüssel `gm-`: Er lässt keine Modellzugriffe zu. Es braucht einen Schlüssel `jg-`. |
| `400 invalid_request_error` | Fehler in der Anfrage. Wird das Modell nicht gefunden, enthält der Fehlertext die Liste der verfügbaren IDs — nehmen Sie eine von dort oder aus `GET /v1/models`. |
| `404 model_not_found` | Dieses Modell gibt es gerade nicht — wählen Sie ein anderes aus `GET /v1/models`. |
| `429` | Zu viele Anfragen oder das Netzwerk ist ausgelastet. Warten Sie so viele Sekunden, wie im Header `Retry-After` angegeben, und wiederholen Sie. |
| `503 model_unavailable` | Das Netzwerk bedient das Modell gerade nicht. Wechseln Sie zu dem Modell aus dem Fehlertext oder zu einem anderen aus `GET /v1/models`. |
| `504 upstream_timeout` | Das Netzwerk hat nicht rechtzeitig zu antworten begonnen. Wiederholen Sie die Anfrage; für lange Antworten aktivieren Sie `stream: true`. |
| `502` | Störung auf Seiten des Gateways oder Netzwerks — der Schlüssel ist nicht das Problem. Wiederholen Sie später; den Netzwerkstatus finden Sie auf der Seite [Netzwerkstatus](https://gate.joingonka.ai/de/status). |

Alle Antwortcodes und Limits — im Abschnitt [Fehler und Limits](https://gate.joingonka.ai/de/docs/errors).

## Bericht

Teilen Sie dem Nutzer am Ende mit:

- welches Tool eingerichtet und welche Konfigurationsdatei geschrieben wurde (den Pfad gibt der Installer aus, die Kopie der alten liegt daneben);
- Basis-URL und Modell-ID;
- Ergebnis der Prüfung: Antwortcode und Antwort des Modells – oder warum die Prüfung nicht möglich war;
- was der Nutzer noch selbst tun muss: zum Beispiel das Tool neu starten oder das Guthaben aufladen.

Den Schlüssel nicht in den Bericht aufnehmen.

## Maschinenadressen

| Adresse | Was sich dahinter verbirgt |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Dokumentationsindex für Sprachmodelle. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Die gesamte Dokumentation als eine Datei. |
| `/docs/<page>.md` | Markdown-Version einer Dokumentationsseite: dieselbe Adresse mit `.md` am Ende ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) oder eine Seitenanfrage mit dem Header `Accept: text/markdown`. |
| `GET /v1/capabilities` | Funktionen des Gateways und seine Limits – Feld `limits`. |
| `GET /v1/models` | Aktuell verfügbare Modelle. |
| `GET /api/pricing` | Preise pro Modell für 1M Tokens und Gebühren. |
| `GET /v1/network-status` | Modellstatus und Vorfälle. |

## Skill für den Agenten

Die Anleitung lässt sich dem Agenten als Skill installieren – dann steht sie ihm jederzeit zur Verfügung, ganz ohne Prompt:

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