Wenn Sie Google Cloud-Anmeldedaten haben und Claude Code über Vertex AI verwenden möchten, führt Sie der Anmeldeasistent durch den Prozess. Sie führen die GCP-seitigen Voraussetzungen einmal pro Projekt durch; der Assistent kümmert sich um die Claude Code-Seite.
1
Aktivieren Sie Claude-Modelle in Ihrem GCP-Projekt
Führen Sie claude aus. Wählen Sie bei der Anmeldeeingabeaufforderung 3rd-party platform und dann Google Vertex AI.
3
Folgen Sie den Eingabeaufforderungen des Assistenten
Wählen Sie, wie Sie sich bei Google Cloud authentifizieren: Application Default Credentials von gcloud, eine Service-Account-Schlüsseldatei oder Anmeldedaten, die bereits in Ihrer Umgebung vorhanden sind. Der Assistent erkennt Ihr Projekt und Ihre Region, überprüft, welche Claude-Modelle Ihr Projekt aufrufen kann, und ermöglicht es Ihnen, diese zu fixieren. Das Ergebnis wird im env-Block Ihrer Benutzereinstellungsdatei gespeichert, sodass Sie Umgebungsvariablen nicht selbst exportieren müssen.
Nachdem Sie sich angemeldet haben, führen Sie /setup-vertex jederzeit aus, um den Assistenten erneut zu öffnen und Ihre Anmeldedaten, Ihr Projekt, Ihre Region oder Ihre Modellpins zu ändern.
Regionskonfiguration
Claude Code unterstützt Vertex AI globale, Multi-Region- und regionale Endpunkte. Legen Sie CLOUD_ML_REGION auf global, einen Multi-Region-Standort wie eu oder us oder eine bestimmte Region wie us-east5 fest. Claude Code wählt den korrekten Vertex AI-Hostnamen für jedes Formular aus, einschließlich der Hosts aiplatform.eu.rep.googleapis.com und aiplatform.us.rep.googleapis.com für Multi-Region-Standorte.
Manuelles Setup
Um Vertex AI über Umgebungsvariablen statt über den Assistenten zu konfigurieren, z. B. in CI oder einem skriptgesteuerten Enterprise-Rollout, folgen Sie den folgenden Schritten.
1. Aktivieren Sie die Vertex AI API
Aktivieren Sie die Vertex AI API in Ihrem GCP-Projekt:
# Legen Sie Ihre Projekt-ID fest
gcloud config set project YOUR-PROJECT-ID# Aktivieren Sie die Vertex AI API
gcloud services enable aiplatform.googleapis.com
2. Fordern Sie Modellzugriff an
Fordern Sie Zugriff auf Claude-Modelle in Vertex AI an:
Claude Code v2.1.121 oder später unterstützt X.509-zertifikatbasierte Workload Identity Federation über die gleiche Application Default Credentials-Kette. Legen Sie GOOGLE_APPLICATION_CREDENTIALS auf den Pfad Ihrer Anmeldedaten-Konfigurationsdatei fest.
Erweiterte Anmeldedaten-Konfiguration
Claude Code unterstützt die automatische Aktualisierung von Anmeldedaten für GCP über die Einstellung gcpAuthRefresh. Wenn Claude Code erkennt, dass Ihre GCP-Anmeldedaten abgelaufen sind oder nicht geladen werden können, führt es den konfigurierten Befehl aus, um neue Anmeldedaten zu erhalten, bevor die Anfrage erneut versucht wird.
Die Ausgabe des Befehls wird dem Benutzer angezeigt, aber interaktive Eingaben werden nicht unterstützt. Dies funktioniert gut für browserbasierte Authentifizierungsabläufe, bei denen die CLI eine URL anzeigt und Sie die Authentifizierung im Browser abschließen. Der Aktualisierungsbefehl läuft nach drei Minuten ab, wenn die Authentifizierung nicht abgeschlossen ist. Wenn Sie gcpAuthRefresh in Projekteinstellungen wie .claude/settings.json festlegen, wird der Befehl nur ausgeführt, nachdem Sie die Workspace-Vertrauensaufforderung akzeptiert haben.
4. Konfigurieren Sie Claude Code
Legen Sie die folgenden Umgebungsvariablen fest:
# Aktivieren Sie die Vertex AI-Integrationexport CLAUDE_CODE_USE_VERTEX=1export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID# Optional: Überschreiben Sie die Vertex-Endpunkt-URL für benutzerdefinierte Endpunkte oder Gateways# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com# Optional: Deaktivieren Sie Prompt Caching bei Bedarfexport DISABLE_PROMPT_CACHING=1# Optional: Fordern Sie eine 1-Stunden-Prompt-Cache-TTL statt des 5-Minuten-Standards anexport ENABLE_PROMPT_CACHING_1H=1# Wenn CLOUD_ML_REGION=global, überschreiben Sie die Region für Modelle, die keine globalen Endpunkte unterstützenexport VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
Die meisten Modellversionen haben eine entsprechende VERTEX_REGION_CLAUDE_*-Variable. Siehe die Referenz für Umgebungsvariablen für die vollständige Liste. Überprüfen Sie Vertex Model Garden, um zu bestimmen, welche Modelle globale Endpunkte versus nur regionale Endpunkte unterstützen.
Prompt Caching wird automatisch aktiviert. Um es zu deaktivieren, legen Sie DISABLE_PROMPT_CACHING=1 fest. Um eine 1-Stunden-Cache-TTL statt des 5-Minuten-Standards anzufordern, legen Sie ENABLE_PROMPT_CACHING_1H=1 fest; Cache-Schreibvorgänge mit einer 1-Stunden-TTL werden mit einem höheren Satz abgerechnet. Für erhöhte Ratenlimits wenden Sie sich an den Google Cloud-Support. Bei Verwendung von Vertex AI ist der Befehl /logout nicht verfügbar, da die Authentifizierung über Google Cloud-Anmeldedaten erfolgt.
Claude Code deaktiviert MCP-Toolsuche standardmäßig auf Vertex AI, sodass MCP-Tool-Definitionen beim Start geladen werden. Vertex AI unterstützt Toolsuche für Claude Sonnet 4.5 und später sowie Claude Opus 4.5 und später. Legen Sie ENABLE_TOOL_SEARCH=true fest, um sie auf diesen Modellen zu aktivieren. Frühere Modelle auf Vertex AI akzeptieren den erforderlichen Beta-Header nicht, und Anfragen schlagen fehl, wenn Sie die Toolsuche mit ihnen aktivieren.
5. Fixieren Sie Modellversionen
Legen Sie diese Umgebungsvariablen auf spezifische Vertex AI-Modell-IDs fest.
Ohne ANTHROPIC_DEFAULT_OPUS_MODEL wird der opus-Alias auf Vertex zu Opus 4.6 aufgelöst. Legen Sie ihn auf die Opus 4.8-ID fest, um das neueste Modell zu verwenden:
Aktuelle und ältere Modell-IDs finden Sie unter Modellübersicht. Siehe Modellkonfiguration für die vollständige Liste der Umgebungsvariablen.
Claude Code verwendet diese Standardmodelle, wenn keine Fixierungsvariablen gesetzt sind:
Modelltyp
Standardwert
Primäres Modell
claude-sonnet-4-5@20250929
Kleines/schnelles Modell
Gleich wie primäres Modell
Hintergrundaufgaben wie die Generierung von Sitzungstiteln verwenden das kleine/schnelle Modell, normalerweise ein Haiku-Klasse-Modell. Auf Vertex AI setzt Claude Code dies standardmäßig auf das primäre Modell, da Haiku möglicherweise nicht in jedem Projekt oder jeder Region aktiviert ist. Um Haiku für Hintergrundaufgaben zu verwenden, legen Sie ANTHROPIC_DEFAULT_HAIKU_MODEL auf eine Modell-ID fest, die in Ihrem Projekt verfügbar ist.
Wenn Claude Code mit konfiguriertem Vertex AI startet, überprüft es, dass die Modelle, die es verwenden möchte, in Ihrem Projekt zugänglich sind. Diese Prüfung erfordert Claude Code v2.1.98 oder später.
Wenn Sie eine Modellversion fixiert haben, die älter als der aktuelle Claude Code-Standard ist, und Ihr Projekt die neuere Version aufrufen kann, fordert Claude Code Sie auf, die Fixierung zu aktualisieren. Das Akzeptieren schreibt die neue Modell-ID in Ihre Benutzereinstellungsdatei und startet Claude Code neu. Das Ablehnen wird bis zur nächsten Standardversionänderung beibehalten.
Wenn Sie ein Modell nicht fixiert haben und der aktuelle Standard in Ihrem Projekt nicht verfügbar ist, fällt Claude Code für die aktuelle Sitzung zur vorherigen Version zurück und zeigt einen Hinweis an. Das Fallback wird nicht beibehalten. Aktivieren Sie das neuere Modell im Model Garden oder fixieren Sie eine Version, um die Auswahl dauerhaft zu machen.
IAM-Konfiguration
Weisen Sie die erforderlichen IAM-Berechtigungen zu:
Die Rolle roles/aiplatform.user umfasst die erforderlichen Berechtigungen:
aiplatform.endpoints.predict - Erforderlich für Modellaufrufe und Token-Zählung
Für restriktivere Berechtigungen erstellen Sie eine benutzerdefinierte Rolle nur mit den oben genannten Berechtigungen.
Claude Sonnet 5, Opus 4.6 und später sowie Sonnet 4.6 unterstützen das 1M-Token-Kontextfenster auf Vertex AI. Sonnet 5 läuft immer mit dem 1M-Fenster, ohne dass eine [1m]-Variante zum Auswählen vorhanden ist. Bei den anderen Modellen aktiviert Claude Code automatisch das erweiterte Kontextfenster, wenn Sie eine 1M-Modellvariante auswählen.
Überprüfen Sie aktuelle Kontingente oder fordern Sie eine Kontingenterhöhung über die Cloud Console an
Wenn Sie auf Fehler „Modell nicht gefunden" 404 stoßen:
Bestätigen Sie, dass das Modell im Model Garden aktiviert ist
Überprüfen Sie, dass das Modell am angegebenen Standort verfügbar ist. Einige Modelle werden nur auf global oder Multi-Region-Standorten wie eu und us angeboten, nicht in spezifischen Regionen
Wenn Sie CLOUD_ML_REGION=global verwenden, überprüfen Sie, dass Ihre Modelle globale Endpunkte im Model Garden unter „Unterstützte Funktionen" unterstützen. Für Modelle, die globale Endpunkte nicht unterstützen, können Sie entweder:
Ein unterstütztes Modell über ANTHROPIC_MODEL oder ANTHROPIC_DEFAULT_HAIKU_MODEL angeben, oder
Einen regionalen oder Multi-Region-Standort mit VERTEX_REGION_<MODEL_NAME>-Umgebungsvariablen festlegen
Wenn Sie auf 429-Fehler stoßen:
Stellen Sie für regionale Endpunkte sicher, dass das primäre Modell und das kleine/schnelle Modell in Ihrer ausgewählten Region unterstützt werden
Erwägen Sie, zu CLOUD_ML_REGION=global zu wechseln, um bessere Verfügbarkeit zu erreichen
293Claude Opus 4.6 und später sowie Sonnet 4.6 unterstützen das [1M-Token-Kontextfenster](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) auf Vertex AI. ClaudeCode aktiviert automatisch das erweiterte Kontextfenster, wenn Sie eine 1M-Modellvariante auswählen.293Claude Sonnet 5, Opus 4.6 und später sowie Sonnet 4.6 unterstützen das [1M-Token-Kontextfenster](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) auf Vertex AI. Sonnet5läuft immer mit dem 1M-Fenster, ohne dass eine `[1m]`-Variante zum Auswählen vorhanden ist. Bei den anderen Modellen aktiviert Claude Code automatisch das erweiterte Kontextfenster, wenn Sie eine 1M-Modellvariante auswählen.
294294
295Der [Setup-Assistent](#sign-in-with-vertex-ai) bietet eine 1M-Kontextoption an, wenn er Modelle fixiert. Um es stattdessen für ein manuell fixiertes Modell zu aktivieren, hängen Sie `[1m]` an die Modell-ID an. Siehe [Modelle für Drittanbieter-Bereitstellungen fixieren](/de/model-config#pin-models-for-third-party-deployments) für Details.295Der [Setup-Assistent](#sign-in-with-vertex-ai) bietet eine 1M-Kontextoption an, wenn er Modelle fixiert. Um es stattdessen für ein manuell fixiertes Modell zu aktivieren, hängen Sie `[1m]` an die Modell-ID an. Siehe [Modelle für Drittanbieter-Bereitstellungen fixieren](/de/model-config#pin-models-for-third-party-deployments) für Details.
