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 连接到 LLM 网关
6
7> 将 Claude Code 指向您组织的 LLM 网关。检查您的管理员是否已配置它，或为 CLI、VS Code、GitHub Actions 和 Agent SDK 自行设置基础 URL 和凭证，然后验证连接并修复网关错误。
8
9[LLM 网关](/zh-CN/llm-gateway)是您的组织在 Claude Code 和模型提供商之间运行的代理。当您的组织使用网关时，Claude Code 使用您的组织颁发的凭证而不是您的个人 claude.ai 登录来向网关进行身份验证。
10
11本页面适用于通过其组织运营的网关运行 Claude Code 的开发人员。它涵盖两条路径：[检查您的管理员是否已为您配置它](#check-for-an-existing-configuration)，以及[在他们没有配置时自行配置](#configure-claude-code-yourself)。
12
13<Note>
14 * 要为您的组织部署网关，请参阅[推出 LLM 网关](/zh-CN/llm-gateway-rollout)
15 * 有关 Claude Code 发送到网关的内容，请参阅[网关协议参考](/zh-CN/llm-gateway-protocol)
16</Note>
17
18<h2 id="check-for-an-existing-configuration">
19 检查现有配置
20</h2>
21
22管理员可以通过[托管设置](/zh-CN/settings#settings-files)、设备管理或 [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) 分发网关地址和凭证，以便 Claude Code 在启动时自动获取，无需您进行任何设置。要检查您的组织是否已这样做：
23
24<Steps>
25 <Step title="启动 Claude Code">
26 运行 `claude`。如果它打开到登录屏幕而不是会话，则没有分发网关凭证；[自行配置](#configure-claude-code-yourself)如下。
27 </Step>
28
29 <Step title="检查状态选项卡">
30 如果 Claude Code 启动了会话而没有显示登录屏幕，运行 `/status`，打开**状态**选项卡，并检查两行：
31
32 * `Anthropic base URL`：仅当设置了网关地址时才显示此行。如果不存在，Claude Code 未指向网关；[自行配置](#configure-claude-code-yourself)如下。
33 * `Auth token` 或 `API key`：命名 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` 或 `apiKeyHelper` 的行确认网关凭证处于活动状态。命名 claude.ai 账户的 `Login method` 行意味着凭证未被分发；[自行设置](#set-the-credential-variable)。
34 </Step>
35
36 <Step title="发送测试消息">
37 关闭 `/status` 菜单并在 Claude Code 中发送任何提示。来自 Claude 的正常响应，没有错误，确认网关连接有效。
38 </Step>
39</Steps>
40
41如果 `/status` 菜单中的两行看起来都正确，但向 Claude 的消息失败，请参阅[故障排除表](#troubleshoot-gateway-errors)。
42
43<h2 id="configure-claude-code-yourself">
44 自行配置 Claude Code
45</h2>
46
47要自行为网关配置 Claude Code，您需要从网关团队获得：
48
49* 网关的基础 URL
50* 凭证：密钥或令牌字符串，或获取凭证的命令
51 * 如果您的网关团队没有说明凭证的类型，下面的[凭证变量部分](#set-the-credential-variable)涵盖了要尝试的内容
52
53下面的部分按顺序涵盖配置：
54
55* [设置凭证变量](#set-the-credential-variable)和[设置基础 URL](#set-the-base-url-and-credential)：每个网关连接需要的两个变量
56* [验证连接](#verify-the-connection)：在保存任何内容之前确认它有效
57* [配置每个界面](#configure-each-surface)：如果您使用除 Claude Code CLI 之外的界面（如 VS Code），请查看如何使用网关凭证配置它
58* [其他配置](#additional-configuration)：某些网关需要的变量超出基础 URL 和凭证，例如自定义标头、凭证助手、模型发现或提供商格式的基础 URL。仅在您的管理员命名它们时设置这些
59
60<h3 id="set-the-credential-variable">
61 设置凭证变量
62</h3>
63
64要向网关验证 Claude Code，请在环境变量中设置您的凭证。哪个变量取决于您的网关团队告诉您的内容：
65
66| 在以下位置设置凭证 | 使用时机 |
67| :------------------------------------------------------ | :------------------------------------------- |
68| `ANTHROPIC_AUTH_TOKEN` | 您的网关团队说"bearer token"或"Authorization header" |
69| `ANTHROPIC_API_KEY` | 您的网关团队说"API key"或"x-api-key" |
70| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | 凭证轮换或来自保管库 |
71
72如果您没有被告知是哪种类型，请使用 `ANTHROPIC_AUTH_TOKEN`；下面的[验证请求](#verify-the-connection)显示了如何判断您是否需要切换。
73
74<h3 id="set-the-base-url-and-credential">
75 设置基础 URL 和凭证
76</h3>
77
78将网关的基础 URL 和您上面选择的凭证变量设置为环境变量。示例使用 `ANTHROPIC_AUTH_TOKEN`；如果那是[您选择的变量](#set-the-credential-variable)，请将其替换为 `ANTHROPIC_API_KEY`。您可以[在您的 shell 中](#set-as-shell-environment-variables)设置它们，这仅持续一个终端会话，或[在 Claude Code 设置文件中](#set-in-a-settings-file)设置它们，这在 Claude Code 运行的任何地方都持续。
79
80对于您的第一次连接，从 shell 导出开始，并在将值移动到设置文件之前运行[验证请求](#verify-the-connection)。
81
82<h4 id="set-as-shell-environment-variables">
83 设置为 shell 环境变量
84</h4>
85
86将值替换为您的网关团队给您的值：
87
88<Tabs>
89 <Tab title="Bash or 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 导出仅适用于该终端会话和从它启动的程序；从 dock 或开始菜单启动的编辑器不会看到它们。要使它们在新终端中持续，请将相同的行添加到您的 shell 配置文件，例如 `~/.zshrc`、`~/.bashrc` 或您的 PowerShell `$PROFILE`，或改用设置文件。
105
106<h4 id="set-in-a-settings-file">
107 在设置文件中设置
108</h4>
109
110要使配置在 Claude Code 运行的任何地方应用而不依赖于您的 shell，请在[设置文件](/zh-CN/settings)的 `env` 块中设置变量。设置文件有不同的范围：
111
112* `~/.claude/settings.json` 适用于您的所有项目。在 Windows 上，路径是 `%USERPROFILE%\.claude\settings.json`
113* `.claude/settings.local.json` 适用于一个项目。Claude Code 在创建文件时将其添加到您的 gitignore；如果您自己创建它，请首先手动将其添加到您的 gitignore，以便您不会意外提交您的凭证
114
115<Warning>
116 不要将凭证放在项目的 `.claude/settings.json` 中。该文件被提交并与克隆存储库的每个人共享。
117</Warning>
118
119`env` 块在任一文件中看起来相同：
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
130当 shell 导出和设置文件 `env` 块都设置相同的变量时，设置文件值适用。运行 `/status` 以查看 Claude Code 使用的基础 URL 和凭证源。
131
132<h3 id="verify-the-connection">
133 验证连接
134</h3>
135
136使用在 shell 中导出的变量，向网关直接发送一个单令牌请求。这在您打开 Claude Code 之前确认 URL 和凭证有效，因此失败指向网关而不是您的配置。下面的命令读取 shell 变量，因此即使您也将值放在设置文件中，它们也需要[shell 导出](#set-as-shell-environment-variables)。
137
138<Tabs>
139 <Tab title="Bash or 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
159如果您的网关期望 `x-api-key` 标头中的密钥，请在 Bash 命令中将 `Authorization` 标头替换为 `x-api-key: $ANTHROPIC_API_KEY`，或在 PowerShell 命令中将 `"Authorization"` 哈希表条目替换为 `"x-api-key" = "$env:ANTHROPIC_API_KEY"`。
160
161以 `{"id":"msg_` 开头并包含 `"content":[...]` 字段的 JSON 响应意味着网关可达且凭证有效。命名未知模型的错误仍然证明 URL 和凭证有效，因为网关在拒绝模型名称之前验证了请求；您不需要为此测试找到您的网关提供的模型。`401` 意味着凭证被拒绝：如果您猜测了变量，请切换到另一个并重新导出。
162
163<h4 id="confirm-in-claude-code">
164 在 Claude Code 中确认
165</h4>
166
167从同一 shell 启动 `claude`，以便它继承导出，发送消息，并运行 `/status`。
168
169在**状态**选项卡上，`Anthropic base URL` 行应显示您的网关地址，这确认请求正在路由到那里；如果该行不存在，变量没有到达会话。命名您设置的变量的 `Auth token` 或 `API key` 行确认网关凭证处于活动状态而不是保存的 claude.ai 登录。
170
171如果消息失败，或 `/status` 不显示网关 URL，请参阅下面的[故障排除表](#troubleshoot-gateway-errors)。
172
173<h3 id="how-the-credential-variable-maps-to-a-header">
174 凭证变量如何映射到标头
175</h3>
176
177每个变量在不同的 HTTP 标头中发送凭证：`ANTHROPIC_AUTH_TOKEN` 在 `Authorization: Bearer` 中，`ANTHROPIC_API_KEY` 在 `x-api-key` 中，`apiKeyHelper` 在两者中。错误变量中的凭证到达网关时处于它不读取的标头中，请求失败并返回 `401`。如果验证请求返回 `401`，请切换到另一个变量并重试。
178
179<h3 id="conflicts-with-an-existing-login">
180 与现有登录的冲突
181</h3>
182
183网关凭证变量优先于保存的 claude.ai 登录或 Console 密钥。您的 claude.ai 登录在设置变量时保持保存和未使用；取消设置变量，Claude Code 返回到它。使用 `ANTHROPIC_AUTH_TOKEN`，变量立即优先。使用 `ANTHROPIC_API_KEY`，在交互模式下提示您一次以批准密钥，然后它接管。
184
185运行 `/status` 以确认哪个凭证源处于活动状态。如果启动显示命名两个源的身份验证冲突警告，请参阅[故障排除表](#troubleshoot-gateway-errors)的第一行，了解要删除哪一个。要清除保存的登录，以便仅保留网关凭证，请运行 `/logout`。
186
187<h2 id="configure-each-surface">
188 配置每个界面
189</h2>
190
191CLI 读取上面的环境变量和设置文件。其他界面是 VS Code 扩展、桌面应用、GitHub Actions、Agent SDK 和云界面（如 Slack 和网络）；下面的部分涵盖这些设置是否到达每一个。
192
193<h3 id="vs-code-extension">
194 VS Code 扩展
195</h3>
196
197在 VS Code 自己的用户设置中的 `claudeCode.environmentVariables` 中为 [VS Code 扩展](/zh-CN/vs-code)设置网关变量，使用**首选项：打开用户设置 (JSON)** 命令打开。扩展在启动前检查此设置中的凭证，因此这是网关凭证的可靠位置；`~/.claude/settings.json` 中的值到达生成的进程但不到达扩展自己的登录检查。
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 桌面应用
210</h3>
211
212桌面应用从[管理员分发的配置](https://claude.com/docs/cowork/3p/gateway)读取网关路由，而不是从 `ANTHROPIC_BASE_URL` 或 `settings.json` 读取。如果您的组织已分发它，桌面应用通过网关路由，无需您进行任何设置；如果没有，请使用终端 CLI 或 VS Code 扩展进行网关会话。管理员按照[组织推出](/zh-CN/llm-gateway-rollout#distribute-through-managed-settings)中所述分发配置。
213
214如果桌面应用显示 `Gateway was unreachable`，应用在启动时无法到达配置的基础 URL；使用上面的 [curl 测试](#verify-the-connection)检查 URL 和网络路径。
215
216<h3 id="github-actions">
217 GitHub Actions
218</h3>
219
220[Claude Code GitHub Actions](/zh-CN/github-actions) 从工作流的 `env` 块读取 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_CUSTOM_HEADERS`。将凭证作为操作的 `anthropic_api_key` 输入传递；操作将其设置为 `ANTHROPIC_API_KEY`，因此它到达网关时处于 `x-api-key` 标头中。
221
222对于 `x-api-key` 网关，在 `env` 中设置基础 URL 并将网关密钥作为输入传递：
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
234对于 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` 中的副本被忽略：
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
247对于操作的其他身份验证选项，包括 `CLAUDE_CODE_OAUTH_TOKEN` 和工作负载身份联合，请参阅 [Claude Code GitHub Actions](/zh-CN/github-actions) 和操作的 [README](https://github.com/anthropics/claude-code-action#readme)。
248
249<h3 id="agent-sdk">
250 Agent SDK
251</h3>
252
253[Agent SDK](/zh-CN/agent-sdk/overview) 没有网关特定的选项；它将环境变量传递给它生成的 Claude Code 进程。每个 SDK 接受设置生成进程环境的 `env` 选项，TypeScript 和 Python SDK 以不同方式处理它：
254
255* TypeScript：生成的进程默认继承父环境，但设置 `options.env` 完全替换环境。将 `process.env` 扩展到其中以保留您的网关变量。
256* Python：`ClaudeAgentOptions(env=...)` 合并到继承的环境之上，因此在父进程中设置的网关变量无需扩展即可通过。
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、网络和远程控制
284</h3>
285
286[Slack 中的 Claude Code](/zh-CN/slack) 和[网络上的 Claude Code](/zh-CN/claude-code-on-the-web) 是 Anthropic 托管的产品，始终使用 Anthropic 的 API；它们不是网关部署的一部分。在云会话的环境配置中设置的网关变量不适用。如果您的流量必须保持在网关上，请不要为这些用户启用这些界面。
287
288[远程控制](/zh-CN/remote-control)和[语音听写](/zh-CN/voice-dictation)都依赖于 claude.ai 身份：远程控制将实时会话与您的账户配对，语音听写到达 claude.ai 转录端点。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活动状态时，它们不可用。要使用任一个，取消设置网关凭证并改用 claude.ai 登录；`/doctor` 命名要取消设置的变量。
289
290<h2 id="additional-configuration">
291 其他配置
292</h2>
293
294这些设置涵盖超出基础 URL 和凭证的情况。仅在您的管理员的说明或[故障排除表](#troubleshoot-gateway-errors)要求一个时设置它们。
295
296<h3 id="send-additional-headers">
297 发送其他标头
298</h3>
299
300某些网关使用除凭证外的自定义标头来路由或标记请求，例如租户标识符或路由密钥。要发送一个，请设置 [`ANTHROPIC_CUSTOM_HEADERS`](/zh-CN/env-vars)，每行一个 `Name: Value` 对。下面的示例添加了一个名为 `X-Org-Route` 的路由标头：
301
302<Tabs>
303 <Tab title="Bash or 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
316您也可以在设置文件的 `env` 块中设置 `ANTHROPIC_CUSTOM_HEADERS`。在那里使用 `\n` 在对之间，因为 JSON 字符串不能跨多行：
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 将网关模型添加到模型选择器
328</h3>
329
330模型发现在启动时查询网关的模型列表，并将这些名称添加到 `/model` 选择器中，与内置条目一起。
331
332如果您的网关提供不在 Claude Code 内置列表中的模型名称，并且您想从选择器中选择它们，请启用它。如果内置模型是您使用的，您不需要发现；您的管理员也可能已通过托管设置启用它。
333
334要启用它，请在您的 shell 或 `~/.claude/settings.json` 的 `env` 块中设置 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1`。发现需要 Claude Code v2.1.129 或更高版本。{/* min-version: 2.1.129 */}
335
336发现的模型显示为标记为 `From gateway` 的其他 `/model` 条目。要确认发现运行，启动 `claude --debug` 并查找 `[gatewayDiscovery]` 行：成功记录缓存了多少模型，`404`、超时或重定向也记录在那里。有关发现何时运行、它过滤什么以及网关提供的响应格式，请参阅[模型发现参考](/zh-CN/llm-gateway-protocol#model-discovery)。
337
338<h3 id="rotate-credentials-with-apikeyhelper">
339 使用 apiKeyHelper 轮换凭证
340</h3>
341
342`apiKeyHelper` 是 Claude Code 运行以获取您的网关凭证的命令，而不是从静态环境变量读取它。
343
344当凭证按计划过期、来自保管库或 SSO 命令，或您的管理员告诉您配置一个时，使用助手。如果您的凭证是您设置一次的固定字符串，[凭证变量](#set-the-credential-variable)是您需要的全部，您可以跳过本部分。
345
346助手是任何将当前凭证打印到 stdout 的 shell 命令。Claude Code 通过您的系统 shell 运行它，因此在 Windows 上它可以是可执行文件或 PowerShell 调用。编写脚本，使其可执行，并从您的[设置文件](/zh-CN/settings)中的 `apiKeyHelper` 引用它：
347
348<Tabs>
349 <Tab title="Bash or Zsh">
350 例如，从保管库读取的脚本：
351
352 ```bash theme={null}
353 #!/bin/bash
354 vault kv get -field=api_key secret/llm-gateway/claude-code
355 ```
356
357 在 `~/.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 例如，从保管库读取的脚本：
368
369 ```powershell theme={null}
370 vault kv get -field=api_key secret/llm-gateway/claude-code
371 ```
372
373 在 `%USERPROFILE%\.claude\settings.json` 中引用 PowerShell 调用，转义 JSON 字符串中的反斜杠：
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 默认缓存助手的输出五分钟，并在请求返回 HTTP 401 时重新运行它。要更改缓存生命周期，请以毫秒为单位设置 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS`，例如 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` 表示 15 分钟。
384
385助手的值在 `Authorization` 和 `x-api-key` 标头中都发送，因此它适用于您的网关读取的任何标头。
386
387<h3 id="route-to-a-cloud-provider-through-a-gateway">
388 通过网关路由到云提供商
389</h3>
390
391这些配置使用提供商特定的基础 URL 变量代替 `ANTHROPIC_BASE_URL` 将 Claude Code 指向通过网关的云提供商。Bedrock 和 Vertex 网关接受这些提供商的本机请求格式；Foundry 和 AWS 上的 Claude Platform 网关接受 Anthropic Messages 格式，仅在哪个基础 URL 变量到达它们方面有所不同。
392
393仅在您的网关团队特别命名 Bedrock、Vertex、Foundry 或 AWS 上的 Claude Platform 时使用一个。如果上面的[验证请求](#verify-the-connection)返回 JSON，您可以跳过本部分。
394
395为您的网关团队命名的提供商设置块。跳过身份验证变量告诉 Claude Code 不要使用提供商凭证签署请求，因为网关持有这些。如果网关需要自己的令牌，请在块后添加 `ANTHROPIC_AUTH_TOKEN`，除了 Foundry，它使用 `ANTHROPIC_FOUNDRY_API_KEY`，如所示。
396
397<h4 id="amazon-bedrock">
398 Amazon Bedrock
399</h4>
400
401<Tabs>
402 <Tab title="Bash or 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 or 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
449将网关的凭证放在 `ANTHROPIC_FOUNDRY_API_KEY` 中；它作为 `x-api-key` 标头发送到网关。`CLAUDE_CODE_SKIP_FOUNDRY_AUTH` 在这里不适用：没有 API 密钥，Foundry 客户端在它离开机器之前会使每个请求失败。
450
451<Tabs>
452 <Tab title="Bash or 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 AWS 上的 Claude Platform
471</h4>
472
473有关工作区 ID，请参阅 [AWS 上的 Claude Platform](/zh-CN/claude-platform-on-aws)。
474
475<Tabs>
476 <Tab title="Bash or 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 故障排除网关错误
497</h2>
498
499这些是通过网关运行 Claude Code 时最常见的错误，包括网关端的原因和修复：
500
501| 错误 | 原因 | 修复 |
502| :-------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503| 启动警告命名两个凭证源并以 `auth may not work as expected` 结尾。较旧的版本显示 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` 代替。 | 网关凭证和保存的登录都处于活动状态；变量用于请求，但过时的登录可能导致意外的身份验证行为 | 取消设置变量以使用保存的登录，或运行 `/logout` 以使用网关凭证 |
504| `401` 错误命名无效或无法识别的令牌 | 凭证不是网关颁发的，或它处于网关不读取的标头中 | 确认变量与[凭证表](#set-the-credential-variable)中的凭证类型匹配，如果凭证被撤销，请在网关处重新生成密钥 |
505| `Unable to connect to API (ConnectionRefused)`，或来自 npm 安装的 `(ECONNREFUSED)`，通常在 Claude Code [使用退避重试](/zh-CN/errors#automatic-retries)时的静默暂停之后 | 没有任何东西在基础 URL 处应答：地址错误，或 VPN 或防火墙阻止了网关的路径 | 运行上面的 [curl 测试](#verify-the-connection)，它会立即因相同原因失败，并与您的网关团队确认 URL 和网络路径 |
506| `API returned an empty or malformed response (HTTP 200)` | 网关或中间代理返回了非 API 响应，通常是 HTML 错误或登录页面 | 使用上面的 [curl 请求](#verify-the-connection)测试；修复返回非 JSON 的网关路由 |
507| `400` 错误命名 `context_management`、`Extra inputs are not permitted` 或其他无法识别的字段 | 网关将请求转发到上游，该上游拒绝 Claude Code 发送到 Anthropic 格式端点的字段 | 设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，它抑制大多数预发布字段；请参阅[功能传递](/zh-CN/llm-gateway-protocol#feature-pass-through)。某些 beta 不受此标志限制；对于那些，设置匹配的 `CLAUDE_CODE_USE_*` 提供商变量，以便 Claude Code 仅发送该提供商接受的内容 |
508| `400` 错误命名 `thinking` 或 `adaptive`，例如 `Input tag 'adaptive' found` | 上游模型构建不接受自适应推理，Claude Code 为 Claude 4.6 及更高版本的模型请求 | 升级网关的上游。在 Opus 4.6 和 Sonnet 4.6 上，`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 代替有效。[模型配置](/zh-CN/model-config)能力变量仅适用于提供商配置，例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`，不在 `ANTHROPIC_BASE_URL` 网关后面 |
509| `400` 错误声明网关自己的措辞中的上下文或令牌限制，例如 `ContextWindowExceededError` 或 `prompt token count of N exceeds the limit of M` | 网关强制执行比模型的本机窗口更小的上下文，并重写上游错误，因此自动紧凑和重试（与 Anthropic 的 `prompt is too long` 措辞匹配）不会触发 | 运行 `/compact` 以恢复会话。要防止它，请将 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设置为网关的限制；该值被限制在至少 100,000 令牌和最多模型的上下文窗口，因此低于 100,000 的网关限制无法匹配，`/compact` 仍然是那里的恢复。还要将 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 设置为低于网关模型的输出限制 |
510| 模型从 `/model` 选择器中缺失 | 网关模型名称不在 Claude Code 的内置列表中 | 启用[网关模型发现](#add-gateway-models-to-the-model-picker)或使用[模型配置](/zh-CN/model-config)变量添加名称 |
511| Claude Code 要求您登录，即使 [curl 测试](#verify-the-connection)成功 | CLI 没有自己的凭证：可达的基础 URL 不是一个，项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 块仅在第一次运行向导和信任提示之后应用 | 在 Claude Code 在首次运行设置之前读取的某处设置 `ANTHROPIC_AUTH_TOKEN`：shell 导出、`~/.claude/settings.json` 中的 `env` 块或托管设置 |
512| `ANTHROPIC_API_KEY` 已设置但被忽略，没有提示 | 密钥需要在交互会话中进行一次性批准，之前拒绝的密钥被忽略而不再询问 | 在 `/config` 下使用 `Use custom API key` 选项启用它 |
513| `This machine's managed settings require a first-party login` | 托管设置包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，在 Claude Code v2.1.146 及更高版本上不能与 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理员必须从托管设置中删除 `forceLoginMethod` 和 `forceLoginOrgUUID` 以使用网关凭证，或删除网关凭证以使用第一方登录。两者不能组合 |
514| `403` 带有 HTML 正文，例如 `403 Forbidden`，当网关自己的日志显示没有收到请求时 | 网关前面的 Web 应用防火墙或反向代理在请求到达网关之前阻止了请求正文。Claude Code 提示包括 XML 样式标签和与跨站脚本正文规则匹配的源代码，因此短 curl 测试通过而实际会话不通过 | 从请求正文检查中豁免网关的 `/v1/messages` 路径。在 AWS WAF 上这是 `CrossSiteScripting_Body` 托管规则；在带有 ModSecurity 的 nginx 上它是等效的 OWASP CRS 正文规则 |
515| 证书或 TLS 错误，例如 `SSL certificate verification failed` 或 `Self-signed certificate detected`，当 [curl 测试](#verify-the-connection)成功时 | Claude Code 的运行时不信任 `curl` 使用的相同证书颁发机构。常见于企业 TLS 检查代理后面 | 将 `NODE_EXTRA_CA_CERTS` 设置为 CA 包路径；请参阅 [CA 证书存储](/zh-CN/network-config#ca-certificate-store) |
516
517如果 Claude Code 在删除网关配置后重复提示您登录，原因通常是凭证存储而不是网关；请参阅[身份验证错误](/zh-CN/errors#authentication-errors)。
518
519<h2 id="related-resources">
520 相关资源
521</h2>
522
523* [LLM 网关概述](/zh-CN/llm-gateway)：什么是网关以及它如何与 claude.ai 订阅交互
524* [为您的组织推出 LLM 网关](/zh-CN/llm-gateway-rollout)：部署和分发网关配置的面向管理员的检查清单
525* [网关协议参考](/zh-CN/llm-gateway-protocol)：Claude Code 发送到网关的内容，包括网关必须转发的标头和字段
526* [设置](/zh-CN/settings)：设置文件的位置以及如何读取 `env` 块
527* [身份验证](/zh-CN/authentication)：凭证变量、`apiKeyHelper` 和 OAuth 登录如何交互
