1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Claude Code mit einem LLM-Gateway verbinden
6
7> Richten Sie Claude Code auf das LLM-Gateway Ihrer Organisation aus. Überprüfen Sie, ob Ihr Administrator es bereits konfiguriert hat, oder legen Sie die Basis-URL und die Anmeldedaten selbst für die CLI, VS Code, GitHub Actions und das Agent SDK fest, überprüfen Sie dann die Verbindung und beheben Sie Gateway-Fehler.
8
9Ein [LLM-Gateway](/de/llm-gateway) ist ein Proxy, den Ihre Organisation zwischen Claude Code und dem Modell-Anbieter betreibt. Wenn Ihre Organisation einen verwendet, authentifiziert sich Claude Code beim Gateway mit einer Anmeldedaten, die Ihre Organisation ausstellt, anstelle Ihres persönlichen claude.ai-Logins.
10
11Diese Seite ist für Entwickler, die Claude Code über ein Gateway ausführen, das ihre Organisation betreibt. Sie behandelt zwei Pfade: [Überprüfung, ob Ihr Administrator es bereits für Sie konfiguriert hat](#check-for-an-existing-configuration), und [Konfiguration selbst](#configure-claude-code-yourself), wenn dies nicht der Fall ist.
12
13<Note>
14 * Um ein Gateway für Ihre Organisation bereitzustellen, siehe [Rollout eines LLM-Gateways](/de/llm-gateway-rollout)
15 * Für das, was Claude Code an ein Gateway sendet, siehe die [Gateway-Protokoll-Referenz](/de/llm-gateway-protocol)
16</Note>
17
18<h2 id="check-for-an-existing-configuration">
19 Überprüfung einer vorhandenen Konfiguration
20</h2>
21
22Administratoren können die Gateway-Adresse und die Anmeldedaten über [verwaltete Einstellungen](/de/settings#settings-files), Geräteverwaltung oder einen [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) verteilen, sodass Claude Code sie beim Start ohne weitere Konfiguration aufgreift. Um zu überprüfen, ob Ihre Organisation dies bereits getan hat:
23
24<Steps>
25 <Step title="Claude Code starten">
26 Führen Sie `claude` aus. Wenn es sich stattdessen zum Anmeldebildschirm öffnet, wurde keine Gateway-Anmeldedaten verteilt; [konfigurieren Sie es selbst](#configure-claude-code-yourself) unten.
27 </Step>
28
29 <Step title="Überprüfen Sie die Registerkarte Status">
30 Wenn Claude Code eine Sitzung ohne Anmeldebildschirm gestartet hat, führen Sie `/status` aus, öffnen Sie die Registerkarte **Status**, und überprüfen Sie zwei Zeilen:
31
32 * `Anthropic base URL`: Diese Zeile wird nur angezeigt, wenn eine Gateway-Adresse festgelegt ist. Wenn sie nicht vorhanden ist, ist Claude Code nicht auf das Gateway ausgerichtet; [konfigurieren Sie es selbst](#configure-claude-code-yourself) unten.
33 * `Auth token` oder `API key`: Eine Zeile mit `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY` oder einem `apiKeyHelper` bestätigt, dass eine Gateway-Anmeldedaten aktiv ist. Eine `Login method`-Zeile mit einem claude.ai-Konto bedeutet stattdessen, dass die Anmeldedaten nicht verteilt wurden; [legen Sie sie selbst fest](#set-the-credential-variable).
34 </Step>
35
36 <Step title="Senden Sie eine Testnachricht">
37 Schließen Sie das `/status`-Menü und senden Sie eine beliebige Eingabeaufforderung in Claude Code. Eine normale Antwort von Claude ohne Fehler bestätigt, dass die Gateway-Verbindung funktioniert.
38 </Step>
39</Steps>
40
41Wenn beide Zeilen im `/status`-Menü richtig aussehen, aber die Nachricht an Claude fehlschlägt, siehe die [Fehlerbehebungstabelle](#troubleshoot-gateway-errors).
42
43<h2 id="configure-claude-code-yourself">
44 Claude Code selbst konfigurieren
45</h2>
46
47Um Claude Code selbst für das Gateway zu konfigurieren, benötigen Sie von Ihrem Gateway-Team:
48
49* Die Basis-URL des Gateways
50* Eine Anmeldedaten: eine Schlüssel- oder Token-Zeichenkette oder ein Befehl, der eine abruft
51 * Wenn Ihr Gateway-Team nicht angegeben hat, welche Art von Anmeldedaten es ist, behandelt der Abschnitt [Anmeldedaten-Variable](#set-the-credential-variable) unten, was zu versuchen ist
52
53Die folgenden Abschnitte behandeln die Konfiguration in Reihenfolge:
54
55* [Legen Sie die Anmeldedaten-Variable fest](#set-the-credential-variable) und [legen Sie die Basis-URL fest](#set-the-base-url-and-credential): die zwei Variablen, die jede Gateway-Verbindung benötigt
56* [Überprüfen Sie die Verbindung](#verify-the-connection): bestätigen Sie, dass sie funktioniert, bevor Sie etwas speichern
57* [Konfigurieren Sie jede Oberfläche](#configure-each-surface): Wenn Sie eine andere Oberfläche als die Claude Code CLI verwenden, z. B. VS Code, erfahren Sie, wie Sie sie mit Ihren Gateway-Anmeldedaten konfigurieren
58* [Zusätzliche Konfiguration](#additional-configuration): Variablen, die einige Gateways über die Basis-URL und die Anmeldedaten hinaus benötigen, z. B. einen benutzerdefinierten Header, einen Anmeldedaten-Helper, Modellermittlung oder eine Basis-URL im Anbieterformat. Legen Sie diese nur fest, wenn Ihr Administrator sie benannt hat
59
60<h3 id="set-the-credential-variable">
61 Legen Sie die Anmeldedaten-Variable fest
62</h3>
63
64Um Claude Code beim Gateway zu authentifizieren, legen Sie Ihre Anmeldedaten in einer Umgebungsvariablen fest. Welche Variable hängt davon ab, was Ihr Gateway-Team Ihnen mitgeteilt hat:
65
66| Legen Sie die Anmeldedaten fest in | Verwenden Sie, wenn |
67| :------------------------------------------------------ | :---------------------------------------------------------------- |
68| `ANTHROPIC_AUTH_TOKEN` | Ihr Gateway-Team sagte 'Bearer-Token" oder „Authorization-Header" |
69| `ANTHROPIC_API_KEY` | Ihr Gateway-Team sagte „API-Schlüssel" oder „x-api-key" |
70| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | Die Anmeldedaten rotieren oder stammen aus einem Tresor |
71
72Wenn Sie nicht angegeben wurden, welche Art, verwenden Sie `ANTHROPIC_AUTH_TOKEN`; die [Überprüfungsanfrage](#verify-the-connection) unten zeigt, wie Sie feststellen, ob Sie wechseln müssen.
73
74<h3 id="set-the-base-url-and-credential">
75 Legen Sie die Basis-URL und die Anmeldedaten fest
76</h3>
77
78Legen Sie die Basis-URL des Gateways und die Anmeldedaten-Variable, die Sie oben ausgewählt haben, als Umgebungsvariablen fest. Die Beispiele verwenden `ANTHROPIC_AUTH_TOKEN`; ersetzen Sie es durch `ANTHROPIC_API_KEY`, wenn das [die Variable ist, die Sie ausgewählt haben](#set-the-credential-variable). Sie können sie [in Ihrer Shell](#set-as-shell-environment-variables) festlegen, was für eine Terminal-Sitzung gilt, oder [in einer Claude Code-Einstellungsdatei](#set-in-a-settings-file), was überall dort bestehen bleibt, wo Claude Code ausgeführt wird.
79
80Beginnen Sie für Ihre erste Verbindung mit Shell-Exporten und führen Sie die [Überprüfungsanfrage](#verify-the-connection) aus, bevor Sie die Werte in eine Einstellungsdatei verschieben.
81
82<h4 id="set-as-shell-environment-variables">
83 Legen Sie als Shell-Umgebungsvariablen fest
84</h4>
85
86Ersetzen Sie die Werte durch die, die Ihr Gateway-Team Ihnen gegeben hat:
87
88<Tabs>
89 <Tab title="Bash oder Zsh">
90 ```bash theme={null}
91 export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
92 export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
93 ```
94 </Tab>
95
96 <Tab title="PowerShell">
97 ```powershell theme={null}
98 $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
99 $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
100 ```
101 </Tab>
102</Tabs>
103
104Shell-Exporte gelten nur für diese Terminal-Sitzung und Programme, die von ihr aus gestartet werden; ein Editor, der vom Dock oder Startmenü gestartet wird, sieht sie nicht. Um sie über neue Terminals hinweg bestehen zu lassen, fügen Sie die gleichen Zeilen zu Ihrem Shell-Profil hinzu, z. B. `~/.zshrc`, `~/.bashrc` oder Ihr PowerShell-`$PROFILE`, oder verwenden Sie stattdessen eine Einstellungsdatei.
105
106<h4 id="set-in-a-settings-file">
107 Legen Sie in einer Einstellungsdatei fest
108</h4>
109
110Um die Konfiguration überall dort anzuwenden, wo Claude Code ausgeführt wird, ohne von Ihrer Shell abhängig zu sein, legen Sie die Variablen im `env`-Block einer [Einstellungsdatei](/de/settings) fest. Einstellungsdateien haben unterschiedliche Bereiche:
111
112* `~/.claude/settings.json` gilt für alle Ihre Projekte. Unter Windows ist der Pfad `%USERPROFILE%\.claude\settings.json`
113* `.claude/settings.local.json` gilt für ein Projekt. Claude Code fügt es zu Ihrem gitignore hinzu, wenn es die Datei erstellt; wenn Sie sie selbst erstellen, fügen Sie sie zuerst manuell zu Ihrem gitignore hinzu, damit Sie Ihre Anmeldedaten nicht versehentlich committen
114
115<Warning>
116 Legen Sie die Anmeldedaten nicht in die `.claude/settings.json` eines Projekts. Diese Datei wird committed und mit jedem geteilt, der das Repository klont.
117</Warning>
118
119Der `env`-Block sieht in beiden Dateien gleich aus:
120
121```json theme={null}
122{
123 "env": {
124 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
125 "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
126 }
127}
128```
129
130Wenn sowohl ein Shell-Export als auch ein `env`-Block einer Einstellungsdatei die gleiche Variable festlegen, gilt der Wert der Einstellungsdatei. Führen Sie `/status` aus, um zu sehen, welche Basis-URL und Anmeldedaten-Quelle Claude Code verwendet.
131
132<h3 id="verify-the-connection">
133 Überprüfen Sie die Verbindung
134</h3>
135
136Mit den in Ihrer Shell exportierten Variablen senden Sie eine Anfrage mit einem Token direkt an das Gateway. Dies bestätigt, dass die URL und die Anmeldedaten funktionieren, bevor Sie Claude Code öffnen, sodass ein Fehler auf das Gateway statt auf Ihre Konfiguration hinweist. Die folgenden Befehle lesen die Shell-Variablen, daher benötigen sie die [Shell-Exporte](#set-as-shell-environment-variables), auch wenn Sie die Werte auch in eine Einstellungsdatei eingeben.
137
138<Tabs>
139 <Tab title="Bash oder Zsh">
140 ```bash theme={null}
141 curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
142 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
143 -H "anthropic-version: 2023-06-01" \
144 -H "content-type: application/json" \
145 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
146 ```
147 </Tab>
148
149 <Tab title="PowerShell">
150 ```powershell theme={null}
151 Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
152 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
153 -ContentType "application/json" `
154 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
155 ```
156 </Tab>
157</Tabs>
158
159Wenn Ihr Gateway Schlüssel im `x-api-key`-Header erwartet, ersetzen Sie den `Authorization`-Header durch `x-api-key: $ANTHROPIC_API_KEY` im Bash-Befehl oder den `"Authorization"`-Hashtable-Eintrag durch `"x-api-key" = "$env:ANTHROPIC_API_KEY"` im PowerShell-Befehl.
160
161Eine JSON-Antwort, die mit `{"id":"msg_` beginnt und ein `"content":[...]`-Feld enthält, bedeutet, dass das Gateway erreichbar ist und die Anmeldedaten funktionieren. Ein Fehler, der ein unbekanntes Modell benennt, beweist immer noch, dass die URL und die Anmeldedaten funktionieren, da das Gateway die Anfrage authentifiziert hat, bevor es den Modellnamen ablehnt; Sie müssen kein Modell finden, das Ihr Gateway für diesen Test bereitstellt. Ein `401` bedeutet, dass die Anmeldedaten abgelehnt wurden: Wenn Sie die Variable erraten haben, wechseln Sie zur anderen und exportieren Sie erneut.
162
163<h4 id="confirm-in-claude-code">
164 Bestätigen Sie in Claude Code
165</h4>
166
167Starten Sie `claude` aus der gleichen Shell, damit es die Exporte erbt, senden Sie eine Nachricht, und führen Sie `/status` aus.
168
169Auf der Registerkarte **Status** sollte die Zeile `Anthropic base URL` Ihre Gateway-Adresse anzeigen, was bestätigt, dass Anfragen dorthin weitergeleitet werden; wenn die Zeile nicht vorhanden ist, hat die Variable die Sitzung nicht erreicht. Eine `Auth token`- oder `API key`-Zeile, die die Variable benennt, die Sie festgelegt haben, bestätigt, dass die Gateway-Anmeldedaten aktiv sind, anstatt eines gespeicherten claude.ai-Logins.
170
171Wenn die Nachricht fehlschlägt oder `/status` die Gateway-URL nicht anzeigt, siehe die [Fehlerbehebungstabelle](#troubleshoot-gateway-errors) unten.
172
173<h3 id="how-the-credential-variable-maps-to-a-header">
174 Wie die Anmeldedaten-Variable einem Header zugeordnet wird
175</h3>
176
177Jede Variable sendet die Anmeldedaten in einem anderen HTTP-Header: `ANTHROPIC_AUTH_TOKEN` in `Authorization: Bearer`, `ANTHROPIC_API_KEY` in `x-api-key` und `apiKeyHelper` in beiden. Eine Anmeldedaten in der falschen Variable erreicht das Gateway in einem Header, den es nicht liest, und die Anfrage schlägt mit `401` fehl. Wenn die Überprüfungsanfrage `401` zurückgegeben hat, wechseln Sie zur anderen Variable und versuchen Sie es erneut.
178
179<h3 id="conflicts-with-an-existing-login">
180 Konflikte mit einem vorhandenen Login
181</h3>
182
183Eine Gateway-Anmeldedaten-Variable hat Vorrang vor einem gespeicherten claude.ai-Login oder Console-Schlüssel. Ihr claude.ai-Login bleibt gespeichert und ungenutzt, während die Variable festgelegt ist; heben Sie die Festlegung der Variable auf und Claude Code kehrt zu ihr zurück. Mit `ANTHROPIC_AUTH_TOKEN` hat die Variable sofort Vorrang. Mit `ANTHROPIC_API_KEY` werden Sie einmal im interaktiven Modus aufgefordert, den Schlüssel zu genehmigen, bevor er übernimmt.
184
185Führen Sie `/status` aus, um zu bestätigen, welche Anmeldedaten-Quelle aktiv ist. Wenn der Start eine Auth-Konflikt-Warnung anzeigt, die zwei Quellen benennt, siehe die erste Zeile der [Fehlerbehebungstabelle](#troubleshoot-gateway-errors), um zu sehen, welche zu löschen ist. Um einen gespeicherten Login zu löschen, damit nur die Gateway-Anmeldedaten verbleiben, führen Sie `/logout` aus.
186
187<h2 id="configure-each-surface">
188 Konfigurieren Sie jede Oberfläche
189</h2>
190
191Die CLI liest die Umgebungsvariablen und Einstellungsdateien oben. Die anderen Oberflächen sind die VS Code-Erweiterung, die Desktop-App, GitHub Actions, das Agent SDK und die Cloud-Oberflächen wie Slack und das Web; die folgenden Abschnitte behandeln, ob diese Einstellungen jede erreichen.
192
193<h3 id="vs-code-extension">
194 VS Code-Erweiterung
195</h3>
196
197Legen Sie die Gateway-Variablen für die [VS Code-Erweiterung](/de/vs-code) in `claudeCode.environmentVariables` in VS Codes eigenen Benutzereinstellungen fest, die mit dem Befehl **Preferences: Open User Settings (JSON)** geöffnet werden. Die Erweiterung überprüft Anmeldedaten aus dieser Einstellung vor dem Start, daher ist es der zuverlässige Ort für die Gateway-Anmeldedaten; Werte in `~/.claude/settings.json` erreichen den erzeugten Prozess, aber nicht die Anmeldungsprüfung der Erweiterung selbst.
198
199```json theme={null}
200{
201 "claudeCode.environmentVariables": [
202 { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
203 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
204 ]
205}
206```
207
208<h3 id="desktop-app">
209 Desktop-App
210</h3>
211
212Die Desktop-App liest Gateway-Routing aus einer [von Administrator verteilten Konfiguration](https://claude.com/docs/cowork/3p/gateway), nicht aus `ANTHROPIC_BASE_URL` oder `settings.json`. Wenn Ihre Organisation sie verteilt hat, leitet die Desktop-App ohne Einrichtung auf Ihrer Seite durch das Gateway; wenn nicht, verwenden Sie die Terminal-CLI oder VS Code-Erweiterung für Gateway-Sitzungen. Administratoren verteilen die Konfiguration wie in der [Organisations-Rollout](/de/llm-gateway-rollout#distribute-through-managed-settings) beschrieben.
213
214Wenn die Desktop-App `Gateway was unreachable` anzeigt, konnte die App die konfigurierte Basis-URL beim Start nicht erreichen; überprüfen Sie die URL und den Netzwerkpfad mit dem [curl-Test oben](#verify-the-connection).
215
216<h3 id="github-actions">
217 GitHub Actions
218</h3>
219
220[Claude Code GitHub Actions](/de/github-actions) liest `ANTHROPIC_BASE_URL` und `ANTHROPIC_CUSTOM_HEADERS` aus dem `env`-Block des Workflows. Übergeben Sie die Anmeldedaten als die `anthropic_api_key`-Eingabe der Aktion; die Aktion legt sie als `ANTHROPIC_API_KEY` fest, sodass sie das Gateway im `x-api-key`-Header erreichen.
221
222Für ein `x-api-key`-Gateway legen Sie die Basis-URL in `env` fest und übergeben Sie den Gateway-Schlüssel als Eingabe:
223
224```yaml theme={null}
225env:
226 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
227
228steps:
229 - uses: anthropics/claude-code-action@v1
230 with:
231 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
232```
233
234Für ein Bearer-Token-Gateway übergeben Sie das gleiche Geheimnis sowohl als die `anthropic_api_key`-Eingabe als auch als `ANTHROPIC_AUTH_TOKEN` im Workflow-`env`-Block. Die Aktion erfordert `anthropic_api_key`, `CLAUDE_CODE_OAUTH_TOKEN` oder Workload-Identitäts-Verbund, bevor sie Claude Code startet, und sie liest `ANTHROPIC_AUTH_TOKEN` nicht, daher erfüllt die Eingabe diese Start-Prüfung, während die Env-Variable den Schlüssel in den `Authorization`-Header legt, den das Gateway liest. Die Kopie in `x-api-key` wird ignoriert:
235
236```yaml theme={null}
237env:
238 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
239 ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}
240
241steps:
242 - uses: anthropics/claude-code-action@v1
243 with:
244 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
245```
246
247Für die anderen Authentifizierungsoptionen der Aktion, einschließlich `CLAUDE_CODE_OAUTH_TOKEN` und Workload-Identitäts-Verbund, siehe [Claude Code GitHub Actions](/de/github-actions) und die [README](https://github.com/anthropics/claude-code-action#readme) der Aktion.
248
249<h3 id="agent-sdk">
250 Agent SDK
251</h3>
252
253Das [Agent SDK](/de/agent-sdk/overview) hat keine Gateway-spezifischen Optionen; es übergibt Umgebungsvariablen an den Claude Code-Prozess, den es erzeugt. Jedes SDK akzeptiert eine `env`-Option, die die Umgebung des erzeugten Prozesses festlegt, und die TypeScript- und Python-SDKs behandeln sie unterschiedlich:
254
255* TypeScript: Der erzeugte Prozess erbt standardmäßig die übergeordnete Umgebung, aber das Festlegen von `options.env` ersetzt die Umgebung vollständig. Verteilen Sie `process.env` darin, um Ihre Gateway-Variablen zu behalten.
256* Python: `ClaudeAgentOptions(env=...)` wird auf der geerbten Umgebung zusammengeführt, daher werden Gateway-Variablen, die im übergeordneten Prozess festgelegt sind, ohne Verteilung durchgeleitet.
257
258<CodeGroup>
259 ```ts TypeScript theme={null}
260 const result = query({
261 prompt: "...",
262 options: {
263 env: {
264 ...process.env,
265 ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
266 ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
267 },
268 },
269 })
270 ```
271
272 ```python Python theme={null}
273 options = ClaudeAgentOptions(
274 env={
275 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
276 "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
277 }
278 )
279 ```
280</CodeGroup>
281
282<h3 id="slack-web-and-remote-control">
283 Slack, Web und Remote Control
284</h3>
285
286[Claude Code in Slack](/de/slack) und [Claude Code im Web](/de/claude-code-on-the-web) sind von Anthropic gehostete Produkte, die immer die Anthropic-API verwenden; sie sind nicht Teil einer Gateway-Bereitstellung. Gateway-Variablen, die in der Umgebungskonfiguration einer Cloud-Sitzung festgelegt sind, werden nicht angewendet. Wenn Ihr Datenverkehr auf dem Gateway bleiben muss, aktivieren Sie diese Oberflächen nicht für diese Benutzer.
287
288[Remote Control](/de/remote-control) und [Sprachdiktat](/de/voice-dictation) verlassen sich beide auf eine claude.ai-Identität: Remote Control, um eine Live-Sitzung mit Ihrem Konto zu koppeln, und Sprachdiktat, um den claude.ai-Transkriptions-Endpunkt zu erreichen. Sie sind nicht verfügbar, während `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` oder ein `apiKeyHelper` aktiv ist. Um eines davon zu verwenden, heben Sie die Festlegung der Gateway-Anmeldedaten auf und melden Sie sich stattdessen mit claude.ai an; `/doctor` benennt die Variable, die aufgehoben werden soll.
289
290<h2 id="additional-configuration">
291 Zusätzliche Konfiguration
292</h2>
293
294Diese Einstellungen behandeln Fälle über die Basis-URL und die Anmeldedaten hinaus. Legen Sie sie nur fest, wenn die Anweisungen Ihres Administrators oder die [Fehlerbehebungstabelle](#troubleshoot-gateway-errors) eine erfordern.
295
296<h3 id="send-additional-headers">
297 Senden Sie zusätzliche Header
298</h3>
299
300Einige Gateways leiten oder kennzeichnen Anfragen mit einem benutzerdefinierten Header zusätzlich zur Anmeldedaten, z. B. eine Mandanten-ID oder einen Routing-Schlüssel. Um einen zu senden, legen Sie [`ANTHROPIC_CUSTOM_HEADERS`](/de/env-vars) mit einem `Name: Value`-Paar pro Zeile fest. Das Beispiel unten fügt einen Routing-Header namens `X-Org-Route` hinzu:
301
302<Tabs>
303 <Tab title="Bash oder Zsh">
304 ```bash theme={null}
305 export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
306 ```
307 </Tab>
308
309 <Tab title="PowerShell">
310 ```powershell theme={null}
311 $env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
312 ```
313 </Tab>
314</Tabs>
315
316Sie können auch `ANTHROPIC_CUSTOM_HEADERS` im `env`-Block einer Einstellungsdatei festlegen. Verwenden Sie `\n` zwischen Paaren dort, da JSON-Zeichenketten nicht mehrere Zeilen umfassen können:
317
318```json theme={null}
319{
320 "env": {
321 "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"
322 }
323}
324```
325
326<h3 id="add-gateway-models-to-the-model-picker">
327 Fügen Sie Gateway-Modelle zum Modellwähler hinzu
328</h3>
329
330Die Modellermittlung fragt das Gateway beim Start nach seiner Modellliste ab und fügt diese Namen zum `/model`-Wähler neben den integrierten Einträgen hinzu.
331
332Aktivieren Sie es, wenn Ihr Gateway Modellnamen bereitstellt, die nicht in der integrierten Liste von Claude Code enthalten sind, und Sie diese aus dem Wähler auswählen möchten. Wenn die integrierten Modelle das sind, was Sie verwenden, benötigen Sie keine Ermittlung; Ihr Administrator hat sie möglicherweise auch bereits über verwaltete Einstellungen aktiviert.
333
334Um sie zu aktivieren, legen Sie `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` in Ihrer Shell oder im `env`-Block von `~/.claude/settings.json` fest. Die Ermittlung erfordert Claude Code v2.1.129 oder später. {/* min-version: 2.1.129 */}
335
336Ermittelte Modelle werden als zusätzliche `/model`-Einträge mit der Bezeichnung `From gateway` angezeigt. Um zu bestätigen, dass die Ermittlung ausgeführt wurde, starten Sie `claude --debug` und suchen Sie nach den `[gatewayDiscovery]`-Zeilen: Ein Erfolg protokolliert, wie viele Modelle zwischengespeichert wurden, und ein `404`, Timeout oder Umleitung wird dort ebenfalls aufgezeichnet. Für den Zeitpunkt der Ermittlung, was sie filtert, und das Antwortformat, das Gateways bereitstellen, siehe die [Modellermittlungs-Referenz](/de/llm-gateway-protocol#model-discovery).
337
338<h3 id="rotate-credentials-with-apikeyhelper">
339 Rotieren Sie Anmeldedaten mit apiKeyHelper
340</h3>
341
342Ein `apiKeyHelper` ist ein Befehl, den Claude Code ausführt, um Ihre Gateway-Anmeldedaten abzurufen, anstatt sie aus einer statischen Umgebungsvariablen zu lesen.
343
344Verwenden Sie einen Helper, wenn die Anmeldedaten nach einem Zeitplan ablaufen, aus einem Tresor oder SSO-Befehl stammen, oder Ihr Administrator Ihnen mitgeteilt hat, einen zu konfigurieren. Wenn Ihre Anmeldedaten eine feste Zeichenkette sind, die Sie einmal festlegen, ist die [Anmeldedaten-Variable](#set-the-credential-variable) alles, was Sie benötigen, und Sie können diesen Abschnitt überspringen.
345
346Der Helper ist ein beliebiger Shell-Befehl, der die aktuelle Anmeldedaten auf stdout ausgibt. Claude Code führt ihn durch Ihre System-Shell aus, daher kann er unter Windows eine ausführbare Datei oder eine PowerShell-Invokation sein. Schreiben Sie das Skript, machen Sie es ausführbar, und verweisen Sie darauf von `apiKeyHelper` in Ihrer [Einstellungsdatei](/de/settings):
347
348<Tabs>
349 <Tab title="Bash oder Zsh">
350 Zum Beispiel ein Skript, das aus einem Tresor liest:
351
352 ```bash theme={null}
353 #!/bin/bash
354 vault kv get -field=api_key secret/llm-gateway/claude-code
355 ```
356
357 Verweisen Sie auf seinen Pfad in `~/.claude/settings.json`:
358
359 ```json theme={null}
360 {
361 "apiKeyHelper": "~/bin/get-gateway-key.sh"
362 }
363 ```
364 </Tab>
365
366 <Tab title="PowerShell">
367 Zum Beispiel ein Skript, das aus einem Tresor liest:
368
369 ```powershell theme={null}
370 vault kv get -field=api_key secret/llm-gateway/claude-code
371 ```
372
373 Verweisen Sie auf die PowerShell-Invokation in `%USERPROFILE%\.claude\settings.json`, wobei Sie die Backslashes in der JSON-Zeichenkette escapen:
374
375 ```json theme={null}
376 {
377 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
378 }
379 ```
380 </Tab>
381</Tabs>
382
383Claude Code speichert die Ausgabe des Helpers standardmäßig fünf Minuten lang zwischen und führt ihn erneut aus, wenn eine Anfrage HTTP 401 zurückgibt. Um die Lebensdauer des Caches zu ändern, legen Sie `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` in Millisekunden fest, z. B. `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` für 15 Minuten.
384
385Der Wert des Helpers wird in beiden `Authorization`- und `x-api-key`-Headern gesendet, daher funktioniert er, welcher Header Ihr Gateway auch liest.
386
387<h3 id="route-to-a-cloud-provider-through-a-gateway">
388 Leiten Sie zu einem Cloud-Anbieter über ein Gateway weiter
389</h3>
390
391Diese Konfigurationen richten Claude Code auf ein Gateway über eine anbieter-spezifische Basis-URL-Variable anstelle von `ANTHROPIC_BASE_URL` aus. Bedrock- und Vertex-Gateways akzeptieren die nativen Anforderungsformate dieser Anbieter; Foundry- und Claude Platform on AWS-Gateways akzeptieren das Anthropic Messages-Format und unterscheiden sich nur in der Basis-URL-Variable, die sie erreicht.
392
393Verwenden Sie eine nur, wenn Ihr Gateway-Team speziell Bedrock, Vertex, Foundry oder die Claude Platform on AWS benannt hat. Wenn die [Überprüfungsanfrage](#verify-the-connection) oben JSON zurückgegeben hat, können Sie diesen Abschnitt überspringen.
394
395Legen Sie den Block für den Anbieter fest, den Ihr Gateway-Team benannt hat. Die Skip-Auth-Variablen teilen Claude Code mit, dass Anfragen nicht mit Anbieter-Anmeldedaten signiert werden sollen, da das Gateway diese hält. Wenn das Gateway sein eigenes Token benötigt, fügen Sie `ANTHROPIC_AUTH_TOKEN` nach dem Block hinzu, außer für Foundry, das `ANTHROPIC_FOUNDRY_API_KEY` wie gezeigt verwendet.
396
397<h4 id="amazon-bedrock">
398 Amazon Bedrock
399</h4>
400
401<Tabs>
402 <Tab title="Bash oder Zsh">
403 ```bash theme={null}
404 export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
405 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
406 export CLAUDE_CODE_USE_BEDROCK=1
407 ```
408 </Tab>
409
410 <Tab title="PowerShell">
411 ```powershell theme={null}
412 $env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
413 $env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
414 $env:CLAUDE_CODE_USE_BEDROCK = "1"
415 ```
416 </Tab>
417</Tabs>
418
419<h4 id="google-vertex-ai">
420 Google Vertex AI
421</h4>
422
423<Tabs>
424 <Tab title="Bash oder Zsh">
425 ```bash theme={null}
426 export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
427 export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
428 export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
429 export CLAUDE_CODE_USE_VERTEX=1
430 export CLOUD_ML_REGION=us-east5
431 ```
432 </Tab>
433
434 <Tab title="PowerShell">
435 ```powershell theme={null}
436 $env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
437 $env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
438 $env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
439 $env:CLAUDE_CODE_USE_VERTEX = "1"
440 $env:CLOUD_ML_REGION = "us-east5"
441 ```
442 </Tab>
443</Tabs>
444
445<h4 id="microsoft-foundry">
446 Microsoft Foundry
447</h4>
448
449Legen Sie die Anmeldedaten des Gateways in `ANTHROPIC_FOUNDRY_API_KEY` fest; sie werden an das Gateway als `x-api-key`-Header gesendet. `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` gilt hier nicht: Ohne einen API-Schlüssel schlägt der Foundry-Client jede Anfrage fehl, bevor sie die Maschine verlässt.
450
451<Tabs>
452 <Tab title="Bash oder Zsh">
453 ```bash theme={null}
454 export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
455 export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
456 export CLAUDE_CODE_USE_FOUNDRY=1
457 ```
458 </Tab>
459
460 <Tab title="PowerShell">
461 ```powershell theme={null}
462 $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
463 $env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
464 $env:CLAUDE_CODE_USE_FOUNDRY = "1"
465 ```
466 </Tab>
467</Tabs>
468
469<h4 id="claude-platform-on-aws">
470 Claude Platform on AWS
471</h4>
472
473Siehe [Claude Platform on AWS](/de/claude-platform-on-aws) für die Workspace-ID.
474
475<Tabs>
476 <Tab title="Bash oder Zsh">
477 ```bash theme={null}
478 export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
479 export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
480 export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
481 export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
482 ```
483 </Tab>
484
485 <Tab title="PowerShell">
486 ```powershell theme={null}
487 $env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
488 $env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
489 $env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
490 $env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"
491 ```
492 </Tab>
493</Tabs>
494
495<h2 id="troubleshoot-gateway-errors">
496 Fehlerbehebung bei Gateway-Fehlern
497</h2>
498
499Dies sind die häufigsten Fehler beim Ausführen von Claude Code über ein Gateway, mit der Gateway-seitigen Ursache und der Behebung:
500
501| Fehler | Ursache | Behebung |
502| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503| Eine Start-Warnung, die zwei Anmeldedaten-Quellen benennt und mit `auth may not work as expected` endet. Ältere Versionen zeigen stattdessen `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` an. | Eine Gateway-Anmeldedaten und ein gespeicherter Login sind beide aktiv; die Variable wird für Anfragen verwendet, aber der veraltete Login kann zu unerwartetem Auth-Verhalten führen | Heben Sie die Festlegung der Variable auf, um den gespeicherten Login zu verwenden, oder führen Sie `/logout` aus, um die Gateway-Anmeldedaten zu verwenden |
504| `401`-Fehler, die ein ungültiges oder nicht erkanntes Token benennen | Die Anmeldedaten sind nicht eine, die das Gateway ausgestellt hat, oder sie sind in einem Header, den das Gateway nicht liest | Bestätigen Sie, dass die Variable Ihrer Anmeldedaten-Art in der [Anmeldedaten-Tabelle](#set-the-credential-variable) entspricht, und generieren Sie den Schlüssel beim Gateway neu, wenn er widerrufen wurde |
505| `Unable to connect to API (ConnectionRefused)`, oder `(ECONNREFUSED)` von npm-Installationen, oft nach einer stillen Pause, während Claude Code [mit Backoff erneut versucht](/de/errors#automatic-retries) | Nichts antwortete unter der Basis-URL: Die Adresse ist falsch, oder ein VPN oder eine Firewall blockiert den Pfad zum Gateway | Führen Sie den [curl-Test oben](#verify-the-connection) aus, der sofort mit der gleichen Ursache fehlschlägt, und bestätigen Sie die URL und den Netzwerkpfad mit Ihrem Gateway-Team |
506| `API returned an empty or malformed response (HTTP 200)` | Das Gateway oder ein zwischengelagerter Proxy gab eine Nicht-API-Antwort zurück, oft eine HTML-Fehler oder Anmeldeseite | Testen Sie mit der [curl-Anfrage oben](#verify-the-connection); beheben Sie die Gateway-Route, die Nicht-JSON zurückgibt |
507| `400`-Fehler, die `context_management`, `Extra inputs are not permitted` oder andere nicht erkannte Felder benennen | Das Gateway leitet Anfragen an einen Upstream weiter, der Felder ablehnt, die Claude Code an Anthropic-Format-Endpunkte sendet | Legen Sie `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` fest, das die meisten Pre-Release-Felder unterdrückt; siehe [Feature-Durchleitung](/de/llm-gateway-protocol#feature-pass-through). Einige Betas werden nicht durch dieses Flag gated; für diese legen Sie die passende `CLAUDE_CODE_USE_*`-Anbieter-Variable fest, damit Claude Code nur das sendet, das dieser Anbieter akzeptiert |
508| `400`-Fehler, die `thinking` oder `adaptive` benennen, z. B. `Input tag 'adaptive' found` | Der Upstream-Modell-Build akzeptiert keine adaptive Überlegung, die Claude Code für Claude 4.6 und neuere Modelle anfordert | Aktualisieren Sie den Upstream des Gateways. Auf Opus 4.6 und Sonnet 4.6 funktioniert stattdessen `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`. Die [Modellkonfiguration](/de/model-config)-Fähigkeitsvariablen gelten nur für die Anbieter-Konfigurationen, z. B. `CLAUDE_CODE_USE_BEDROCK` und `CLAUDE_CODE_USE_VERTEX`, nicht hinter einem `ANTHROPIC_BASE_URL`-Gateway |
509| `400`-Fehler, die einen Kontext- oder Token-Limit in den eigenen Worten des Gateways angeben, z. B. `ContextWindowExceededError` oder `prompt token count of N exceeds the limit of M` | Das Gateway erzwingt ein kleineres Kontext als das native Fenster des Modells und schreibt den Upstream-Fehler um, daher wird die automatische Komprimierung und Wiederholung, die Anthropics `prompt is too long`-Wortlaut entspricht, nicht ausgelöst | Führen Sie `/compact` aus, um die Sitzung wiederherzustellen. Um dies zu verhindern, legen Sie `CLAUDE_CODE_AUTO_COMPACT_WINDOW` auf das Limit des Gateways fest; der Wert wird auf mindestens 100.000 Token und höchstens das Kontext-Fenster des Modells begrenzt, daher kann ein Gateway-Limit unter 100.000 nicht abgeglichen werden und `/compact` bleibt die Wiederherstellung dort. Legen Sie auch `CLAUDE_CODE_MAX_OUTPUT_TOKENS` unter das Output-Limit des Gateway-Modells fest |
510| Modelle fehlen im `/model`-Wähler | Gateway-Modellnamen sind nicht in der integrierten Liste von Claude Code enthalten | Aktivieren Sie die [Gateway-Modellermittlung](#add-gateway-models-to-the-model-picker) oder fügen Sie Namen mit den [Modellkonfiguration](/de/model-config)-Variablen hinzu |
511| Claude Code fordert Sie auf, sich anzumelden, obwohl der [curl-Test](#verify-the-connection) erfolgreich ist | Die CLI hat keine eigene Anmeldedaten: Eine erreichbare Basis-URL ist keine, und ein `env`-Block in einer Projekt-`.claude/settings.json` oder `.claude/settings.local.json` gilt nur nach dem First-Run-Wizard und der Vertrauensaufforderung | Legen Sie `ANTHROPIC_AUTH_TOKEN` irgendwo fest, wo Claude Code vor dem First-Run-Setup liest: ein Shell-Export, der `env`-Block in `~/.claude/settings.json` oder verwaltete Einstellungen |
512| `ANTHROPIC_API_KEY` ist festgelegt, wird aber ignoriert, ohne Aufforderung | Der Schlüssel benötigt eine einmalige Genehmigung in interaktiven Sitzungen, und ein zuvor abgelehnter Schlüssel wird ohne erneute Frage ignoriert | Aktivieren Sie ihn unter `/config` mit der Option `Use custom API key` |
513| `This machine's managed settings require a first-party login` | Verwaltete Einstellungen enthalten `forceLoginMethod` oder `forceLoginOrgUUID`, die auf Claude Code v2.1.146 und später nicht mit `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` oder `apiKeyHelper` koexistieren können | Ihr Administrator muss `forceLoginMethod` und `forceLoginOrgUUID` aus verwalteten Einstellungen entfernen, um Gateway-Anmeldedaten zu verwenden, oder die Gateway-Anmeldedaten entfernen, um First-Party-Login zu verwenden. Die beiden können nicht kombiniert werden |
514| `403` mit einem HTML-Body wie `403 Forbidden`, wenn die eigenen Logs des Gateways zeigen, dass keine Anfrage empfangen wurde | Eine Web-Anwendungs-Firewall oder ein Reverse-Proxy vor dem Gateway blockierte den Anfrage-Body, bevor er das Gateway erreichte. Claude Code-Eingabeaufforderungen enthalten XML-ähnliche Tags und Quellcode, die Cross-Site-Scripting-Body-Regeln entsprechen, daher besteht ein kurzer curl-Test, während eine echte Sitzung nicht besteht | Befreien Sie den `/v1/messages`-Pfad des Gateways von der Anfrage-Body-Inspektion. Auf AWS WAF ist dies die verwaltete Regel `CrossSiteScripting_Body`; auf nginx mit ModSecurity sind dies die äquivalenten OWASP CRS-Body-Regeln |
515| Zertifikat- oder TLS-Fehler wie `SSL certificate verification failed` oder `Self-signed certificate detected`, wenn der [curl-Test](#verify-the-connection) erfolgreich ist | Die Runtime von Claude Code vertraut nicht der gleichen Zertifizierungsstelle, die `curl` verwendet. Häufig hinter Unternehmens-TLS-Inspektions-Proxys | Legen Sie `NODE_EXTRA_CA_CERTS` auf den CA-Bundle-Pfad fest; siehe [CA-Zertifikat-Speicher](/de/network-config#ca-certificate-store) |
516
517Wenn Claude Code Sie nach dem Entfernen der Gateway-Konfiguration wiederholt auffordert, sich anzumelden, ist die Ursache normalerweise Anmeldedaten-Speicherung statt des Gateways; siehe [Authentifizierungsfehler](/de/errors#authentication-errors).
518
519<h2 id="related-resources">
520 Verwandte Ressourcen
521</h2>
522
523* [LLM-Gateways-Übersicht](/de/llm-gateway): Was ein Gateway ist und wie es mit claude.ai-Abonnements interagiert
524* [Rollout eines LLM-Gateways für Ihre Organisation](/de/llm-gateway-rollout): Die Admin-seitige Checkliste für die Bereitstellung und Verteilung der Gateway-Konfiguration
525* [Gateway-Protokoll-Referenz](/de/llm-gateway-protocol): Was Claude Code an ein Gateway sendet, einschließlich der Header und Felder, die das Gateway weiterleiten muss
526* [Einstellungen](/de/settings): Wo Einstellungsdateien leben und wie der `env`-Block gelesen wird
527* [Authentifizierung](/de/authentication): Wie Anmeldedaten-Variablen, `apiKeyHelper` und OAuth-Login interagieren
