> Per gli agenti AI: guida passo passo alla configurazione — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), indice della documentazione — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Per gli agenti AI

Come affidare l'integrazione a un agente AI: prompt pronto per qualsiasi strumento. Di seguito — indirizzi della documentazione leggibili dalle macchine e una skill che l'agente installa con un solo comando.

## Prompt per l'agente

Invia questo prompt al tuo agente AI. Configurerà lo strumento seguendo le istruzioni qui sotto e ti chiederà la chiave.

```text
Collega il tuo strumento a JoinGonka Gateway, l'API compatibile con OpenAI e Anthropic della rete Gonka, seguendo le istruzioni su https://gate.joingonka.ai/docs/agents.md. La chiave te la fornisco io: non salvarla nei file del repository e non modificare le variabili d'ambiente globali. Alla fine verifica la connessione con una breve richiesta e riporta il risultato.
```

Qui sotto ci sono le istruzioni. L'agente le riceve in formato Markdown all'indirizzo [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Regole

- La chiave API è creata da una persona — nella dashboard su [gate.joingonka.ai](https://gate.joingonka.ai/keys). Non registrare account e non creare chiavi da solo: chiedi la chiave all'utente.
- Tieni la chiave nella variabile d'ambiente `JOINGONKA_API_KEY` della tua sessione terminale. Non scriverla in file sotto git, non fare commit e non mostrarla nel report.
- Non modificare le variabili globali `OPENAI_*` e `ANTHROPIC_*` — né nel profilo della shell né a livello di sistema: vengono lette da altri strumenti dell'utente. La chiave e l'indirizzo vengono scritti nella configurazione dello strumento stesso — è ciò che fa l'installer.

## Fatti

- Base URL per i client OpenAI API: `https://gate.joingonka.ai/v1`
- Base URL per i client Anthropic API, senza `/v1`: `https://gate.joingonka.ai`
- La chiave si passa nell'header `Authorization: Bearer jg-…` oppure `x-api-key: jg-…`
- La chiave per le richieste ai modelli inizia con `jg-`; la chiave di gestione `gm-` non dà accesso ai modelli.
- Modello consigliato: `MiniMaxAI/MiniMax-M2.7`
- Elenco dei modelli disponibili: `GET https://gate.joingonka.ai/v1/models`
- Per chiave — fino a 120 richieste al minuto, oltre il limite risposta 429 con header `Retry-After`. Limiti e timeout sono nella risposta `GET /v1/capabilities`, campo `limits`.

## Configurazione

Trova lo strumento dell'utente nella tabella in fondo alla sezione. Se esiste il valore `--tool` — configura con l'installer, altrimenti — manualmente seguendo la guida.

### Con l'installer

Un solo comando, senza domande: la chiave dalla variabile d'ambiente, il modello tramite flag. L'installer scrive la configurazione dello strumento, conserva una copia della precedente e verifica la connessione con una richiesta al gateway.

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

| Flag | Cosa fa |
| --- | --- |
| `--tool <id>` | Quale strumento configurare — valore dalla tabella degli strumenti. |
| `--model <id>` | Identificatore del modello: consigliato — `MiniMaxAI/MiniMax-M2.7`, tutti i disponibili — `GET /v1/models`. |
| `--non-interactive` | Senza domande: la chiave viene presa da `JOINGONKA_API_KEY`. |
| `--scope local` | Configurazione nel progetto corrente, non nella home directory. Solo per Claude Code; il file di configurazione viene aggiunto a `.gitignore`. |
| `--no-verify` | Non verificare la connessione dopo aver scritto la configurazione. |

| Codice di uscita | Cosa significa |
| --- | --- |
| `0` | Fatto: configurazione scritta, richiesta di verifica riuscita. Se la verifica non è possibile per rete o saldo, l'installer stampa un avviso ma esce comunque con codice 0 — segnalalo all'utente. |
| `1` | Configurazione non riuscita, il motivo è nell'output: ad esempio valore `--tool` sconosciuto, `JOINGONKA_API_KEY` non impostata o chiave che non inizia con `jg-`. |
| `2` | Configurazione scritta, ma la richiesta di verifica non è riuscita: controlla la chiave e l'identificatore del modello. |

Se lo strumento era in esecuzione, riavvialo: la configurazione viene letta all'avvio.

### Manualmente

Per uno strumento senza installer, apri la sua guida (link nella tabella qui sotto) e imposta tre valori:

- indirizzo base — `https://gate.joingonka.ai/v1` per i client OpenAI API o `https://gate.joingonka.ai` per i client Anthropic API;
- chiave — nel campo della chiave API nelle impostazioni dello strumento;
- modello — `MiniMaxAI/MiniMax-M2.7` o un altro tra `GET /v1/models`.

### Strumenti e guide

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

## Verifica

Verifica della chiave — richiesta del saldo: non consuma token, la chiave viene presa da `JOINGONKA_API_KEY`:

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

Verifica di indirizzo, chiave e modello — una breve richiesta al modello:

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

Risposta `200` con il testo del modello — la connessione funziona. L'installer esegue questa verifica da solo: dopo di lui basta un codice di uscita 0.

## Se qualcosa non va

L'errore arriva nel campo `error` del corpo della risposta — con tipo e testo del motivo.

| Risposta | Cosa fare |
| --- | --- |
| `401 authentication_error` | Chiave non accettata. Controlla che sia stata copiata per intero e passata in `Authorization: Bearer` o `x-api-key`; una nuova chiave la crea l'utente. |
| `402 insufficient_funds` | Saldo a zero. Segnalalo all'utente: il saldo si ricarica nella dashboard. |
| `402 child_key_limit_exceeded` | Limite della chiave figlia esaurito. Serve un'altra chiave o un limite maggiore — decide il proprietario della chiave. |
| `403 forbidden` | Questa è la chiave di gestione `gm-`: non dà accesso ai modelli. Serve una chiave `jg-`. |
| `400 invalid_request_error` | Errore nella richiesta. Se il modello non è stato trovato, nel testo dell'errore c'è l'elenco degli identificatori disponibili — prendine uno da lì o da `GET /v1/models`. |
| `404 model_not_found` | Questo modello al momento non esiste — scegline un altro da `GET /v1/models`. |
| `429` | Troppe richieste o rete occupata. Attendi il numero di secondi indicato nell'header `Retry-After` e riprova. |
| `503 model_unavailable` | La rete al momento non serve questo modello. Passa a un modello indicato nel testo dell'errore o a un altro tra `GET /v1/models`. |
| `504 upstream_timeout` | La rete non ha iniziato a rispondere in tempo. Ripeti la richiesta; per risposte lunghe attiva `stream: true`. |
| `502` | Guasto lato gateway o rete — la chiave non c'entra. Riprova più tardi; lo stato della rete è nella pagina [Stato della rete](https://gate.joingonka.ai/it/status). |

Tutti i codici di risposta e i limiti sono nella sezione [Errori e limiti](https://gate.joingonka.ai/it/docs/errors).

## Report

Alla fine comunica all'utente:

- quale strumento è stato configurato e quale file di configurazione è stato scritto (il percorso lo stampa l'installer, la copia del precedente è accanto);
- indirizzo di base e identificatore del modello;
- esito della verifica: codice di risposta e risposta del modello — oppure perché non è stato possibile verificare;
- cosa resta da fare all'utente: ad esempio riavviare lo strumento o ricaricare il saldo.

Non includere la chiave nel report.

## Indirizzi macchina

| Indirizzo | Cosa contiene |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Indice della documentazione per i modelli linguistici. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Tutta la documentazione in un unico file. |
| `/docs/<page>.md` | Versione Markdown di una pagina di documentazione: lo stesso indirizzo con `.md` in coda ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) oppure una richiesta della pagina con l'header `Accept: text/markdown`. |
| `GET /v1/capabilities` | Funzionalità del gateway e relativi limiti — campo `limits`. |
| `GET /v1/models` | Modelli attualmente disponibili. |
| `GET /api/pricing` | Prezzi per modello ogni 1M token e commissioni. |
| `GET /v1/network-status` | Stato dei modelli e incidenti. |

## Skill per l'agente

Le istruzioni possono essere installate nell'agente come skill — così restano sempre a portata di mano, anche senza prompt:

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