2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.
4 4
5# LLM gateway 設定5# LLM gateway
6 6
7> 了解如何設定 Claude Code 以使用 LLM gateway 解決方案。涵蓋 gateway 要求、身份驗證設定、模型選擇和提供商特定的端點設置。7> 透過 LLM gateway 路由 Claude Code 以進行集中身份驗證、使用情況追蹤和成本控制。涵蓋將 Claude Code 連接到 gateway、為您的組織推出 gateway、Claude Code 發送到 gateway 的內容，以及 gateway 如何與 claude.ai 訂閱互動。
8 8
9LLM gateway 提供了 Claude Code 和模型提供商之間的集中代理層，通常提供：9LLM gateway 是您的組織在 Claude Code 和模型提供商之間運行的代理。Claude Code 將 API 流量發送到 gateway，gateway 使用您的組織控制的憑證將其轉發給提供商。
10 10
11* **集中身份驗證** - 單一 API 金鑰管理點11此頁面涵蓋：
12* **使用情況追蹤** - 監控跨團隊和專案的使用情況
13* **成本控制** - 實施預算和速率限制
14* **審計日誌** - 追蹤所有模型互動以進行合規性檢查
15* **模型路由** - 無需更改程式碼即可在提供商之間切換
16 12
17此頁面涵蓋 Claude Code CLI 的 gateway 要求和設定。企業桌面部署可以透過[受管設定](https://support.claude.com/zh-TW/articles/12622667-enterprise-configuration)設定 gateway 提供商。Claude Desktop 應用程式也可以透過 [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/gateway) 針對自託管 gateway 執行，該預覽使用自己的設定金鑰。13* [gateway 提供的功能](#what-a-gateway-provides)
18 14* [路由和憑證如何運作](#how-a-gateway-works)
19<h2 id="gateway-requirements">15* [推出 gateway 的步驟](#roll-out-a-gateway)
20 Gateway 要求16* [gateway 如何與 claude.ai 訂閱互動](#subscriptions-and-gateways)
21</h2>17* [與 gateway 分開配置的內容](#configure-separately-from-the-gateway)
22
23為了讓 LLM gateway 與 Claude Code 配合使用，它必須滿足以下要求：
24
25**API 格式**
26
27gateway 必須向客戶端公開以下至少一種 API 格式：
28
291. **Anthropic Messages**: `/v1/messages`, `/v1/messages/count_tokens`
30 * 必須轉發請求標頭：`anthropic-beta`、`anthropic-version`
31
322. **Bedrock InvokeModel**: `/invoke`, `/invoke-with-response-stream`
33 * 必須保留請求正文字段：`anthropic_beta`、`anthropic_version`
34
353. **Vertex rawPredict**: `:rawPredict`、`:streamRawPredict`、`/count-tokens:rawPredict`
36 * 必須轉發請求標頭：`anthropic-beta`、`anthropic-version`
37
38未能轉發標頭或保留正文字段可能會導致功能減少或無法使用 Claude Code 功能。
39 18
40<Note>19<Note>
41 Claude Code 根據 API 格式確定要啟用的功能。使用 Bedrock 或 Vertex 的 Anthropic Messages 格式時，您可能需要設置環境變數 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。20 - 如果您是連接到現有 gateway 的開發人員：[將 Claude Code 連接到您的 gateway](/zh-TW/llm-gateway-connect)
21 - 如果您是為組織推出 gateway 的管理員：[部署和分發 gateway](/zh-TW/llm-gateway-rollout)
22 - 如果您正在配置 gateway 產品：[gateway 協議參考](/zh-TW/llm-gateway-protocol)
42</Note>23</Note>
43 24
44**請求標頭**25<h2 id="what-a-gateway-provides">
45 26 gateway 提供的功能
46Claude Code 在每個 API 請求上包含以下標頭：
47
48| 標頭 | 描述 |
49| :------------------------------ | :--------------------------------------------------------------------------------------------- |
50| `X-Claude-Code-Session-Id` | 當前 Claude Code 會話的唯一識別符。代理可以使用此識別符來聚合來自單個會話的所有 API 請求，而無需解析請求正文。 |
51| `X-Claude-Code-Agent-Id` | 發出請求的子代理或隊友的識別符。您的代理可以使用此識別符將 API 成本歸屬於會話內的個別並行子代理，而無需解析請求正文。僅針對由進程內子代理或隊友發出的請求出現。 |
52| `X-Claude-Code-Parent-Agent-Id` | 生成發出請求的代理的代理的識別符。將此與 `X-Claude-Code-Agent-Id` 一起使用，以在您的代理中跨嵌套代理歸屬 API 成本。僅當請求代理本身由另一個代理生成時才出現。 |
53
54兩個代理 ID 標頭都是每次生成的臨時識別符，而不是持久的用戶或設備 ID。
55
56Claude Code 還在系統提示前面添加了一個簡短的歸屬塊，其中包含客戶端版本和從對話派生的指紋。Anthropic API 在處理前會刪除此塊，因此不會影響第一方提示快取。如果您的 gateway 實現了自己的提示快取，其密鑰基於完整請求正文，請設置 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-TW/env-vars) 以省略它。
57
58<h2 id="configuration">
59 配置
60</h2>27</h2>
61 28
62<h3 id="model-selection">29gateway 為您的組織提供一個地方來管理：
63 模型選擇
64</h3>
65
66默認情況下，Claude Code 使用所選 API 格式的標準模型名稱。
67 30
68當 `ANTHROPIC_BASE_URL` 指向公開 Anthropic Messages 格式的 gateway 時，Claude Code 在啟動時會查詢 gateway 的 `/v1/models` 端點，並將返回的模型添加到 `/model` 選擇器中。設置 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 以啟用此功能。發現功能默認關閉，以便由共享 API 金鑰支持的 gateway 不會向每個用戶公開該金鑰可以訪問的每個模型。每個發現的條目都標記為「From gateway」，並在提供時使用響應中的 `display_name` 欄位。這需要 Claude Code v2.1.129 或更高版本。31* **憑證**：提供商金鑰保留在伺服器端；開發人員改為持有 gateway 憑證
32* **使用情況追蹤**：按開發人員或團隊歸屬使用情況，無論哪個提供商處理請求
33* **成本控制**：在一個地方強制執行預算和速率限制
34* **審計日誌**：記錄每個模型請求以進行合規性檢查
35* **提供商切換**：在 gateway 配置中更改提供商，無需觸及開發人員機器
69 36
70發現功能僅適用於 Anthropic Messages 格式。它不會針對 Bedrock 或 Vertex 傳遞端點運行，也不會在 `ANTHROPIC_BASE_URL` 未設置或指向 `api.anthropic.com` 時運行。37除了提供商切換外，所有這些都適用於上游是 Anthropic API 還是[雲提供商](/zh-TW/third-party-integrations)。
71 38
72發現請求的身份驗證方式與推理請求相同：它將 `ANTHROPIC_AUTH_TOKEN` 作為 bearer token 發送，或在未設置身份驗證令牌時將 `ANTHROPIC_API_KEY` 作為 `x-api-key` 標頭發送，以及來自 `ANTHROPIC_CUSTOM_HEADERS` 的任何標頭。只有 ID 以 `claude` 或 `anthropic` 開頭的模型才會添加到選擇器中。結果被緩存到 `~/.claude/cache/gateway-models.json`，並在每次啟動時刷新。如果請求失敗或 gateway 未實現 `/v1/models`，選擇器將回退到上次啟動時的緩存列表或內置模型列表。39權衡是 gateway 成為您的組織運營的基礎設施。Claude Code 在每個版本中添加功能，不轉發這些功能的 gateway 會破壞相應的功能，因此 gateway 產品需要隨著 Claude Code 的發展而保持更新。[gateway 協議參考](/zh-TW/llm-gateway-protocol)涵蓋要轉發的內容。
73 40
74如果您的 gateway 使用與發現篩選器不匹配的模型名稱，請使用 [模型配置](/zh-TW/model-config) 中記錄的環境變數手動添加它們。41<h2 id="how-a-gateway-works">
75 42 gateway 如何運作
76<h2 id="litellm-configuration">
77 LiteLLM 配置
78</h2>43</h2>
79 44
80<Warning>45默認情況下，Claude Code 直接向 Anthropic API 在 `api.anthropic.com` 發送請求。要透過 gateway 路由，請將 `ANTHROPIC_BASE_URL` 設置為 gateway 的地址；Claude Code 改為向那裡發送相同的請求。gateway 對開發人員進行身份驗證，附加您的組織的提供商憑證，並將每個請求轉發給它配置的任何提供商。
81 LiteLLM PyPI 版本 1.82.7 和 1.82.8 被盜竊憑證的惡意軟體破壞。請勿安裝這些版本。如果您已經安裝了它們：
82
83 * 移除該軟體包
84 * 輪換受影響系統上的所有憑證
85 * 按照 [BerriAI/litellm#24518](https://github.com/BerriAI/litellm/issues/24518) 中的補救步驟進行操作
86
87 LiteLLM 是第三方代理服務。Anthropic 不認可、維護或審計 LiteLLM 的安全性或功能。本指南僅供參考，可能會過時。請自行決定是否使用。
88</Warning>
89
90<h3 id="prerequisites">
91 先決條件
92</h3>
93
94* Claude Code 已更新至最新版本
95* LiteLLM Proxy Server 已部署且可訪問
96* 通過您選擇的提供商訪問 Claude 模型
97
98<h3 id="basic-litellm-setup">
99 基本 LiteLLM 設置
100</h3>
101
102**配置 Claude Code**：
103
104<h4 id="authentication-methods">
105 身份驗證方法
106</h4>
107 46
108<h5 id="static-api-key">47`ANTHROPIC_BASE_URL` 是大多數 gateway 的地址變數。面向特定雲提供商（如 Bedrock、Vertex、Foundry 或 AWS 上的 Claude Platform）的 gateway 改為使用該提供商的基本 URL 變數；[API 格式](/zh-TW/llm-gateway-protocol#api-formats)列出哪個變數與每個配置相關聯。
109 靜態 API 密鑰
110</h5>
111 48
112使用固定 API 密鑰的最簡單方法：49<Frame>
50 <img src="https://mintcdn.com/claude-code/zIcIE_SQv4Z0Zbhc/images/llm-gateway-flow.svg?fit=max&auto=format&n=zIcIE_SQv4Z0Zbhc&q=85&s=490607d033d235694efb49a73a5b9e4b" alt="顯示 Claude Code 透過 LLM gateway 路由的圖表。在開發人員機器區域中，Claude Code CLI、VS Code 擴展和 CI 或 Agent SDK 客戶端向 gateway 發送請求，gateway API 格式的基本 URL 變數指向它，每個開發人員持有每個開發人員的憑證，桌面應用程式透過組織分發的配置到達相同的 gateway。在標記為您的基礎設施的區域中，LLM gateway 處理身份驗證、使用情況追蹤、預算和路由，並使用您的組織的憑證轉發請求。在模型提供商區域中，實線箭頭指向您配置的提供商（顯示為 Anthropic API），虛線箭頭指向其他提供商選項，以 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 為例。" width="780" height="322" data-path="images/llm-gateway-flow.svg" />
51</Frame>
113 52
114```bash theme={null}53涉及兩種憑證：
115# 在環境中設置
116export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key
117 54
118# 或在 Claude Code 設置中55* **開發人員憑證**：每個開發人員持有自己的憑證，由 gateway 發行。它對 gateway 進行身份驗證，並在使用情況追蹤中識別他們
119{56* **提供商憑證**：gateway 為您的提供商帳戶持有一個憑證，由所有轉發的流量共享。您不需要為每個開發人員配置提供商金鑰
120 "env": {
121 "ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
122 }
123}
124```
125 57
126此值將作為 `Authorization` 標頭發送。58gateway 將每個請求轉發給您配置的提供商，例如 Anthropic API、[Amazon Bedrock](/zh-TW/amazon-bedrock)、[Google Vertex AI](/zh-TW/google-vertex-ai)、[Microsoft Foundry](/zh-TW/microsoft-foundry) 或 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws)。因為 Claude Code 只與 gateway 通信，提供商選擇是 gateway 的配置，而不是客戶端的。
127 59
128<h5 id="dynamic-api-key-with-helper">60<h2 id="roll-out-a-gateway">
129 使用幫助程序的動態 API 密鑰61 推出 gateway
130</h5>62</h2>
131
132用於輪換密鑰或按用戶身份驗證：
133
1341. 創建 API 密鑰幫助程序腳本：
135
136```bash theme={null}
137#!/bin/bash
138# ~/bin/get-litellm-key.sh
139
140# 示例：從保管庫獲取密鑰
141vault kv get -field=api_key secret/litellm/claude-code
142
143# 示例：生成 JWT 令牌
144jwt encode \
145 --secret="${JWT_SECRET}" \
146 --exp="+1h" \
147 '{"user":"'${USER}'","team":"engineering"}'
148```
149
1502. 配置 Claude Code 設置以使用幫助程序：
151
152```json theme={null}
153{
154 "apiKeyHelper": "~/bin/get-litellm-key.sh"
155}
156```
157
1583. 設置令牌刷新間隔：
159
160```bash theme={null}
161# 每小時刷新一次（3600000 毫秒）
162export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
163```
164
165此值將作為 `Authorization` 和 `X-Api-Key` 標頭發送。`apiKeyHelper` 的優先級低於 `ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_API_KEY`。
166
167<h4 id="unified-endpoint-recommended">
168 統一端點（推薦）
169</h4>
170
171使用 LiteLLM 的 [Anthropic 格式端點](https://docs.litellm.ai/docs/anthropic_unified)：
172
173```bash theme={null}
174export ANTHROPIC_BASE_URL=https://litellm-server:4000
175```
176
177**統一端點相對於傳遞端點的優勢：**
178
179* 負載均衡
180* 故障轉移
181* 對成本追蹤和最終用戶追蹤的一致支持
182
183<h4 id="provider-specific-pass-through-endpoints-alternative">
184 提供商特定的傳遞端點（替代方案）
185</h4>
186
187<h5 id="claude-api-through-litellm">
188 通過 LiteLLM 的 Claude API
189</h5>
190
191使用 [傳遞端點](https://docs.litellm.ai/docs/pass_through/anthropic_completion)：
192 63
193```bash theme={null}64當您準備好為組織推出 LLM gateway 時，無論您選擇哪個 gateway 產品，順序都是相同的：
194export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
195```
196 65
197<h5 id="amazon-bedrock-through-litellm">661. 部署 gateway 並給予它您的提供商憑證，以便它可以對它轉發的請求進行身份驗證。
198 通過 LiteLLM 的 Amazon Bedrock672. 為每個開發人員發行 gateway 憑證，以便使用情況歸屬於開發人員，離職時撤銷一個憑證。
199</h5>683. 透過[受管設定檔](/zh-TW/settings#settings-files)和您的機密工具分發配置，以便每台機器都接收基本 URL 和憑證。當兩者都分發時，開發人員無需配置任何內容。如果您沒有設定分發，開發人員按照[連接頁面](/zh-TW/llm-gateway-connect)自己設置變數。
694. 讓每個開發人員[檢查 Claude Code 中的配置](/zh-TW/llm-gateway-connect#check-for-an-existing-configuration)，以便分發問題在他們依賴 gateway 之前浮出水面。
200 70
201使用 [傳遞端點](https://docs.litellm.ai/docs/pass_through/bedrock)：71[為您的組織推出 LLM gateway](/zh-TW/llm-gateway-rollout) 逐步介紹每個步驟，並顯示在每個步驟分發的配置檔案。gateway 是組織設置的一部分；有關政策強制執行、使用情況可見性和資料處理決策，請參閱[為您的組織設置 Claude Code](/zh-TW/admin-setup)。
202 72
203```bash theme={null}73<h2 id="third-party-gateways">
204export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock74 第三方 gateway
205export CLAUDE_CODE_SKIP_BEDROCK_AUTH=175</h2>
206export CLAUDE_CODE_USE_BEDROCK=1
207```
208 76
209<h5 id="google-vertex-ai-through-litellm">77任何公開[支持的 API 格式](/zh-TW/llm-gateway-protocol#api-formats)的 gateway 都可以運作。Anthropic 不認可、維護或審計第三方 gateway 產品。按照他們自己的文檔部署它們，然後使用[推出步驟](/zh-TW/llm-gateway-rollout)完成 Claude Code 端的推出。
210 通過 LiteLLM 的 Google Vertex AI
211</h5>
212 78
213使用 [傳遞端點](https://docs.litellm.ai/docs/pass_through/vertex_ai)：79<h2 id="subscriptions-and-gateways">
80 訂閱和 gateway
81</h2>
214 82
215```bash theme={null}83當[gateway 憑證變數](/zh-TW/llm-gateway-connect#set-the-credential-variable)或 `apiKeyHelper` 處於活動狀態時，開發人員的 claude.ai 訂閱不被使用：憑證替換該會話的訂閱登錄，訂閱的使用限制不適用。該流量按令牌計費給擁有 gateway 轉發的憑證的人，例如您的組織的 Anthropic Console 帳戶，或當 gateway 路由到那裡時您的 Bedrock、Vertex 或 Foundry 帳戶。
216export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
217export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
218export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
219export CLAUDE_CODE_USE_VERTEX=1
220export CLOUD_ML_REGION=us-east5
221```
222 84
223<h5 id="claude-platform-on-aws-through-a-gateway">85僅設置 `ANTHROPIC_BASE_URL` 而不設置 gateway 憑證不會替換訂閱。請求仍然透過 gateway 路由，但保存的 claude.ai 登錄保持活動憑證，因此其使用限制和計費適用。將此流量轉發給 Anthropic 的 gateway 必須轉發 `anthropic-beta` 中的 OAuth 功能；請參閱[請求標頭參考](/zh-TW/llm-gateway-protocol#request-headers)。
224 通過網關的 AWS 上的 Claude Platform
225</h5>
226 86
227路由到轉發至 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 端點的網關：87<h2 id="configure-separately-from-the-gateway">
88 與 gateway 分開配置
89</h2>
228 90
229```bash theme={null}91gateway 決定模型 API 請求的發送位置。模型選擇、Claude Code 的其餘網路流量和公司代理分開配置：
230export ANTHROPIC_AWS_BASE_URL=https://litellm-server:4000/anthropic-aws
231export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
232export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
233export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
234```
235 92
236如需更詳細的信息，請參閱 [LiteLLM 文檔](https://docs.litellm.ai/)。93* **模型選擇**：基本 URL 決定請求的發送位置，而不是哪個模型回答它們。使用 `/model` 命令或模型環境變數選擇模型；請參閱[如何設置您的模型](/zh-TW/model-config#setting-your-model)
94* **客戶端流量**：版本檢查和可選客戶端遙測（都使用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/zh-TW/env-vars) 禁用），以及當使用 claude.ai 或 Console 登錄時的登錄流量，轉到 Anthropic 的更新和身份驗證端點而不是 gateway。有關域，請參閱[網路存取要求](/zh-TW/network-config#network-access-requirements)
95* **公司代理**：使用 `HTTPS_PROXY` 設置的代理位於 Claude Code 和它與之通信的每個伺服器之間，包括 gateway。如果您的網路需要代理，請配置兩者；請參閱[代理配置](/zh-TW/network-config#proxy-configuration)
237 96
238<h2 id="additional-resources">97<h2 id="related-pages">
239 其他資源98 相關頁面
240</h2>99</h2>
241 100
242* [LiteLLM 文檔](https://docs.litellm.ai/)101* [將 Claude Code 連接到 LLM gateway](/zh-TW/llm-gateway-connect)：在您自己的機器上設置基本 URL 和憑證，具有每個表面的配置和故障排除表
243* [Claude Code 設定](/zh-TW/settings)102* [為您的組織推出 LLM gateway](/zh-TW/llm-gateway-rollout)：部署 gateway、發行開發人員憑證和分發受管設定的管理員檢查清單
244* [企業網路配置](/zh-TW/network-config)103* [Gateway 協議參考](/zh-TW/llm-gateway-protocol)：Claude Code 發送到 gateway 的內容，供配置 gateway 的操作人員使用，涵蓋端點、要轉發的標頭和功能傳遞
245* [第三方整合概述](/zh-TW/third-party-integrations)104* [為您的組織設置 Claude Code](/zh-TW/admin-setup)：gateway 是其中一部分的更廣泛推出決策，包括政策強制執行和使用情況可見性
