Claude Code mit Third-Party-API verbinden: ANTHROPIC_BASE_URL einrichten und Fehler beheben

Standardmäßig sendet Claude Code jede Anfrage an die offizielle API von Anthropic. Wenn die offizielle Route aus Ihrem Netzwerk heraus instabil ist oder Sie Schlüssel, Abrechnung und Modellwechsel an einem zentralen Ort verwalten möchten, ist die Verbindung über einen Anthropic-kompatiblen Third-Party-Endpoint die direkteste Lösung. Diese Anleitung behandelt genau die Änderungen, die Verifikation und die Reihenfolge der Fehlersuche.

Zuerst verstehen: Claude Code ist ein Client

Definition: Claude Code liest eine kleine Gruppe von Umgebungsvariablen, um zu bestimmen, wohin Anfragen gehen, welcher Schlüssel verwendet wird und welches Modell läuft. Solange der Ziel-Endpoint das Request/Response-Format der Anthropic Messages API implementiert, funktioniert Claude Code damit genau wie mit der offiziellen API — Tool Calling, Streaming und Multi-Turn-Sessions hängen von der Kompatibilität des Endpoints ab.

Das Überschreiben der Base URL ist eine dokumentierte Funktion, kein Hack. EXAIV stellt einen Anthropic-kompatiblen Endpoint bereit; die Kurzversion dieser Anleitung finden Sie auf der offiziellen Setup-Seite.

Die entscheidenden Umgebungsvariablen

Methode 1: settings.json (empfohlen, dauerhaft)

Claude Code liest Umgebungsvariablen aus ~/.claude/settings.json. Dies gilt für alle Sessions und lässt sich leicht teamweit standardisieren. Beispiel für EXAIV:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://exaiv.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_EXAIV_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "model": "claude-opus-5-5"
}

Nach dem Speichern claude neu starten. Für die Beschränkung auf ein Projekt dieselbe Struktur in .claude/settings.json im Projektverzeichnis ablegen.

Methode 2: Temporäre Umgebungsvariablen (Schnelltest)

Ohne Dateiänderung — im aktuellen Shell exportieren:

export ANTHROPIC_BASE_URL="https://exaiv.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_EXAIV_API_KEY"

# Minimale Verifikation
claude --print "say hi"

Wenn eine Antwort kommt, ist der Endpoint aktiv. Für dauerhafte Nutzung können die beiden Exporte in ~/.zshrc oder ~/.bashrc — das betrifft aber jeden claude-Aufruf. Wenn Sie zusätzlich ein offizielles Abonnement haben, empfiehlt sich die project-level settings.json, um nicht versehentlich Third-Party-Credits zu verbrauchen.

Wo finde ich verfügbare Modelle

Der Endpoint bestimmt, welche Modelle existieren. Der vollständige EXAIV-Katalog (Claude, GPT, Gemini, DeepSeek, Kimi und weitere) steht auf der Modellseite; der Wechsel in Claude Code erfolgt über ANTHROPIC_MODEL oder den In-Session-Befehl /model.

Fehlerbehebung: in fester Reihenfolge prüfen

Teameinführung: eine Konfiguration, kein Drift

Die größte teamseitige Falle: jeder konfiguriert anders. Was funktioniert:

Ein settings-Template ins Repository. Eine schlüsselfreie .claude/settings.example.json im Projektverzeichnis; neue Mitglieder kopieren sie und tragen ihren eigenen Schlüssel ein. Fünf Minuten bis zur fertigen Einrichtung.

Schlüssel pro Person, niemals geteilt. Jedes Mitglied verwendet seinen eigenen API-Schlüssel mit sichtbarer Nutzung im Console. Probleme lassen sich klar zuordnen, und beim Ausscheiden genügt das Widerrufen eines einzigen Schlüssels.

Wrapper-Skript zur Kontexttrennung. Wenn Teammitglieder zusätzlich ein offizielles Abonnement haben, verweist ein kleines Alias-Skript auf die Projekt-Konfiguration — so vermischen sich offizielle und Third-Party-Quoten nicht.

Sicherheitsgrundlagen

Ein API-Schlüssel ist eine Wallet-Berechtigung. Vier Grundregeln:

• Schlüssel nie in git. Konfigurationsdateien mit echten Schlüsseln gehören außerhalb der Versionskontrolle; ins Repository gehört nur die schlüsselfreie Vorlage
• Regelmäßig rotieren. Schlüssel im Console periodisch neu generieren und alte widerrufen; bei Verdacht auf Leck sofort wechseln
• Minimale Berechtigung. Keine Schlüssel in CI-Logs, Frontend-Code oder Chat-Nachrichten hinterlassen
• Anomalien beobachten. Weicht die Verbrauchsrate deutlich vom Üblichen ab, zuerst den Schlüssel widerrufen, dann untersuchen

Eine zusätzliche Prüfung, die Zeit spart: den Endpoint zuerst mit bare curl testen — ohne Claude Code, ohne SDK. Wenn curl antwortet, verengt sich das Problem auf die Client-Konfiguration. Wenn nicht, liegen Schlüssel oder Netzwerk dahinter. Diese eine Minute Test erspart Stunden des Ratens.

Kurzreferenz nach Betriebssystem

Alles Weitere — Modell-Zuordnung, Reihenfolge der Fehlersuche, Sicherheitspraktiken — ist plattformübergreifend identisch.

Warum die Tier-Zuordnung wichtiger ist, als man denkt

Claude Code ruft nicht nur das gewählte Hauptmodell auf. Im Hintergrund feuert es viele kleine Anfragen — Zusammenfassung von Tool-Ergebnissen, Commit-Messages, schnelle Nachschlageabfragen — und diese Anfragen sind als Sonnet- oder Haiku-Tier markiert. Wenn Ihr Endpoint nicht das genaue Standardmodell für diese Tiers bereitstellt, schlagen die Aufrufe fehl oder fallen unvorhersehbar zurück.

Genau das lösen ANTHROPIC_DEFAULT_SONNET_MODEL und ANTHROPIC_DEFAULT_HAIKU_MODEL: Sie leiten tier-markierte Anfragen an ein Modell um, das Ihr Endpoint tatsächlich bedient. Das einfachste und stabilste Muster: beide auf dasselbe Hauptmodell setzen. Das Abbilden des Haiku-Tiers auf ein günstigeres Modell ist eine übliche Optimierung, sobald alles stabil läuft. Dieselbe Logik gilt im Gateway: auf der Modellseite prüfen, was existiert, und die Tiers auf Modelle mappen, die sicher vorhanden sind.

Timeout und Netzwerk-Feintuning

Zwei Variablen lösen fast alle Konnektivitätsbeschwerden:

• API_TIMEOUT_MS — komplexe Agent-Turns können legitim Minuten dauern; ein zu kurzer Client-Timeout tötet Anfragen, die eigentlich erfolgreich wären. Wenn Turns ohne Fehlermeldung abgeschnitten werden, diesen Wert erhöhen.
• Proxy-Überlappung — wenn die Shell auch HTTP_PROXY/HTTPS_PROXY setzt, umlaufen Anfragen möglicherweise über einen lokalen Proxy, bevor sie den Gateway erreichen. Wenn die Base URL korrekt ist aber die Verbindung trotzdem scheitert, mit deaktivierten Proxy-Variablen testen, bevor etwas anderes geändert wird.

Beide sind standardmäßig nicht erforderlich — es sind die ersten beiden Stellschrauben, wenn die Konfiguration stimmt aber der Netzwerkweg falsch ist.

Warum ein Gateway die richtige Wahl ist

Zusammengefasst die Vorteile, die diesen Leitfaden motiviert haben: ein Schlüssel für alle Modelle statt separater Konten pro Anbieter; einheitliche Abrechnung über ein Credits-Guthaben statt separater Rechnungen; der Modellwechsel per Konfigurationsänderung ohne neue Registrierung; und die Anthropic-kompatible Schnittstelle, die Claude Code ohne Anpassungen versteht.

Der Einstieg ist bewusst niedrigschwellig gehalten: Der günstigste Credit-Pack reicht für einen vollständigen Verifizierungszyklus aus. Wer nach dem Test auf ein größeres Paket aufrüstet, behält dieselbe Konfiguration bei — nur der Tarif ändert sich. Und weil alle Modelle denselben Endpoint teilen, ist der Wechsel zwischen Modellen innerhalb einer Sitzung eine Ein-Zeilen-Änderung.

FAQ

Weiterführende Links

• Claude Code Setup-Seite — die Kurzfassung auf der Website
• Anthropic Messages API Referenz — Request/Response-Format
• Preise — Live-Modellpreise