Takeover one-click per gli strumenti di programmazione AI

La funzione Takeover one-click ti consente di puntare facilmente i tool CLI di programmazione AI più diffusi verso il gateway AI locale senza dover modificare manualmente alcun file di configurazione. Dopo il takeover, tutte le richieste di questi strumenti saranno instradate in modo centralizzato all'indirizzo http://127.0.0.1:11580 e quindi dirette ai fornitori configurati tramite il gateway, permettendone monitoraggio e gestione unificata di consumi e costi.

Come funziona

Quando esegui il takeover one-click per ogni strumento, il gateway esegue questi passaggi:

1. Controlla lo stato di salute del gateway per assicurarsi che l'endpoint proxy sia disponibile.
2. Crea automaticamente una chiave virtuale dedicata (la chiave è mostrata solo durante la creazione; il gateway la scrive direttamente nella configurazione dello strumento).
3. Effettua il backup del file di configurazione originale, aggiungendo l'estensione .bak (es: ~/.claude/settings.json.bak).
4. Scrive/merge con precisione nella configurazione solo i parametri necessari per puntare al gateway, lasciando inalterate le altre impostazioni.
5. Aggiorna lo stato nell'interfaccia, mostrando la situazione di takeover attuale.

Anche la rimozione del takeover avviene in modo preciso: le modifiche vengono annullate solo se la configurazione punta realmente al gateway locale, evitando la cancellazione accidentale di altre impostazioni personalizzate.

Stato del takeover

Per ogni strumento, nella sezione AI Gateway → Endpoints vengono mostrate una delle quattro possibili condizioni:

Stato	Significato
Takeover attivo (gateway locale)	Lo strumento punta al gateway AI locale
Collegato (altri indirizzi)	Lo strumento usa un altro indirizzo configurato manualmente o di un altro gateway. Il gateway ServBay non sovrascriverà questa impostazione.
Takeover non attivo	Lo strumento è rilevato ma non instradato tramite il gateway
Non rilevato	La directory di configurazione dello strumento non è stata trovata sulla macchina

Prerequisiti

• Devi aver effettuato l'accesso al tuo account ServBay e aver configurato almeno un canale attivo nella sezione Canali.
• Lo strumento AI target deve essere installato sulla macchina locale (il gateway lo rileva tramite la presenza della directory di configurazione).

Come attivare il takeover

Vai su AI Gateway → Endpoints, trova lo strumento desiderato nella lista e clicca su Takeover one-click. Se il processo va a buon fine, lo stato si aggiornerà a "Takeover attivo (gateway locale)". Per disattivare, clicca su Rimuovi / Ripristina.

Dettagli di takeover per ciascuno strumento

La tabella seguente mostra quali file e contenuti vengono modificati per ogni tool durante il takeover; questo ti aiuta a comprendere e diagnosticare i cambiamenti:

Strumento	File di configurazione	Voci modificate	Gateway address
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] + chiave model_provider = "servbay"	http://127.0.0.1:11580/v1
Gemini CLI	~/.gemini/.env	Linee GOOGLE_GEMINI_BASE_URL + GEMINI_API_KEY	http://127.0.0.1:11580
Qwen Code	~/.qwen/.env	OPENAI_BASE_URL + OPENAI_API_KEY (compatibile OpenAI)	http://127.0.0.1:11580/v1
Kimi CLI	~/.kimi/config.toml	Sezione [model_providers.servbay] + definizione modello	http://127.0.0.1:11580/v1
CodeBuddy	~/.codebuddy/models.json	Merge profondo del nodo modello servbay	http://127.0.0.1:11580/v1
opencode	~/.config/opencode/opencode.json	Merge profondo del nodo provider.servbay (aggregazione modelli da tutti i canali)	http://127.0.0.1:11580/v1
Crush	~/.config/crush/crush.json	Merge profondo del nodo providers.servbay	http://127.0.0.1:11580/v1

Perché l'indirizzo di Claude Code non include /v1

Claude Code si basa sul protocollo Anthropic e il gateway aggiunge automaticamente percorsi come /v1/messages, quindi ANTHROPIC_BASE_URL deve essere l’indirizzo base del gateway (senza /v1). La maggior parte degli altri strumenti invece utilizza il protocollo compatibile OpenAI e richiede l’estensione /v1. Takeover one-click inserisce l’indirizzo corretto per ogni strumento in automatico, non serve distinguere a mano.

Ripristino e troubleshooting

• Ripristina la configurazione originale — Clicca su Rimuovi per annullare solo le modifiche legate al gateway locale. In alternativa, puoi ripristinare manualmente dalla copia .bak nella stessa directory.
• Lo stato mostra "Collegato (altri indirizzi)" — Significa che lo strumento sta usando attualmente un altro indirizzo configurato manualmente o puntato a un altro gateway. Per prevenire sovrapposizioni, ServBay non attiva takeover automaticamente; cancella prima l’indirizzo manualmente, poi procedi con takeover.
• Lo strumento dà errore dopo il takeover — Controlla che il proxy del gateway sia attivo, che i canali siano operativi e che la chiave virtuale non sia stata revocata. Puoi anche verificare se le richieste arrivano al gateway tramite la pagina Statistiche e Monitoraggio.

Domande Frequenti (FAQ)

• D: Il takeover andrà a modificare o compromettere la mia vecchia configurazione dello strumento?
  • R: No. Il gateway scrive/merge solo le chiavi strettamente collegate al gateway stesso, mantenendo intatte tutte le altre impostazioni. Prima di ogni modifica viene inoltre creato un backup .bak.
• D: Posso tornare indietro e modificare la configurazione manualmente dopo takeover?
  • R: Sì, puoi. Basta cliccare su “Rimuovi” per annullare takeover, oppure ripristinare il file .bak manualmente.
• D: Dove viene salvata la chiave virtuale usata per takeover?
  • R: Per ogni strumento soggetto a takeover, il gateway genera una chiave virtuale dedicata visualizzabile e gestibile nella sezione Chiavi.
• D: Perché alcuni strumenti risultano "Non rilevati"?
  • R: Vuol dire che il relativo percorso di configurazione non è stato trovato sulla macchina. Installa e avvia lo strumento almeno una volta perché venga creato, poi procedi con takeover.

Conclusioni

Takeover one-click trasforma una procedura laboriosa e soggetta a errori — la modifica manuale dei file di configurazione di ogni tool — in una semplice operazione a portata di clic: creazione automatica delle chiavi, backup, modifica mirata, ripristino immediato. Integrando strumenti con statistiche e gestione centralizzata, puoi configurare tutti i tool di programmazione AI dell’ambiente per utilizzare gli stessi canali e controllare facilmente consumi e costi. Per integrare il gateway nelle tue applicazioni, consulta Endpoints e variabili d’ambiente.