Collega Zed a Claude tramite il gateway

Zed è veloce e il suo assistente è davvero utile, ma il modo in cui accetta un endpoint Claude personalizzato non si trova dove la maggior parte delle persone cerca inizialmente. Il provider Anthropic nativo non consente di personalizzare l'URL di base, quindi il percorso più semplice verso il gateway passa invece dal blocco openai_compatible di Zed.

Perché non usare il provider Anthropic

Zed include un provider Anthropic nativo e l'istinto è quello di indirizzarlo al gateway. Il problema è che questo provider non dispone di un'impostazione api_url, quindi non esiste un campo supportato con cui reindirizzarlo dall'host Anthropic predefinito.

Questa singola limitazione è il motivo per cui tante persone si bloccano. Anziché cercare di aggirarla, instrada Claude tramite il meccanismo generico openai_compatible, che espone l'URL di base ed è progettato proprio per gli endpoint di terze parti.

È utile pensare al provider nativo come vincolato a una sola destinazione e al provider openai_compatible come a quello configurabile. Per un gateway multimodello, il percorso configurabile è comunque quello più adatto, perché lo stesso blocco può dare accesso a Claude e a qualsiasi altro modello offerto dal gateway tramite un unico api_url. In questo modo tutta la configurazione dei modelli dell'editor rimane in un solo posto, anziché essere suddivisa tra due meccanismi di provider con regole diverse. Questa singola decisione determina il resto della configurazione, quindi conviene comprenderla prima di modificare qualsiasi cosa. Una volta accettato che il blocco openai_compatible è il percorso supportato, resta solo da compilare i campi.

Aggiungi un blocco openai_compatible

In settings.json, sotto language_models.openai_compatible, aggiungi un provider con un nome. Imposta il suo api_url sull'indirizzo del gateway con /v1 alla fine; Zed aggiunge /chat/completions a quel percorso, quindi a rispondere è l'interfaccia del gateway compatibile con OpenAI.

Il nome che scegli è arbitrario e diventa l'etichetta nel menu dei modelli di Zed. Un blocco può servire diversi modelli Claude, ciascuno dichiarato nel passaggio successivo.

Il suffisso /v1 è essenziale: Zed costruisce il percorso chat-completions direttamente sotto il valore fornito come api_url, quindi l'assenza di /v1 invia le richieste al percorso sbagliato e una barra finale può duplicare il percorso. Impostalo esattamente sull'host seguito da /v1 e l'instradamento funzionerà correttamente. Un rapido ricaricamento delle impostazioni dopo la modifica conferma che Zed ha interpretato il blocco senza errori. Se il provider non compare, la prima cosa da controllare è un errore di sintassi JSON nel blocco.

Dichiara available_models

Zed non rileva automaticamente i modelli su un endpoint personalizzato, quindi elencali manualmente in available_models. Ogni voce richiede un name corrispondente all'ID del gateway, un display_name per il menu e un valore max_tokens adeguato al modello.

Usa claude-sonnet-4-5 per l'assistenza quotidiana e aggiungi claude-opus-4-8 come seconda voce per le attività più complesse. Poiché li elenchi esplicitamente, il menu mostra esattamente l'insieme desiderato e nient'altro.

Il campo name deve corrispondere all'ID del gateway carattere per carattere, mentre display_name è puramente estetico e può apparire nel menu come preferisci. Un valore name errato è la causa più comune di un modello che compare ma restituisce errori quando viene usato, quindi copia l'ID direttamente dal gateway anziché digitarlo a memoria. Elencare solo i modelli che usi davvero mantiene il menu breve e rende immediata la scelta nel lavoro quotidiano. Aggiungere un modello in seguito richiede la modifica di una sola riga, quindi non è necessario dichiarare tutto fin dall'inizio.

Dove viene conservata la chiave

La chiave API non va in settings.json. Zed la memorizza nel portachiavi del sistema operativo o la legge da una variabile d'ambiente denominata in base al provider, come AIPRIME_API_KEY, mantenendo così il segreto fuori dalla configurazione sincronizzata.

Dopo aver salvato, apri l'assistente, scegli il provider dal menu e inserisci la chiave quando richiesto. Da quel momento Zed usa il portachiavi per l'autenticazione e il file delle impostazioni rimane privo di credenziali.

Questa separazione è davvero utile se sincronizzi le impostazioni di Zed tra più computer o le includi in un repository di dotfile: la configurazione può essere trasferita liberamente perché non contiene segreti e ogni computer fornisce la propria chiave tramite il portachiavi o l'ambiente. È una soluzione più pulita rispetto agli strumenti che incorporano la chiave nel file di configurazione. È anche il motivo per cui condividere una configurazione di Zed con un collega è sicuro: userà la propria chiave e la tua non verrà mai trasferita. Lo stesso vale per il commit delle impostazioni in un repository di dotfile.

Il percorso nativo tramite ACP

Se desideri specificamente il comportamento nativo di Anthropic anziché l'interfaccia compatibile con OpenAI, Zed supporta l'Agent Client Protocol con Claude Code. Esegui Claude Code come agente e Zed comunica con esso tramite ACP.

In questa configurazione, Claude Code dispone del proprio ANTHROPIC_BASE_URL indirizzato al gateway, quindi Zed non ha mai bisogno di un api_url Anthropic proprio. È il modo più semplice per ottenere il comportamento realmente nativo di Messages all'interno dell'editor.

Il compromesso è che ACP offre il ciclo operativo completo dell'agente di Claude Code anziché l'assistente integrato più leggero di Zed: è più potente, ma anche più impegnativo da usare. Scegli il percorso openai_compatible per un aiuto inline rapido e il percorso ACP quando vuoi un agente completo che gestisca modifiche in più passaggi dall'interno dell'editor. La maggior parte delle persone inizia con il percorso più leggero e adotta ACP solo quando desidera un agente completo nell'editor. Puoi mantenerli entrambi disponibili e usare quello più adatto all'attività.

// Zed settings.json
{
  "language_models": {
    "openai_compatible": {
      "aiprime": {
        "api_url": "https://aiprimetech.io/v1",
        "available_models": [
          { "name": "claude-sonnet-4-5",
            "display_name": "Claude Sonnet",
            "max_tokens": 200000 }
        ]
      }
    }
  }
}
// Key goes in the keychain / AIPRIME_API_KEY env var, NOT this file.

Domande frequenti

AI Prime Tech è un gateway API indipendente. Non è affiliato ad Anthropic, non è approvato da Anthropic e non è un suo rivenditore. Claude e i nomi dei modelli correlati sono marchi dei rispettivi proprietari.