Der API-Key von Claude Code ist mehr als eine Zeichenkette: Er bestimmt, unter welcher Identität Anfragen abgerechnet werden, welche Modelle erreichbar sind und wie groß der Schaden bei einer Offenlegung ist. Die meisten 401-Fehler entstehen nicht durch einen ungültigen Key, sondern durch Variablennamen, Request-Header oder die Konfigurationsebene.
Dieser Artikel folgt dem Ablauf „Authentifizierungskette, Key anlegen, Umgebungsvariablen und Konfigurationsdatei, mehrere Konfigurationen, Rotation, Leak-Schutz, CI und Team, 401-Diagnose“ und liefert eine direkt umsetzbare Methode. Konkrete Variablennamen und Einstellungen richten sich nach der aktuellen Claude-Code-Version und der Gateway-Dokumentation.
Hinweis: Claude und Anthropic sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient der technischen Erläuterung; es besteht keine Zugehörigkeit zu den Herstellern. Schnittstellen, Berechtigungen und Preise richten sich nach der offiziellen Dokumentation der Plattformen und den Seiten auf dieser Website.
1. Zuerst die Authentifizierungskette von Claude Code verstehen
Beim Start sendet Claude Code Anfragen an ANTHROPIC_BASE_URL und fügt Authentifizierungsinformationen hinzu. Diese stammen üblicherweise aus einer von zwei Variablen:
ANTHROPIC_AUTH_TOKEN: wird alsAuthorization: Bearergesendet, üblich bei Gateway-Anbindung.ANTHROPIC_API_KEY: wird alsx-api-keygesendet und entspricht dem nativen Anthropic-Weg.
Das Gateway sucht anhand des Keys das zugehörige Konto und prüft Guthaben, Kontingent, Modellberechtigungen und Gültigkeit. Scheitert eine dieser Prüfungen, kann das als 401, 403 oder 429 erscheinen. Versteifen Sie sich bei der Diagnose daher nicht auf die Key-Zeichenkette.
Ein weiteres häufiges Missverständnis ist die Bindung eines Keys an ein Modell. Der Key ist die Identität, das Modell ein Anfrageparameter; derselbe Key kann meist mehrere Modelle aufrufen, abhängig von Kontorechten und Gateway-Richtlinie.
2. Key anlegen: fünf Schritte
- Öffnen Sie das ZSQH AI Gateway oder die von Ihnen genutzte Plattform, registrieren Sie sich und melden Sie sich in der Konsole an.
- Gehen Sie zur Seite „API-Keys“ und legen Sie einen neuen Key an. Der Name sollte Umgebung und Zweck erkennen lassen, etwa
claude-code-work-mac. - Legen Sie Obergrenze und Ablaufdatum fest. Für Test-Keys zunächst ein niedriges Limit; nach Feststellung des echten Verbrauchs anpassen.
- Unterstützt die Plattform Modell-Allowlists oder Projektbereiche, wählen Sie nur die für Claude Code nötigen Modelle.
- Kopieren Sie den vollständigen Key und legen Sie ihn sofort in einem Passwortmanager oder Secrets-Dienst ab. Viele Konsolen zeigen den vollständigen Wert nur einmal.
Keys beginnen oft mit sk-, aber das Präfix beweist weder Echtheit noch Berechtigungen. Achten Sie beim Kopieren auf Leerzeichen und Zeilenumbrüche am Anfang und Ende; sie sind eine häufige 401-Ursache.
Validieren Sie den Key nach dem Anlegen zunächst mit einem minimalen curl-Aufruf, bevor Sie ihn an Teammitglieder verteilen. Die Methode steht im Abschnitt „401-Diagnose“.
3. Umgebungsvariablen oder Konfigurationsdatei: die Wahl
| Methode | Geeignet für | Vorteile | Beachten |
|---|---|---|---|
| Shell-Umgebungsvariablen | Persönliche Entwicklungsrechner, temporäres Umschalten | Nichts landet im Projekt, leicht umschaltbar | Neue Terminals oder IDEs lesen sie eventuell nicht |
| Benutzerweite settings.json | Dauerhafte persönliche Nutzung | Einmal konfigurieren, global gültig | Key liegt im Klartext |
| Projektspezifische settings.local.json | Überschreibung für ein Projekt | Andere Projekte unberührt, gitignore möglich | Auf neuem Rechner neu konfigurieren |
| apiKeyHelper oder Secrets-Dienst | Teams, geteilte Rechner, Compliance | Key steht nicht direkt in der Konfiguration | Zusätzliche Skripte und Rechteverwaltung nötig |
| CI-Secret-Variablen | Automatisierte Pipelines | Vom Code getrennt, auditierbar | Log-Maskierung und Branch-Rechte beachten |
Umgebungsvariablen passen zu „ich möchte es jetzt testen“; settings.json zu „dieser Rechner soll dauerhaft so arbeiten“; Secrets-Management zu „der Key darf nicht im Klartext auf der Platte liegen“. Die Methoden lassen sich kombinieren, aber Sie müssen wissen, was was überschreibt. Die Priorität in Claude Code verläuft grob: Unternehmenskonfiguration, Kommandozeilenparameter, lokales Projekt, Projekt, Benutzer. Zwischen Versionen kann sich das leicht ändern; maßgeblich ist die offizielle Dokumentation.
Eine häufige Falle: Die Variable wird in ~/.zshrc exportiert, aber Claude Code, das über Dock oder IDE gestartet wird, liest sie nicht. GUI-Programme erben die Login-Umgebung und laden nicht zwingend Ihre Shell-Konfiguration. Schreiben Sie die Einstellung dann in settings.json oder injizieren Sie sie explizit im Startskript.
4. Mehrere Konfigurationen: Person, Projekt, Team trennen
Legen Sie mindestens drei Key-Sätze an: persönlicher Alltag, projektspezifisch und Automatisierung. Kontingente, Rechte und Rotationszyklen unterscheiden sich; eine Vermischung macht Verbrauch und Störungen schwer nachvollziehbar.
Wenn Sie nicht mehrere Konfigurationsdateien pflegen möchten, injizieren Sie die Werte per Shell-Funktion:
# ~/.zshrc
claude_work() {
ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
ANTHROPIC_AUTH_TOKEN="$ZSQH_WORK_KEY" \
claude "$@"
}
claude_test() {
ANTHROPIC_BASE_URL="https://ai.zhongshangqihang.com" \
ANTHROPIC_AUTH_TOKEN="$ZSQH_TEST_KEY" \
claude "$@"
}
Die echten Keys liegen in ~/.zshrc.local oder einem Secrets-Tool; die Hauptkonfiguration referenziert nur Variablen. So wechseln Sie die Umgebung über den Funktionsnamen, ohne Projektcode zu ändern.
Für Projekttrennung nutzen Sie .claude/settings.local.json und stellen sicher, dass die Datei in .gitignore steht. Die im Team geteilte .claude/settings.json enthält nur unkritische Angaben wie Base URL, Modellnamen und Berechtigungen, niemals Keys.
5. Key-Rotation: wann und wie
Rotation ist kein Selbstzweck, sondern verkürzt das Zeitfenster nach einer Offenlegung. Rotieren Sie bei Mitarbeiteraustritt oder -wechsel, Geräteverlust, Leak-Verdacht, Anbieteranforderung und zusätzlich in festen Zyklen. Der Zyklus richtet sich nach den Compliance-Vorgaben des Teams, beispielsweise alle 90 Tage.
- Legen Sie in der Konsole einen neuen Key an, mit Datum im Namen, etwa
claude-code-prod-2026-10. - Schreiben Sie den neuen Key zuerst in das Secrets-Tool oder die Umgebungsvariable; den alten Key noch nicht löschen.
- Validieren Sie je einmal mit curl und Claude Code, dass Modell, Kontingent und Rechte stimmen.
- Beobachten Sie die Nutzungslogs des alten Keys, um übersehene Skripte oder Mitglieder zu finden.
- Deaktivieren Sie den alten Key und beobachten Sie ein bis zwei Tage die Fehlerrate.
- Dokumentieren Sie Zeitpunkt, Verantwortlichen und betroffenen Bereich für die nächste Übergabe.
Rotieren Sie nicht in Spitzenzeiten der Produktion. Zwei Keys eine Zeit lang parallel zu betreiben ist deutlich sicherer als „löschen und neu anlegen“.
6. Leak-Schutz: vom Entwicklungsrechner bis zum Repository
Keys gelangen meist nicht durch Hackerangriffe nach außen, sondern durch eigene Commits, Screenshots, Bildschirmaufnahmen, Gruppenchats oder Logs. Diese Regeln helfen:
.gitignoredeckt.env,.env.*,.claude/settings.local.json,*.pemund Ähnliches ab.- Vor dem Commit prüfen Secret-Scanner oder ein Pre-Commit-Hook auf Muster wie
sk-. - Keine Standard-Keys im Code, kein Debuggen mit
echo $ANTHROPIC_AUTH_TOKEN. - In Logs die Header
Authorizationundx-api-keymaskieren. - Vor Bildschirmfreigabe und Screenshots die Terminal-Historie schließen oder den Bildschirm leeren.
- Dateirechte auf dem Entwicklungsrechner setzen, etwa
chmod 600 ~/.claude/settings.json. - Keys mit Ablaufdatum und Obergrenze verwenden, um den Schaden einer einzelnen Offenlegung zu begrenzen.
Bei bestätigtem Leak gilt: zuerst den Key deaktivieren oder löschen, dann einen neuen anlegen, anschließend Nutzungslogs und Repository-Historie prüfen. Nur das Passwort zu ändern oder eine Datei zu löschen reicht nicht, denn der alte Key kann bereits kopiert worden sein.
7. CI und Teamnutzung
Im CI gilt: „Key nicht in den Code, nicht ins Image, nicht ins Log.“ Konkret:
- Über die Secret- oder Umgebungsvariablenfunktion der Plattform injizieren, nicht im Klartext in YAML schreiben.
- Secrets nur für geschützte Branches oder vertrauenswürdige Workflows freigeben.
- Vor Log-Ausgaben sicherstellen, dass Request-Header nicht gedruckt werden; viele HTTP-Bibliotheken tun das standardmäßig nicht, eigene Logs möglicherweise schon.
- Automatisierte Aufgaben mit eigenem Key und eigenem Limit betreiben, damit Anomalien lokalisierbar sind.
- Ein Key pro Teammitglied, am Austrittstag deaktivieren; keine gemeinsamen Keys aus Bequemlichkeit.
- Nutzung regelmäßig exportieren und nach Mitglied, Projekt und Modell prüfen.
Unterstützt die Plattform kurzlebige Credentials oder OIDC, bevorzugen Sie diese, um langfristige Keys seltener speichern zu müssen. Ob das geht, hängt von der Plattform ab; lesen Sie vor der Anbindung die Dokumentation.
8. 401-Diagnose: in dieser Reihenfolge
401 bedeutet Authentifizierungsfehler, nicht zwingend einen falschen Key. Mit dieser Reihenfolge finden Sie die Ursache meist in wenigen Minuten:
- Prüfen Sie, an welche Base URL die Anfrage geht:
echo $ANTHROPIC_BASE_URL. Ein leerer Wert oder eine alte Adresse scheitert. - Prüfen Sie den Key auf führende/abschließende Leerzeichen, Zeilenumbrüche oder überflüssige Anführungszeichen; kopieren Sie ihn erneut aus der Konsole.
- Prüfen Sie den Variablennamen:
ANTHROPIC_AUTH_TOKENoderANTHROPIC_API_KEY; setzen Sie nicht beide gleichzeitig. - Prüfen Sie, ob der Request-Header zur Gateway-Anforderung passt: Bearer oder x-api-key.
- Prüfen Sie, ob der Key abgelaufen oder deaktiviert ist und ob das Konto Guthaben hat.
- Prüfen Sie, ob der Modellname im Gateway-Katalog existiert; manche Plattformen antworten bei fehlender Modellberechtigung mit 401 oder 403.
- Läuft die Anfrage über einen Proxy, prüfen Sie, ob dieser den Authorization-Header entfernt oder umschreibt.
- Reproduzieren Sie mit einem minimalen curl, um Claude-Code-Version oder Konfigurationsebenen auszuschließen.
Häufige Fehler im Überblick:
| Fehler | Häufige Ursache | Behandlung |
|---|---|---|
| 401 | Falscher Key, falscher Variablenname, falscher Header | Neu kopieren; nur eine Auth-Variable behalten |
| 403 Forbidden | Key ohne Modellrecht oder IP-Sperre | Allowlist und Modellrechte prüfen |
| 404 Not Found | Base URL oder Pfad falsch | Root-Adresse und /v1 schrittweise testen |
| 429 Too Many Requests | Parallelität oder Kontingent überschritten | Parallelität senken; Key-Limit prüfen |
| insufficient quota | Guthaben zu niedrig | Aufladen oder Key wechseln |
Funktioniert curl, Claude Code meldet aber weiter 401, prüfen Sie die Startumgebung: Integrierte IDE-Terminals, Docker, systemd und launchd erben Ihre Shell-Variablen möglicherweise nicht. Schreiben Sie die Konfiguration in settings.json oder ein Startskript; meist löst das das Problem.
Häufige Fragen
Sind der Claude-Code-Key und eine Claude-Web-Mitgliedschaft dasselbe?
Nein. Die Web-Mitgliedschaft ist ein Abo für das Chatprodukt, der API-Key ein Zugangsnachweis für die Schnittstelle. Claude Code nutzt API-Aufrufe; eine Web-Mitgliedschaft ersetzt keinen Key.
Kann ein Key gleichzeitig für Claude Code und Cursor verwendet werden?
Technisch meist ja, sofern beide Werkzeuge dasselbe Gateway-Protokoll und dieselben Modellnamen unterstützen. Empfohlen ist dennoch ein Key pro Werkzeug, damit Limits, Diagnose und Deaktivierung getrennt bleiben.
Ist ein Key in settings.json sicher?
Auf einem persönlichen Rechner ist das akzeptabel, weil die Datei nur lokal liegt. Auf geteilten Rechnern, in Repositories und in CI keine Klartext-Keys ablegen; nutzen Sie Umgebungsvariablen, apiKeyHelper oder einen Secrets-Dienst.
Erfordert Key-Rotation eine Dienstunterbrechung?
Nein. Neuen Key anlegen und validieren, Konfiguration umstellen, alten Key deaktivieren. Lassen Sie beide Keys eine Zeit lang parallel laufen, um Anfrageabbrüche zu vermeiden.
Warum funktionierte es gestern, und heute kommt 401?
Häufige Ursachen: Key abgelaufen, Guthaben oder Kontingent erschöpft, Key vom Administrator deaktiviert, Gateway hat die Authentifizierung geändert oder die Startumgebung lädt die neuesten Variablen nicht. Gehen Sie die 401-Reihenfolge durch.
Nächste Schritte
Wenn Sie noch keinen Key haben, legen Sie über die Registrierung einen Test-Key mit niedrigem Limit an und konfigurieren und validieren Sie ihn wie beschrieben. Modelle, Kontingente und Abrechnung entnehmen Sie den Modellpreisen; Preise ändern sich mit Modellversionen und Upstream-Richtlinien, maßgeblich sind die aktuellen Angaben auf der Seite.
Weiterlesen:
- Claude Code einrichten: Installation, Base URL und Modelle
- Claude Code API-Fehler: 401, 404, 429 und Timeouts
- Modellpreise und Tarife
Hinweis: Claude, Claude Code und Anthropic sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient der technischen Erläuterung; es besteht keine Zugehörigkeit zu den genannten Unternehmen. Schnittstellen, Berechtigungen und Preise richten sich nach der offiziellen Dokumentation und den Seiten auf dieser Website.
