Connect Claude Code to an LLM gateway changedllm-gateway-connect
Nearest release: v2.1.304, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 19 Oct 2026 19:44 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+192added
Lines−214removed
From line
6
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits28to this page, all time
The whole hunk
from line 6, old and new numbered
/
from line 6
66
77This page is for developers running Claude Code through a gateway their organization operates. It covers two paths: [checking whether your administrator already configured it for you](#check-for-an-existing-configuration), and [configuring it yourself](#configure-claude-code-yourself) when they haven't.
88
9<Note>
10 * To deploy a gateway for your organization, see [Roll out an LLM gateway](/docs/en/llm-gateway-rollout)
11 * For what Claude Code sends to a gateway, see the [gateway compatibility guide](/docs/en/llm-gateway-protocol)
12</Note>
9> [!NOTE]
10>
11> * To deploy a gateway for your organization, see [Roll out an LLM gateway](/docs/en/llm-gateway-rollout)
12> * For what Claude Code sends to a gateway, see the [gateway compatibility guide](/docs/en/llm-gateway-protocol)
1313
1414## Check for an existing configuration
1515
1616Administrators can distribute the gateway address and credential through [managed settings](/docs/en/managed-settings), device management, or an [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper), so Claude Code picks them up at startup with nothing for you to set. To check whether your organization already did this:
1717
18<Steps>
19 <Step title="Start Claude Code">
20 Run `claude`. If it opens to the login screen instead of a session, no gateway credential was distributed; [configure it yourself](#configure-claude-code-yourself) below.
21 </Step>
18**1. Start Claude Code**
2219
23 <Step title="Check the Status tab">
24 If Claude Code started a session without showing the login screen, run `/status`, which opens on the **Status** tab, and check two lines:
20Run `claude`. If it opens to the login screen instead of a session, no gateway credential was distributed; [configure it yourself](#configure-claude-code-yourself) below.
2521
26 * `Anthropic base URL`: this line only appears when a gateway address is set. If it isn't there, Claude Code isn't pointed at the gateway; [configure it yourself](#configure-claude-code-yourself) below.
27 * `Auth token` or `API key`: a line naming `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, or an `apiKeyHelper` confirms a gateway credential is active. A `Login method` line naming a claude.ai account instead means the credential wasn't distributed; [set it yourself](#set-the-credential-variable).
28 </Step>
22**2. Check the Status tab**
2923
30 <Step title="Send a test message">
31 Close the `/status` menu and send any prompt in Claude Code. A normal response from Claude, with no error, confirms the gateway connection works.
32 </Step>
33</Steps>
24If Claude Code started a session without showing the login screen, run `/status`, which opens on the **Status** tab, and check two lines:
3425
26* `Anthropic base URL`: this line only appears when a gateway address is set. If it isn't there, Claude Code isn't pointed at the gateway; [configure it yourself](#configure-claude-code-yourself) below.
27* `Auth token` or `API key`: a line naming `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, or an `apiKeyHelper` confirms a gateway credential is active. A `Login method` line naming a claude.ai account instead means the credential wasn't distributed; [set it yourself](#set-the-credential-variable).
28
29**3. Send a test message**
30
31Close the `/status` menu and send any prompt in Claude Code. A normal response from Claude, with no error, confirms the gateway connection works.
32
3533If both lines in the `/status` menu look right but the message to Claude fails, see the [troubleshooting table](#troubleshoot-gateway-errors).
3634
3735## Configure Claude Code yourself
from line 69
7169
7270Replace the values with the ones your gateway team gave you:
7371
74<Tabs>
75 <Tab title="Bash or Zsh">
76 ```bash theme={null}
77 export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
78 export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
79 ```
80 </Tab>
72**Bash or Zsh**
8173
82 <Tab title="PowerShell">
83 ```powershell theme={null}
84 $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
85 $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
86 ```
87 </Tab>
88</Tabs>
74```bash theme={null}
75export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
76export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
77```
8978
79**PowerShell**
80
81```powershell theme={null}
82$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
83$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
84```
85
9086Shell exports apply only to that terminal session and programs started from it. An editor launched from the dock or Start menu won't see them. To make the values persist across new terminals, add the same lines to your shell profile, such as `~/.zshrc`, `~/.bashrc`, or your PowerShell `$PROFILE`.
9187
9288If you export the gateway only in your shell, it doesn't reliably reach background agents hosted by the [supervisor](/docs/en/agent-view#how-background-sessions-are-hosted); see [how each background session sources its gateway](/docs/en/agent-view#llm-gateway). Use a settings file for any gateway that background agents must always route through.
from line 94
9894* `~/.claude/settings.json` applies to all your projects. On Windows the path is `%USERPROFILE%\.claude\settings.json`
9995* `.claude/settings.local.json` applies to one project. Claude Code adds it to your global gitignore when it saves a setting there; if you create it by hand or have Claude write it, add it to your gitignore yourself first so you don't accidentally commit your credential
10096
101<Warning>
102 Don't put the credential in a project's `.claude/settings.json`. That file is committed and shared with everyone who clones the repository.
103</Warning>
97> [!WARNING]
98>
99> Don't put the credential in a project's `.claude/settings.json`. That file is committed and shared with everyone who clones the repository.
104100
105101The `env` block looks the same in either file:
106102
from line 115
119115
120116With the variables exported in your shell, send a one-token request to the gateway directly. This confirms the URL and credential work before you open Claude Code, so a failure points at the gateway rather than your configuration. The commands below read the shell variables, so they need the [shell exports](#set-as-shell-environment-variables) even if you also put the values in a settings file.
121117
122<Tabs>
123 <Tab title="Bash or Zsh">
124 ```bash theme={null}
125 curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
126 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
127 -H "anthropic-version: 2023-06-01" \
128 -H "content-type: application/json" \
129 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
130 ```
131 </Tab>
118**Bash or Zsh**
132119
133 <Tab title="PowerShell">
134 ```powershell theme={null}
135 Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
136 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
137 -ContentType "application/json" `
138 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
139 ```
140 </Tab>
141</Tabs>
120```bash theme={null}
121curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
122 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
123 -H "anthropic-version: 2023-06-01" \
124 -H "content-type: application/json" \
125 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
126```
142127
128**PowerShell**
129
130```powershell theme={null}
131Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
132 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
133 -ContentType "application/json" `
134 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
135```
136
143137If your gateway expects keys in the `x-api-key` header, replace the `Authorization` header with `x-api-key: $ANTHROPIC_API_KEY` in the Bash command, or the `"Authorization"` hashtable entry with `"x-api-key" = "$env:ANTHROPIC_API_KEY"` in the PowerShell command.
144138
145139A JSON response that starts with `{"id":"msg_` and includes a `"content":[...]` field means the gateway is reachable and the credential works. An error naming an unknown model still proves the URL and credential work, since the gateway authenticated the request before rejecting the model name; you don't need to find a model your gateway serves for this test. A `401` means the credential was rejected: if you guessed the variable, switch to the other one and re-export.
from line 229
235229* TypeScript: the spawned process inherits the parent environment by default, but setting `options.env` replaces the environment entirely. Spread `process.env` into it to keep your gateway variables.
236230* Python: `ClaudeAgentOptions(env=...)` merges on top of the inherited environment, so gateway variables set in the parent process carry through without spreading.
237231
238<CodeGroup>
239 ```ts TypeScript theme={null}
240 const result = query({
241 prompt: "...",
242 options: {
243 env: {
244 ...process.env,
245 ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
246 ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
247 },
232```ts TypeScript theme={null}
233const result = query({
234 prompt: "...",
235 options: {
236 env: {
237 ...process.env,
238 ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
239 ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
248240 },
249 })
250 ```
241 },
242})
243```
251244
252 ```python Python theme={null}
253 options = ClaudeAgentOptions(
254 env={
255 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
256 "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
257 }
258 )
259 ```
260</CodeGroup>
245```python Python theme={null}
246options = ClaudeAgentOptions(
247 env={
248 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
249 "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
250 }
251)
252```
261253
262254### Slack, cloud sessions, and Remote Control
263255
from line 270
278270
279271Some gateways route or tag requests using a custom header in addition to the credential, for example a tenant identifier or a routing key. To send one, set [`ANTHROPIC_CUSTOM_HEADERS`](/docs/en/env-vars) with one `Name: Value` pair per line. The example below adds a routing header named `X-Org-Route`:
280272
281<Tabs>
282 <Tab title="Bash or Zsh">
283 ```bash theme={null}
284 export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
285 ```
286 </Tab>
273**Bash or Zsh**
287274
288 <Tab title="PowerShell">
289 ```powershell theme={null}
290 $env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
291 ```
292 </Tab>
293</Tabs>
275```bash theme={null}
276export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
277```
294278
279**PowerShell**
280
281```powershell theme={null}
282$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
283```
284
295285You can also set `ANTHROPIC_CUSTOM_HEADERS` in the `env` block of a settings file. Use `\n` between pairs there, since JSON strings can't span multiple lines:
296286
297287```json theme={null}
from line 314
324314
325315The helper is any shell command that prints the current credential to stdout. Claude Code runs it through your system shell, so on Windows it can be an executable or a PowerShell invocation. Make the command print nothing but the credential. On Claude Code v2.1.227 or later, a banner or a log line printed alongside the key makes the [helper fail](/docs/en/errors#your-apikeyhelper-script-is-failing). Write the script, make it executable, and reference it from `apiKeyHelper` in your [settings file](/docs/en/settings):
326316
327<Tabs>
328 <Tab title="Bash or Zsh">
329 For example, a script that reads from a vault:
317**Bash or Zsh**
330318
331 ```bash theme={null}
332 #!/bin/bash
333 vault kv get -field=api_key secret/llm-gateway/claude-code
334 ```
319For example, a script that reads from a vault:
335320
336 Reference its path in `~/.claude/settings.json`:
321```bash theme={null}
322#!/bin/bash
323vault kv get -field=api_key secret/llm-gateway/claude-code
324```
337325
338 ```json theme={null}
339 {
340 "apiKeyHelper": "~/bin/get-gateway-key.sh"
341 }
342 ```
343 </Tab>
326Reference its path in `~/.claude/settings.json`:
344327
345 <Tab title="PowerShell">
346 For example, a script that reads from a vault:
328```json theme={null}
329{
330 "apiKeyHelper": "~/bin/get-gateway-key.sh"
331}
332```
347333
348 ```powershell theme={null}
349 vault kv get -field=api_key secret/llm-gateway/claude-code
350 ```
334**PowerShell**
351335
352 Reference the PowerShell invocation in `%USERPROFILE%\.claude\settings.json`, escaping the backslashes in the JSON string:
336For example, a script that reads from a vault:
353337
354 ```json theme={null}
355 {
356 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
357 }
358 ```
359 </Tab>
360</Tabs>
338```powershell theme={null}
339vault kv get -field=api_key secret/llm-gateway/claude-code
340```
361341
342Reference the PowerShell invocation in `%USERPROFILE%\.claude\settings.json`, escaping the backslashes in the JSON string:
343
344```json theme={null}
345{
346 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
347}
348```
349
362350Claude Code caches the helper's output for five minutes by default and re-runs the helper after the cache lifetime elapses. To change the lifetime, set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` in milliseconds, for example `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` for 15 minutes.
363351
364352See [`apiKeyHelper`](/docs/en/settings-reference#apikeyhelper) for the other cases in which Claude Code re-runs the helper.
from line 361
373361
374362To turn that traffic off, set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` alongside the gateway variables, in the same shell exports or settings-file `env` block:
375363
376<Tabs>
377 <Tab title="Bash or Zsh">
378 ```bash theme={null}
379 export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
380 ```
381 </Tab>
364**Bash or Zsh**
382365
383 <Tab title="PowerShell">
384 ```powershell theme={null}
385 $env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
386 ```
387 </Tab>
388</Tabs>
366```bash theme={null}
367export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
368```
389369
370**PowerShell**
371
372```powershell theme={null}
373$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
374```
375
390376Setting the variable has these effects and limits:
391377
392378* It disables auto-updates, so plan for another update path, such as your package manager or managed distribution.
from line 396
410396
411397Leave `AWS_BEARER_TOKEN_BEDROCK` unset when the gateway issues its own credential. If you set it, Claude Code sends that [Amazon Bedrock API key](/docs/en/amazon-bedrock#2-configure-aws-credentials) as the `Authorization` header instead of your gateway token, even with `CLAUDE_CODE_SKIP_BEDROCK_AUTH` set.
412398
413<Tabs>
414 <Tab title="Bash or Zsh">
415 ```bash theme={null}
416 export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
417 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
418 export CLAUDE_CODE_USE_BEDROCK=1
419 ```
420 </Tab>
399**Bash or Zsh**
421400
422 <Tab title="PowerShell">
423 ```powershell theme={null}
424 $env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
425 $env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
426 $env:CLAUDE_CODE_USE_BEDROCK = "1"
427 ```
428 </Tab>
429</Tabs>
401```bash theme={null}
402export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
403export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
404export CLAUDE_CODE_USE_BEDROCK=1
405```
430406
407**PowerShell**
408
409```powershell theme={null}
410$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
411$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
412$env:CLAUDE_CODE_USE_BEDROCK = "1"
413```
414
431415#### Google Cloud's Agent Platform
432416
433417Replace the project ID and region with your own values. Claude Code includes both in the path of each request it sends to the gateway:
434418
435<Tabs>
436 <Tab title="Bash or Zsh">
437 ```bash theme={null}
438 export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
439 export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
440 export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
441 export CLAUDE_CODE_USE_VERTEX=1
442 export CLOUD_ML_REGION=us-east5
443 ```
444 </Tab>
419**Bash or Zsh**
445420
446 <Tab title="PowerShell">
447 ```powershell theme={null}
448 $env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
449 $env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
450 $env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
451 $env:CLAUDE_CODE_USE_VERTEX = "1"
452 $env:CLOUD_ML_REGION = "us-east5"
453 ```
454 </Tab>
455</Tabs>
421```bash theme={null}
422export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
423export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
424export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
425export CLAUDE_CODE_USE_VERTEX=1
426export CLOUD_ML_REGION=us-east5
427```
456428
429**PowerShell**
430
431```powershell theme={null}
432$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
433$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
434$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
435$env:CLAUDE_CODE_USE_VERTEX = "1"
436$env:CLOUD_ML_REGION = "us-east5"
437```
438
457439The block covers routing and authentication. The region overrides and model pins from the [Agent Platform setup](/docs/en/google-vertex-ai#4-configure-claude-code) apply through a gateway as well:
458440
459441* **Per-model regions**: if your gateway serves some models from a region other than `CLOUD_ML_REGION`, set the matching `VERTEX_REGION_CLAUDE_*` variable for each, for example `VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1`. The [environment variables reference](/docs/en/env-vars) lists the exact names.
from line 448
466448
467449For a gateway that injects its own `Authorization` header, set `CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1` and leave both credential variables unset. Claude Code then sends requests without an Azure credential and preserves the `Authorization` header you supply, for example through `ANTHROPIC_CUSTOM_HEADERS`.
468450
469<Tabs>
470 <Tab title="Bash or Zsh">
471 ```bash theme={null}
472 export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
473 export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
474 export CLAUDE_CODE_USE_FOUNDRY=1
475 ```
476 </Tab>
451**Bash or Zsh**
477452
478 <Tab title="PowerShell">
479 ```powershell theme={null}
480 $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
481 $env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
482 $env:CLAUDE_CODE_USE_FOUNDRY = "1"
483 ```
484 </Tab>
485</Tabs>
453```bash theme={null}
454export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
455export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
456export CLAUDE_CODE_USE_FOUNDRY=1
457```
486458
459**PowerShell**
460
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
487467#### Claude Platform on AWS
488468
489469See [Claude Platform on AWS](/docs/en/claude-platform-on-aws) for the workspace ID.
490470
491<Tabs>
492 <Tab title="Bash or Zsh">
493 ```bash theme={null}
494 export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
495 export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
496 export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
497 export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
498 ```
499 </Tab>
471**Bash or Zsh**
500472
501 <Tab title="PowerShell">
502 ```powershell theme={null}
503 $env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
504 $env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
505 $env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
506 $env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"
507 ```
508 </Tab>
509</Tabs>
473```bash theme={null}
474export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
475export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
476export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
477export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
478```
479
480**PowerShell**
481
482```powershell theme={null}
483$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
484$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
485$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
486$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"
487```
510488
511489#### Confirm the provider route
512490
No line in this hunk matches that.