Takeover con un clic degli strumenti di programmazione AI
Il takeover con un clic ti permette di indirizzare i tuoi strumenti CLI di programmazione AI più usati verso il gateway AI locale senza modificare manualmente alcun file di configurazione. Dopo il takeover, le richieste di questi strumenti vengono instradate tramite http://127.0.0.1:11580 verso i canali dei fornitori configurati nel gateway e vengono incluse nelle statistiche unificate di utilizzo e costi.
Come funziona
Quando esegui il takeover con un clic su uno strumento, il gateway completa in sequenza:
- Verifica lo stato di salute del gateway, confermando che l'endpoint del proxy sia disponibile.
- Crea automaticamente una chiave virtuale dedicata (il gateway la scrive nella configurazione dello strumento; il testo in chiaro può essere recuperato in qualsiasi momento dalla pagina delle chiavi).
- Esegue il backup del file di configurazione originale con il suffisso
.bak(ad esempio~/.claude/settings.json.bak). - Scrive con precisione / esegue un'unione profonda della configurazione che punta al gateway, mantenendo invariate le altre impostazioni.
- Aggiorna lo stato dell'interfaccia, mostrando la situazione attuale del takeover.
Anche l'interruzione del takeover è una "rimozione precisa": le chiavi corrispondenti vengono rimosse solo quando la configurazione punta effettivamente a questo gateway, evitando di eliminare per errore altre impostazioni configurate manualmente; contemporaneamente viene revocata la chiave virtuale creata automaticamente durante il takeover.
Stato del takeover
Ogni strumento nella pagina Gateway AI → Gestione integrazioni → Client mostra uno dei quattro stati seguenti:
| Stato | Significato |
|---|---|
| Takeover attivo (questo gateway) | Lo strumento punta al gateway AI locale |
| Connesso (altro indirizzo) | Lo strumento è configurato con un altro indirizzo (configurato manualmente o che punta a un altro gateway); il gateway non lo sovrascriverà arbitrariamente |
| Takeover non attivo | Lo strumento è stato rilevato, ma non punta ancora al gateway |
| Non rilevato | La directory di configurazione dello strumento non è stata trovata su questa macchina |
Prerequisiti
- Hai effettuato l'accesso all'account ServBay e hai configurato almeno un canale disponibile nella pagina Canali.
- Lo strumento AI di destinazione è installato su questa macchina (il gateway ne determina l'esistenza in base alla sua directory di configurazione).
Operazione di takeover con un clic
Vai alla pagina Gateway AI → Gestione integrazioni → Client, trova lo strumento di destinazione nell'elenco e clicca su Takeover con un clic. Dopo il successo, lo stato diventa "Takeover attivo (questo gateway)". Per annullare, clicca su Interrompi takeover.
Dettagli del takeover per ciascuno strumento
La tabella seguente elenca i file di configurazione e i contenuti effettivamente modificati quando ciascuno strumento viene preso in carico, per aiutarti a comprenderli e a risolvere eventuali problemi:
| Strumento | File di configurazione | Contenuto scritto | Indirizzo del gateway |
|---|---|---|---|
| Claude Code | ~/.claude/settings.json | env.ANTHROPIC_BASE_URL + env.ANTHROPIC_AUTH_TOKEN | http://127.0.0.1:11580 (senza /v1) |
| Codex | ~/.codex/config.toml | Sezione [model_providers.servbay] + model_provider = "servbay" di primo livello | http://127.0.0.1:11580/v1 |
| Qwen Code | ~/.qwen/.env | OPENAI_BASE_URL + OPENAI_API_KEY (compatibile con OpenAI) | http://127.0.0.1:11580/v1 |
| Kimi CLI | ~/.kimi/config.toml | Sezione [model_providers.servbay] + definizione del modello | http://127.0.0.1:11580/v1 |
| CodeBuddy | ~/.codebuddy/models.json | Unione profonda del nodo modello servbay | http://127.0.0.1:11580/v1 |
| opencode | ~/.config/opencode/opencode.json | Unione profonda del nodo provider.servbay (aggrega i modelli di ciascun canale) | http://127.0.0.1:11580/v1 |
| Crush | ~/.config/crush/crush.json | Unione profonda del nodo providers.servbay | http://127.0.0.1:11580/v1 |
Perché l'indirizzo di Claude Code non include /v1
Claude Code utilizza il protocollo Anthropic; il gateway compone autonomamente percorsi come /v1/messages, quindi ANTHROPIC_BASE_URL deve essere l'indirizzo radice del gateway (senza /v1). La maggior parte degli altri strumenti segue il protocollo compatibile con OpenAI e richiede il suffisso /v1. Il takeover con un clic compilerà automaticamente i valori in base alle convenzioni di ciascuno strumento, senza che tu debba distinguerli manualmente.
Ripristino e risoluzione dei problemi
- Ripristino della configurazione originale — Clicca su Rimuovi e il gateway rimuoverà con precisione la configurazione che punta a questo gateway. Puoi anche ripristinare manualmente utilizzando il file di backup
.baknella stessa directory. - Lo stato mostra "Connesso (altro indirizzo)" — Indica che lo strumento attualmente punta a un altro indirizzo (configurato manualmente o che punta a un altro gateway). Per evitare di sovrascrivere le tue impostazioni, il gateway non eseguirà il takeover automaticamente; puoi prima ripulire manualmente quella configurazione e poi eseguire il takeover.
- Lo strumento continua a restituire errori dopo il takeover — Verifica che il servizio proxy del gateway sia in esecuzione, che il canale corrispondente sia integro e che la chiave virtuale non sia stata revocata; puoi anche controllare nella pagina Statistiche e monitoraggio se le richieste raggiungono il gateway.
Domande frequenti (FAQ)
- D: Il takeover con un clic danneggerà la mia configurazione originale dello strumento?
- R: No. Il gateway scrive / unisce con precisione solo le chiavi relative al gateway ed esegue il backup del file originale come
.bakprima di scrivere. Le altre impostazioni rimangono invariate.
- R: No. Il gateway scrive / unisce con precisione solo le chiavi relative al gateway ed esegue il backup del file originale come
- D: Dopo il takeover posso ancora ripristinare manualmente?
- R: Sì. Clicca su "Rimuovi" per annullare tramite il gateway, oppure ripristina manualmente utilizzando il backup
.bak.
- R: Sì. Clicca su "Rimuovi" per annullare tramite il gateway, oppure ripristina manualmente utilizzando il backup
- D: Dove si trova la chiave virtuale utilizzata per il takeover?
- R: Il gateway crea automaticamente una chiave virtuale dedicata per ogni strumento preso in carico; puoi visualizzarla e gestirla nella pagina Chiavi.
- D: Nell'elenco lo strumento mostra "Non rilevato"?
- R: Significa che la directory di configurazione dello strumento non è stata trovata su questa macchina. Installa ed esegui una volta lo strumento per generare la directory di configurazione, quindi esegui il takeover.
Riepilogo
Il takeover con un clic semplifica l'operazione noiosa e soggetta a errori di "modificare manualmente i file di configurazione di ciascuno strumento" riducendola a un solo clic: creazione automatica della chiave, backup automatico, scrittura precisa, ripristino in qualsiasi momento. Grazie ai canali unificati e alle statistiche di utilizzo, puoi far condividere a tutti i tuoi strumenti di programmazione AI la stessa configurazione dei fornitori e la stessa visualizzazione dei costi. Se desideri chiamare il gateway dal tuo codice, consulta Endpoint e variabili d'ambiente.
