將 Claude Code 連接到 LLM 閘道

將 Claude Code 指向您組織的 LLM 閘道。檢查您的管理員是否已配置它，或自行設定基礎 URL 和認證，然後驗證連接並修復閘道錯誤。

LLM 閘道是您的組織在 Claude Code 和模型提供者之間運行的代理。當您的組織使用閘道時，Claude Code 使用您的組織簽發的認證向閘道進行身份驗證，而不是使用您個人的 claude.ai 登入。

本頁面適用於通過其組織運行的閘道運行 Claude Code 的開發人員。它涵蓋兩個路徑：檢查您的管理員是否已為您配置它，以及在他們未配置時自行配置。

[!NOTE]

• 要為您的組織部署閘道，請參閱推出 LLM 閘道
• 有關 Claude Code 發送到閘道的內容，請參閱閘道相容性指南

檢查現有配置

管理員可以通過受管設定、裝置管理或 apiKeyHelper 分發閘道地址和認證，因此 Claude Code 在啟動時會自動獲取它們，無需您進行任何設定。要檢查您的組織是否已執行此操作：

1. 啟動 Claude Code

執行 claude。如果它打開登入畫面而不是會話，則未分發閘道認證；自行配置如下。

2. 檢查狀態標籤

如果 Claude Code 啟動了會話而未顯示登入畫面，執行 /status，打開狀態標籤，並檢查兩行：

• Anthropic base URL：此行僅在設定了閘道地址時出現。如果不存在，Claude Code 未指向閘道；自行配置如下。
• Auth token 或 API key：命名 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 或 apiKeyHelper 的行確認閘道認證處於活動狀態。命名 claude.ai 帳戶的 Login method 行表示認證未被分發；自行設定。

3. 發送測試訊息

關閉 /status 選單並在 Claude Code 中發送任何提示。來自 Claude 的正常回應（無錯誤）確認閘道連接有效。

如果 /status 選單中的兩行看起來都正確，但向 Claude 發送的訊息失敗，請參閱故障排除表。

自行配置 Claude Code

要自行為閘道配置 Claude Code，您需要從閘道團隊獲得：

• 閘道的基礎 URL
• 認證：金鑰或令牌字符串，或獲取認證的命令
  • 如果您的閘道團隊未說明認證的類型，下面的認證變數部分涵蓋了要嘗試的內容

下面的部分按順序涵蓋配置：

• 設定認證變數和設定基礎 URL：每個閘道連接需要的兩個變數
• 驗證連接：在保存任何內容之前確認它有效
• 配置每個介面：如果您使用除 Claude Code CLI 之外的介面（例如 VS Code），請查看如何使用閘道認證配置它
• 其他配置：某些閘道除了基礎 URL 和認證之外還需要的變數，例如自訂標頭、認證幫助程式、模型發現、提供者格式的基礎 URL 或關閉閘道路徑外的流量。僅在您的管理員命名它們或您的網路限制出站流量時設定這些

設定認證變數

要向閘道驗證 Claude Code，請在環境變數中設定您的認證。哪個變數取決於您的閘道團隊告訴您的內容：

如果您未被告知是哪種類型，請使用 ANTHROPIC_AUTH_TOKEN；下面的驗證請求顯示如何判斷您是否需要切換。

設定基礎 URL 和認證

將閘道的基礎 URL 和您上面選擇的認證變數設定為環境變數。示例使用 ANTHROPIC_AUTH_TOKEN；如果那是您選擇的變數，請將其替換為 ANTHROPIC_API_KEY。您可以在您的 shell 中設定它們（持續一個終端會話），或在 Claude Code 設定檔案中設定它們（在 Claude Code 運行的任何地方持續）。

對於您的第一次連接，從 shell 匯出開始，並在將值移動到設定檔案之前執行驗證請求。

設定為 shell 環境變數

將值替換為您的閘道團隊提供的值：

[tab] Bash or Zsh

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

[tab] PowerShell

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

Shell 匯出僅適用於該終端會話和從它啟動的程式。從 dock 或開始功能表啟動的編輯器將看不到它們。要使它們在新終端中持續，請將相同的行添加到您的 shell 配置檔案，例如 ~/.zshrc、~/.bashrc 或您的 PowerShell $PROFILE。

如果您只在 shell 中匯出閘道，它不會可靠地到達由監督程式託管的背景代理；請參閱每個背景會話如何獲取其閘道。對於背景代理必須始終路由的任何閘道，請使用設定檔案。

在設定檔案中設定

要使配置在 Claude Code 運行的任何地方應用，包括背景代理，請在設定檔案的 env 區塊中設定變數，而不是依賴您的 shell。設定檔案有不同的範圍：

• ~/.claude/settings.json 適用於您的所有專案。在 Windows 上，路徑是 %USERPROFILE%\.claude\settings.json
• .claude/settings.local.json 適用於一個專案。Claude Code 在建立檔案時將其添加到您的全域 gitignore；如果您自己建立它或讓 Claude 寫入它，請先手動將其添加到 gitignore，以免您不小心提交您的認證

[!WARNING]

不要將認證放在專案的 .claude/settings.json 中。該檔案已提交並與克隆存儲庫的所有人共享。

env 區塊在任一檔案中看起來都相同：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
  }
}

當 shell 匯出和設定檔案 env 區塊都設定相同的變數時，設定檔案值適用。執行 /status 以查看 Claude Code 使用的基礎 URL 和認證來源。

驗證連接

使用在 shell 中匯出的變數，向閘道直接發送一個單令牌請求。這在您打開 Claude Code 之前確認 URL 和認證有效，因此失敗指向閘道而不是您的配置。下面的命令讀取 shell 變數，因此即使您也將值放在設定檔案中，它們也需要shell 匯出。

[tab] Bash or Zsh

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

[tab] PowerShell

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

如果您的閘道期望 x-api-key 標頭中的金鑰，請在 Bash 命令中將 Authorization 標頭替換為 x-api-key: $ANTHROPIC_API_KEY，或在 PowerShell 命令中將 "Authorization" 雜湊表項目替換為 "x-api-key" = "$env:ANTHROPIC_API_KEY"。

以 {"id":"msg_ 開頭並包含 "content":[...] 欄位的 JSON 回應表示閘道可達且認證有效。命名未知模型的錯誤仍然證明 URL 和認證有效，因為閘道在拒絕模型名稱之前驗證了請求；您不需要為此測試找到您的閘道提供的模型。401 表示認證被拒絕：如果您猜測了變數，請切換到另一個並重新匯出。

在 Claude Code 中確認

從同一 shell 啟動 claude，以便它繼承匯出，發送訊息，並執行 /status。

在狀態標籤上，Anthropic base URL 行應顯示您的閘道地址，這確認請求正在路由到那裡；如果該行不存在，變數未到達會話。命名您設定的變數的 Auth token 或 API key 行確認閘道認證處於活動狀態，而不是已保存的 claude.ai 登入。

如果訊息失敗或 /status 未顯示閘道 URL，請參閱下面的故障排除表。

認證變數如何映射到標頭

每個變數在不同的 HTTP 標頭中發送認證：ANTHROPIC_AUTH_TOKEN 在 Authorization: Bearer 中，ANTHROPIC_API_KEY 在 x-api-key 中，apiKeyHelper 在兩者中。錯誤變數中的認證到達閘道時位於它不讀取的標頭中，請求失敗並返回 401。如果驗證請求返回 401，請切換到另一個變數並重試。

與現有登入的衝突

閘道憑證變數優先於已保存的 claude.ai 登入或 Console 金鑰。使用 ANTHROPIC_AUTH_TOKEN 時，該變數會立即優先生效。使用 ANTHROPIC_API_KEY 時，系統會在互動模式下提示您一次以核准該金鑰，之後才會由其接管。

執行 /status 以確認哪個認證來源處於活動狀態。如果啟動顯示命名兩個來源的身份驗證衝突警告，請參閱故障排除表的第一行以了解要刪除哪一個。要清除已保存的登入，以便只有閘道認證保留，請執行 /logout。

配置每個介面

CLI 讀取上面的環境變數和設定檔案。其他介面是 VS Code 擴充功能、桌面應用程式、GitHub Actions、Agent SDK 和雲端介面（例如 Slack 和網頁）；下面的部分涵蓋這些設定是否到達每一個。

VS Code 擴充功能

在 VS Code 自己的使用者設定中的 claudeCode.environmentVariables 中為 VS Code 擴充功能設定閘道變數，使用偏好設定：開啟使用者設定 (JSON) 命令打開。擴充功能在啟動前檢查此設定中的認證，因此這是閘道認證的可靠位置；~/.claude/settings.json 中的值到達生成的程序但不到達擴充功能自己的登入檢查。

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
  ]
}

桌面應用程式

桌面應用程式從其第三方推論配置讀取閘道路由，而不是從 ANTHROPIC_BASE_URL 或 settings.json。該配置可以來自您的組織或來自應用程式本身的表單：

• 由管理員分發：如果您的組織已部署配置，桌面應用程式通過閘道路由，無需您進行任何設定
• 本地配置：對於沒有管理員分發配置的裝置，打開說明 → 疑難排解 → 啟用開發人員模式，這會使用開發人員功能表重新啟動應用程式。然後打開開發人員 → 配置第三方推論並輸入您的閘道基礎 URL。管理員分發的配置優先，並使此表單為唯讀

啟用閘道設定後，環境選擇器不會提供 Anthropic 託管的雲端環境，且 Remote Control 無法使用。

在閘道設定下，SSH 工作階段目前為 beta 版，且需要 Claude Desktop v1.40609.0 或更新版本。連線前，請檢查允許清單和閘道的位址：

• 允許的主機：SSH 工作階段預設為關閉。若要開啟，您或您的管理員需在第三方推論設定的 sshHostAllowlist 鍵中列出允許的主機
• 閘道位址：遠端機器會自行連線到閘道，因此位於您電腦上 localhost 的閘道無法用於 SSH 工作階段

請參閱 SSH remote sessions in Claude Desktop on 3P。您也可以在遠端主機上執行 CLI，並在該處設定 ANTHROPIC_BASE_URL 和閘道憑證。

如果桌面應用程式顯示 Gateway was unreachable，應用程式在啟動時無法到達配置的基礎 URL；使用上面的 curl 測試檢查 URL 和網路路徑。

GitHub Actions

Claude Code GitHub Actions 從工作流程的 env 區塊讀取 ANTHROPIC_BASE_URL 和 ANTHROPIC_CUSTOM_HEADERS。將認證作為操作的 anthropic_api_key 輸入傳遞；操作將其設定為 ANTHROPIC_API_KEY，因此它到達 x-api-key 標頭中的閘道。

對於 x-api-key 閘道，在 env 中設定基礎 URL 並將閘道金鑰作為輸入傳遞：

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

對於 bearer 令牌閘道，將相同的密鑰作為 anthropic_api_key 輸入和工作流程 env 區塊中的 ANTHROPIC_AUTH_TOKEN 傳遞。操作在啟動 Claude Code 之前需要 anthropic_api_key、CLAUDE_CODE_OAUTH_TOKEN 或工作負載身份聯合，並且它不讀取 ANTHROPIC_AUTH_TOKEN，因此輸入只是為了滿足該啟動檢查。env 變數是將金鑰放在閘道讀取的 Authorization 標頭中的原因；x-api-key 中的副本被忽略：

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

有關操作的其他身份驗證選項，包括 CLAUDE_CODE_OAUTH_TOKEN 和工作負載身份聯合，請參閱 Claude Code GitHub Actions 和操作的 README。

Agent SDK

Agent SDK 沒有閘道特定的選項；它將環境變數傳遞給它生成的 Claude Code 程序。每個 SDK 接受一個 env 選項，用於設定生成的程序的環境，TypeScript 和 Python SDK 以不同的方式處理它：

• TypeScript：生成的程序預設繼承父環境，但設定 options.env 會完全替換環境。將 process.env 擴展到其中以保留您的閘道變數。
• Python：ClaudeAgentOptions(env=...) 合併到繼承的環境之上，因此在父程序中設定的閘道變數無需擴展即可通過。

const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
        "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
    }
)

Slack、雲端會話和遠端控制

Slack 中的 Claude Code 和雲端工作階段不屬於閘道部署的一部分。在雲端工作階段的環境設定中設定的閘道變數不會套用。如果您的流量必須保留在閘道上，請不要為這些使用者啟用這些使用介面。

Remote Control 和語音聽寫都依賴於 claude.ai 身分：Remote Control 用於將即時工作階段與您的帳戶配對，語音聽寫用於到達 claude.ai 轉錄端點。當 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 處於活動狀態時，它們無法使用。Remote Control 在 ANTHROPIC_BASE_URL 指向非 Anthropic 主機時也會被停用，因此僅使用 claude.ai 登入本身是不夠的。

若要還原任一功能，請使用 claude.ai 登入並取消設定該功能檢查的閘道變數。claude doctor 的遠端控制部分命名目前阻止遠端控制的內容。

• 語音聽寫：取消設定閘道認證
• 遠端控制：取消設定閘道認證和 ANTHROPIC_BASE_URL

其他設定

這些設定涵蓋基礎 URL 與憑證以外的情況。僅在管理員的指示、網路的輸出規則或疑難排解表要求時才需設定。

傳送額外的標頭

部分閘道除了憑證之外，還會使用自訂標頭來路由或標記請求，例如租戶識別碼或路由金鑰。若要傳送此類標頭，請設定 ANTHROPIC_CUSTOM_HEADERS，每行一組 Name: Value。以下範例新增一個名為 X-Org-Route 的路由標頭：

[tab] Bash 或 Zsh

export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"

[tab] PowerShell

$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"

您也可以在設定檔的 env 區塊中設定 ANTHROPIC_CUSTOM_HEADERS。由於 JSON 字串無法跨越多行，因此在該處請以 \n 分隔各組：

{
  "env": {
    "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: example"
  }
}

像這類路由與租戶標頭名稱屬於需要核准的標頭。當標頭來自專案設定檔時，Claude Code 會依照套用 env 值的時機規則套用這些標頭。

將閘道模型新增至模型選擇器

啟用模型探索後，Claude Code 會在啟動時向閘道查詢其模型清單，並將這些名稱與內建項目一併加入 /model 選擇器。若您或您的管理員在 modelPicker 清單中設定了 replaceBuiltInOptions，Claude Code 也會隱藏探索到的名稱。但它會保留目前工作階段正在使用之模型的項目。

若您的閘道提供不在 Claude Code 內建清單中的模型名稱，而您希望從選擇器中選取這些模型，請啟用此功能。若您使用的是內建模型，則不需要探索功能；您的管理員也可能已透過受管設定啟用此功能。

若要啟用，請在 shell 中或 ~/.claude/settings.json 的 env 區塊中設定 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。

探索到的模型會以額外的 /model 項目顯示。每個項目會顯示閘道為該模型提供的描述，若閘道未提供描述，則顯示 From gateway。

若要確認探索已執行，請啟動 claude --debug，並在 ~/.claude/debug/<session-id>.txt 的偵錯日誌中尋找 [gatewayDiscovery] 行。探索首次成功時，Claude Code 會記錄其快取了多少個模型，之後僅在閘道清單變更時才會再次記錄。404、逾時或重新導向也會出現在該處。關於探索的執行時機、其篩選的內容，以及閘道提供的回應格式，請參閱模型探索參考。

使用 apiKeyHelper 輪替憑證

apiKeyHelper 是 Claude Code 執行以取得閘道憑證的命令，取代從靜態環境變數讀取憑證的方式。

當憑證會定期到期、來自保管庫或 SSO 命令，或管理員要求您設定時，請使用 helper。若您的憑證是只需設定一次的固定字串，則僅需憑證變數即可，可略過本節。

helper 可以是任何將目前憑證輸出至 stdout 的 shell 命令。Claude Code 會透過系統 shell 執行它，因此在 Windows 上它可以是可執行檔或 PowerShell 呼叫。請讓該命令只輸出憑證，不輸出其他任何內容。在 Claude Code v2.1.227 或更新版本中，若與金鑰一併輸出橫幅或日誌行，會導致 helper 失敗。撰寫指令碼、將其設為可執行，並在設定檔中從 apiKeyHelper 參照它：

[tab] Bash 或 Zsh

例如，一個從保管庫讀取的指令碼：

#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code

在 ~/.claude/settings.json 中參照其路徑：

{
  "apiKeyHelper": "~/bin/get-gateway-key.sh"
}

[tab] PowerShell

例如，一個從保管庫讀取的指令碼：

vault kv get -field=api_key secret/llm-gateway/claude-code

在 %USERPROFILE%\.claude\settings.json 中參照該 PowerShell 呼叫，並在 JSON 字串中跳脫反斜線：

{
  "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}

Claude Code 預設會將 helper 的輸出快取五分鐘，並在快取有效期限過後重新執行 helper。若要變更有效期限，請以毫秒為單位設定 CLAUDE_CODE_API_KEY_HELPER_TTL_MS，例如 CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000 代表 15 分鐘。

關於 Claude Code 重新執行 helper 的其他情況，請參閱 apiKeyHelper。

helper 的值會同時在 Authorization 與 x-api-key 標頭中傳送，因此無論閘道讀取哪個標頭都能運作。

關閉閘道路徑以外的流量

閘道負責傳送模型請求，但 Claude Code 也會在閘道路徑之外，向 Anthropic 以及 GitHub 等第三方服務傳送非必要的背景流量：版本檢查、遙測、版本說明及類似請求。在僅允許輸出至閘道的網路上，這些請求會失敗，並可能在輸出監控中顯示為遭封鎖的連線。

若要關閉這些流量，請在與閘道變數相同的 shell export 或設定檔 env 區塊中，一併設定 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1：

[tab] Bash 或 Zsh

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

[tab] PowerShell

$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

設定此變數有以下效果與限制：

• 它會停用自動更新，因此請規劃其他更新途徑，例如套件管理員或受管發佈。
• 它會抑制快速模式的可用性檢查。在 Anthropic API 上，若 /fast 因此回報快速模式無法使用，請參閱在代理伺服器與 LLM 閘道後方使用快速模式以還原快速模式。
• 它不會影響閘道模型探索，因為探索僅查詢您的閘道。在 v2.1.257 之前，此變數也會阻止探索重新整理，因此選擇器會保留先前快取的清單。
• WebFetch 工具的網域安全檢查不受影響，仍會呼叫 api.anthropic.com。若您的網路封鎖該主機，請在設定中另外以 skipWebFetchPreflight: true 將其關閉。
• 關於各個遙測串流及控制它的變數，請參閱遙測服務。

透過閘道路由至雲端供應商

這些設定會透過供應商專屬的基礎 URL 變數（取代 ANTHROPIC_BASE_URL）將 Claude Code 指向閘道。Amazon Bedrock 與 Google Cloud's Agent Platform 閘道接受這些供應商的原生請求格式；Microsoft Foundry 與 Claude Platform on AWS 閘道則接受 Anthropic Messages 格式。在 Amazon Bedrock 與 Google Cloud's Agent Platform 路由上，Claude Code 也會將其傳送的 beta 標頭與請求欄位限制為該供應商接受的集合。關於閘道在各路由上收到的內容，請參閱閘道相容性指南。

僅在閘道團隊明確指定 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 時才使用這些設定。若上方的驗證請求傳回了 JSON，則可略過本節。

請設定閘道團隊所指定供應商的區塊。Amazon Bedrock、Google Cloud's Agent Platform 與 Claude Platform on AWS 區塊中的略過驗證變數會告知 Claude Code 不要以雲端供應商的憑證簽署請求，因為這些憑證由閘道持有。若閘道本身也需要 token，其放置位置取決於供應商：

• Amazon Bedrock、Google Cloud's Agent Platform 或 Claude Platform on AWS：在區塊之後加入 ANTHROPIC_AUTH_TOKEN。Claude Code 會將其以 Authorization: Bearer 標頭傳送至閘道。若憑證使用不同的驗證方式或標頭，請改用 ANTHROPIC_CUSTOM_HEADERS。無論哪種情況，都請保留略過驗證變數的設定，因為若未設定，Claude Code 會移除 ANTHROPIC_AUTH_TOKEN、apiKeyHelper 或 ANTHROPIC_CUSTOM_HEADERS 原本會加入的任何 Authorization 標頭。
• Microsoft Foundry：依照其區塊所示使用 ANTHROPIC_FOUNDRY_API_KEY

Amazon Bedrock

當閘道核發自己的憑證時，請勿設定 AWS_BEARER_TOKEN_BEDROCK。若設定了它，即使已設定 CLAUDE_CODE_SKIP_BEDROCK_AUTH，Claude Code 仍會以該 Amazon Bedrock API 金鑰作為 Authorization 標頭傳送，而非您的閘道 token。

[tab] Bash 或 Zsh

export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1

[tab] PowerShell

$env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
$env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
$env:CLAUDE_CODE_USE_BEDROCK = "1"

Google Cloud's Agent Platform

請將專案 ID 與區域替換為您自己的值。Claude Code 會在傳送至閘道的每個請求路徑中包含這兩者：

[tab] Bash 或 Zsh

export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5

[tab] PowerShell

$env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
$env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
$env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
$env:CLAUDE_CODE_USE_VERTEX = "1"
$env:CLOUD_ML_REGION = "us-east5"

此區塊涵蓋路由與身分驗證。Agent Platform 設定中的區域覆寫與模型固定設定，透過閘道時同樣適用：

• 個別模型區域：若閘道從 CLOUD_ML_REGION 以外的區域提供某些模型，請為每個模型設定對應的 VERTEX_REGION_CLAUDE_* 變數，例如 VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1。環境變數參考列出了確切名稱。
• 模型版本：依照固定模型版本中的說明固定 ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 與 ANTHROPIC_DEFAULT_HAIKU_MODEL。設定 ANTHROPIC_DEFAULT_HAIKU_MODEL 也會將工作階段標題等背景任務移至該模型，該節也說明了在其他情況下由哪個模型執行這些任務。
• 模型功能：若您固定的模型 ID 是您的 Claude Code 版本無法辨識的，effort 等級或延伸思考等功能可能會在該模型上維持停用。請使用 ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES 及其 Sonnet 與 Haiku 對應變數宣告模型支援的功能。

Microsoft Foundry

將閘道的憑證放入 ANTHROPIC_FOUNDRY_API_KEY；它會以 x-api-key 標頭傳送至閘道。預期接收 bearer token 的閘道可改用 ANTHROPIC_FOUNDRY_AUTH_TOKEN。Claude Code 會將該值以 Authorization: Bearer 標頭傳送，且兩者皆設定時，它優先於 ANTHROPIC_FOUNDRY_API_KEY。需要 Claude Code v2.1.203 或更新版本。

若閘道會注入自己的 Authorization 標頭，請設定 CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1，並讓兩個憑證變數都保持未設定。Claude Code 便會在不附帶 Azure 憑證的情況下傳送請求，並保留您提供的 Authorization 標頭，例如透過 ANTHROPIC_CUSTOM_HEADERS 提供的標頭。

[tab] Bash 或 Zsh

export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
export CLAUDE_CODE_USE_FOUNDRY=1

[tab] PowerShell

$env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
$env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

Claude Platform on AWS

關於工作區 ID，請參閱 Claude Platform on AWS。

[tab] Bash 或 Zsh

export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
export CLAUDE_CODE_USE_ANTHROPIC_AWS=1

[tab] PowerShell

$env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
$env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
$env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
$env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"

確認供應商路由

從設定該區塊的 shell 啟動 claude，然後執行 /status。使用 Amazon Bedrock 區塊時，Status 分頁會顯示如下的列：

API provider: Amazon Bedrock
Bedrock base URL: https://llm-gateway.example.com/bedrock
AWS auth skipped

其他區塊會以其供應商名稱產生相同的列，例如 Google Cloud's Agent Platform 會顯示 Vertex base URL 與 GCP auth skipped；Microsoft Foundry 區塊僅在您設定了 CLAUDE_CODE_SKIP_FOUNDRY_AUTH 時才會顯示略過驗證的列。若您也透過企業代理伺服器進行路由，Proxy 列會顯示代理伺服器 URL。若缺少基礎 URL 列，表示該變數未傳入工作階段。

故障排除閘道錯誤

這些是通過閘道運行 Claude Code 時最常見的錯誤，包括閘道端的原因和修復：

如果 Claude Code 在移除閘道配置後重複提示您登入，原因通常是認證存儲而不是閘道；請參閱身份驗證錯誤。

相關資源

• LLM 閘道概述：什麼是閘道以及它如何與 claude.ai 訂閱互動
• 為您的組織推出 LLM 閘道：部署和分發閘道配置的面向管理員的檢查清單
• 閘道協議參考：Claude Code 發送到閘道的內容，包括閘道必須轉發的標頭和欄位
• 設定：設定檔案的位置以及如何讀取 env 區塊
• 身份驗證：認證變數、apiKeyHelper 和 OAuth 登入如何互動