将 Claude Code 指向您组织的 LLM 网关。检查您的管理员是否已配置它,或自行设置基础 URL 和凭证,然后验证连接并修复网关错误。
LLM 网关是您的组织在 Claude Code 和模型提供商之间运行的代理。当您的组织使用网关时,Claude Code 使用您的组织颁发的凭证而不是您的个人 claude.ai 登录来向网关进行身份验证。
本页面适用于通过其组织运营的网关运行 Claude Code 的开发人员。它涵盖两条路径:检查您的管理员是否已为您配置它,以及在他们没有配置时自行配置。
检查现有配置
管理员可以通过托管设置、设备管理或 apiKeyHelper 分发网关地址和凭证,以便 Claude Code 在启动时自动获取,无需您进行任何设置。要检查您的组织是否已这样做:
- 启动 Claude Code
运行
claude。如果它打开到登录屏幕而不是会话,则没有分发网关凭证;自行配置如下。 - 检查状态选项卡
如果 Claude Code 启动了会话而没有显示登录屏幕,运行
/status,打开状态选项卡,并检查两行:* `Anthropic base URL`:仅当设置了网关地址时才显示此行。如果不存在,Claude Code 未指向网关;[自行配置](#configure-claude-code-yourself)如下。 * `Auth token` 或 `API key`:命名 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY` 或 `apiKeyHelper` 的行确认网关凭证处于活动状态。命名 claude.ai 账户的 `Login method` 行意味着凭证未被分发;[自行设置](#set-the-credential-variable)。 - 发送测试消息
关闭
/status菜单并在 Claude Code 中发送任何提示。来自 Claude 的正常响应,没有错误,确认网关连接有效。
如果 /status 菜单中的两行看起来都正确,但向 Claude 的消息失败,请参阅故障排除表。
自行配置 Claude Code
要自行为网关配置 Claude Code,您需要从网关团队获得:
- 网关的基础 URL
- 凭证:密钥或令牌字符串,或获取凭证的命令
- 如果您的网关团队没有说明凭证的类型,下面的凭证变量部分涵盖了要尝试的内容
下面的部分按顺序涵盖配置:
- 设置凭证变量和设置基础 URL:每个网关连接需要的两个变量
- 验证连接:在保存任何内容之前确认它有效
- 配置每个界面:如果您使用除 Claude Code CLI 之外的界面(如 VS Code),请查看如何使用网关凭证配置它
- 其他配置:某些网关需要的变量超出基础 URL 和凭证,例如自定义标头、凭证助手、模型发现、提供商格式的基础 URL 或关闭网关路径外的流量。仅在您的管理员命名它们或您的网络限制出站流量时设置这些
设置凭证变量
要向网关验证 Claude Code,请在环境变量中设置您的凭证。哪个变量取决于您的网关团队告诉您的内容:
| 在以下位置设置凭证 | 使用时机 |
|---|---|
ANTHROPIC_AUTH_TOKEN |
您的网关团队说"bearer token"或"Authorization header" |
ANTHROPIC_API_KEY |
您的网关团队说"API key"或"x-api-key" |
apiKeyHelper |
凭证轮换或来自保管库 |
如果您没有被告知是哪种类型,请使用 ANTHROPIC_AUTH_TOKEN;下面的验证请求显示了如何判断您是否需要切换。
设置基础 URL 和凭证
将网关的基础 URL 和您上面选择的凭证变量设置为环境变量。示例使用 ANTHROPIC_AUTH_TOKEN;如果那是您选择的变量,请将其替换为 ANTHROPIC_API_KEY。您可以在您的 shell 中设置它们,这仅持续一个终端会话,或在 Claude Code 设置文件中设置它们,这在 Claude Code 运行的任何地方都持续。
对于您的第一次连接,从 shell 导出开始,并在将值移动到设置文件之前运行验证请求。
设置为 shell 环境变量
将值替换为您的网关团队给您的值:
export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
```
$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
```
Shell 导出仅适用于该终端会话和从它启动的程序;从 dock 或开始菜单启动的编辑器不会看到它们。要使它们在新终端中持续,请将相同的行添加到您的 shell 配置文件,例如 ~/.zshrc、~/.bashrc 或您的 PowerShell $PROFILE,或改用设置文件。
在设置文件中设置
要使配置在 Claude Code 运行的任何地方应用而不依赖于您的 shell,请在设置文件的 env 块中设置变量。设置文件有不同的范围:
~/.claude/settings.json适用于您的所有项目。在 Windows 上,路径是%USERPROFILE%\.claude\settings.json.claude/settings.local.json适用于一个项目。Claude Code 在创建文件时将其添加到您的 gitignore;如果您自己创建它,请首先手动将其添加到您的 gitignore,以便您不会意外提交您的凭证
不要将凭证放在项目的 .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 导出。
curl -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": "."}]}'
```
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 密钥。您的 claude.ai 登录在设置变量时保持保存和未使用;取消设置变量,Claude Code 返回到它。使用 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。管理员分发的配置优先级更高,使此表单为只读
启用网关配置后,桌面应用仅在您的本地机器上运行会话:环境选择器不提供 SSH 会话或 Anthropic 托管的云环境,远程控制不可用。要通过网关在远程主机上使用 Claude Code,请在该主机上运行 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 和网络上的 Claude Code 是 Anthropic 托管的产品,始终使用 Anthropic 的 API;它们不是网关部署的一部分。在云会话的环境配置中设置的网关变量不适用。如果您的流量必须保持在网关上,请不要为这些用户启用这些界面。
远程控制和语音听写都依赖于 claude.ai 身份:远程控制将实时会话与您的账户配对,语音听写到达 claude.ai 转录端点。当 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 处于活动状态时,它们不可用。从 v2.1.196 开始,当 ANTHROPIC_BASE_URL 指向非 Anthropic 主机时,远程控制也被禁用,因此仅使用 claude.ai 登录是不够的。
要恢复任一功能,请使用 claude.ai 登录并取消设置它检查的网关变量。claude doctor 的远程控制部分命名要取消设置的凭证变量。
- 语音听写:取消设置网关凭证
- 远程控制:取消设置网关凭证和
ANTHROPIC_BASE_URL
其他配置
这些设置涵盖超出基础 URL 和凭证的情况。仅在您的管理员的说明、您的网络的出站规则或故障排除表要求一个时设置它们。
发送其他标头
某些网关使用除凭证外的自定义标头来路由或标记请求,例如租户标识符或路由密钥。要发送一个,请设置 ANTHROPIC_CUSTOM_HEADERS,每行一个 Name: Value 对。下面的示例添加了一个名为 X-Org-Route 的路由标头:
export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
```
$env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
```
您也可以在设置文件的 env 块中设置 ANTHROPIC_CUSTOM_HEADERS。在那里使用 \n 在对之间,因为 JSON 字符串不能跨多行:
{
"env": {
"ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: example"
}
}
将网关模型添加到模型选择器
模型发现在启动时查询网关的模型列表,并将这些名称添加到 /model 选择器中,与内置条目一起。
如果您的网关提供不在 Claude Code 内置列表中的模型名称,并且您想从选择器中选择它们,请启用它。如果内置模型是您使用的,您不需要发现;您的管理员也可能已通过托管设置启用它。
要启用它,请在您的 shell 或 ~/.claude/settings.json 的 env 块中设置 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。发现需要 Claude Code v2.1.129 或更高版本。
发现的模型显示为标记为 From gateway 的其他 /model 条目。要确认发现运行,启动 claude --debug 并查找 [gatewayDiscovery] 行:成功记录缓存了多少模型,404、超时或重定向也记录在那里。有关发现何时运行、它过滤什么以及网关提供的响应格式,请参阅模型发现参考。
使用 apiKeyHelper 轮换凭证
apiKeyHelper 是 Claude Code 运行以获取您的网关凭证的命令,而不是从静态环境变量读取它。
当凭证按计划过期、来自保管库或 SSO 命令,或您的管理员告诉您配置一个时,使用助手。如果您的凭证是您设置一次的固定字符串,凭证变量是您需要的全部,您可以跳过本部分。
助手是任何将当前凭证打印到 stdout 的 shell 命令。Claude Code 通过您的系统 shell 运行它,因此在 Windows 上它可以是可执行文件或 PowerShell 调用。编写脚本,使其可执行,并从您的设置文件中的 apiKeyHelper 引用它:
例如,从保管库读取的脚本:```bash theme={null}
#!/bin/bash
vault kv get -field=api_key secret/llm-gateway/claude-code
```
在 `~/.claude/settings.json` 中引用其路径:
```json theme={null}
{
"apiKeyHelper": "~/bin/get-gateway-key.sh"
}
```
例如,从保管库读取的脚本:```powershell theme={null}
vault kv get -field=api_key secret/llm-gateway/claude-code
```
在 `%USERPROFILE%\.claude\settings.json` 中引用 PowerShell 调用,转义 JSON 字符串中的反斜杠:
```json theme={null}
{
"apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
}
```
Claude Code 默认缓存助手的输出五分钟,并在请求返回 HTTP 401 时重新运行它。要更改缓存生命周期,请以毫秒为单位设置 CLAUDE_CODE_API_KEY_HELPER_TTL_MS,例如 CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000 表示 15 分钟。
助手的值在 Authorization 和 x-api-key 标头中都发送,因此它适用于您的网关读取的任何标头。
关闭网关路径外的流量
网关承载模型请求,但 Claude Code 也向网关路径外发送非必要的后台流量,发送到 Anthropic 和第三方服务(如 GitHub):版本检查、遥测、错误报告、发行说明和类似请求。在仅允许出站到网关的网络上,这些请求失败,并可能在您的出站监控中显示为被阻止的连接。
要关闭该流量,请在与网关变量相同的 shell 导出或设置文件 env 块中设置 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1:
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
```
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
```
设置该变量具有以下效果和限制:
- 它禁用自动更新,因此请为另一个更新路径做计划,例如您的包管理器或托管分发。
- 它抑制 fast mode 可用性检查。除非之前的检查已在机器上启用了 fast mode,否则
/fast报告 fast mode 不可用。 - 它关闭网关模型发现,尽管发现查询网关本身。之前发现的模型从本地缓存保持可用,但列表不会刷新。
- WebFetch 工具的域安全检查不受影响,仍然调用
api.anthropic.com。如果您的网络阻止该主机,请在设置中使用skipWebFetchPreflight: true单独关闭它。 - 对于每个遥测流及控制它的变量,请参阅遥测服务。
通过网关路由到云提供商
这些配置使用提供商特定的基础 URL 变量代替 ANTHROPIC_BASE_URL 将 Claude Code 指向通过网关的云提供商。Amazon Bedrock 和 Google Cloud 的 Agent Platform 网关接受这些提供商的本机请求格式;Microsoft Foundry 和 AWS 上的 Claude Platform 网关接受 Anthropic Messages 格式,仅在哪个基础 URL 变量到达它们方面有所不同。
仅在您的网关团队特别命名 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform 时使用一个。如果上面的验证请求返回 JSON,您可以跳过本部分。
为您的网关团队命名的提供商设置块。跳过身份验证变量告诉 Claude Code 不要使用提供商凭证签署请求,因为网关持有这些。如果网关需要自己的令牌,请在块后添加 ANTHROPIC_AUTH_TOKEN,除了 Microsoft Foundry,它使用 ANTHROPIC_FOUNDRY_API_KEY,如所示。期望持有者令牌的 Microsoft Foundry 网关可以改用 ANTHROPIC_FOUNDRY_AUTH_TOKEN;当两者都设置时,它优先于 ANTHROPIC_FOUNDRY_API_KEY。ANTHROPIC_FOUNDRY_AUTH_TOKEN 需要 Claude Code v2.1.203 或更高版本。
Amazon Bedrock
export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1
```
$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 的 Agent Platform {#google-cloud’s-agent-platform}
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
```
$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"
```
Microsoft Foundry
将网关的凭证放在 ANTHROPIC_FOUNDRY_API_KEY 中;它作为 x-api-key 标头发送到网关。期望持有者令牌的网关可以改用 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。在 v2.1.203 之前,CLAUDE_CODE_SKIP_FOUNDRY_AUTH 没有 API 密钥会使 Microsoft Foundry 客户端无法发送请求。
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
```
$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"
```
AWS 上的 Claude Platform
有关工作区 ID,请参阅 AWS 上的 Claude Platform。
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
```
$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"
```
故障排除网关错误
这些是通过网关运行 Claude Code 时最常见的错误,包括网关端的原因和修复:
| 错误 | 原因 | 修复 |
|---|---|---|
启动警告命名两个凭证源并以 auth may not work as expected 结尾。较旧的版本显示 Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set 代替。 |
网关凭证和保存的登录都处于活动状态;变量用于请求,但过时的登录可能导致意外的身份验证行为 | 取消设置变量以使用保存的登录,或运行 /logout 以使用网关凭证 |
401 错误命名无效或无法识别的令牌 |
凭证不是网关颁发的,或它处于网关不读取的标头中 | 确认变量与凭证表中的凭证类型匹配,如果凭证被撤销,请在网关处重新生成密钥 |
Your apiKeyHelper script is failing |
apiKeyHelper 设置中的命令以错误退出、超时或未打印任何内容,因此请求携带占位符密钥 |
直接运行该命令以查看失败原因,如果报告会话过期,请使用您的凭证提供商重新身份验证;请参阅错误参考 |
Unable to connect to API (ConnectionRefused),或来自 npm 安装的 (ECONNREFUSED),通常在 Claude Code 使用退避重试时的静默暂停之后 |
没有任何东西在基础 URL 处应答:地址错误,或 VPN 或防火墙阻止了网关的路径 | 运行上面的 curl 测试,它会立即因相同原因失败,并与您的网关团队确认 URL 和网络路径 |
API returned an empty or malformed response (HTTP 200) |
网关或中间代理返回了非 API 响应,通常是 HTML 错误或登录页面 | 使用上面的 curl 请求测试;修复返回非 JSON 的网关路由 |
400 错误命名 context_management、Extra inputs are not permitted 或其他无法识别的字段 |
网关将请求转发到上游,该上游拒绝 Claude Code 发送到 Anthropic 格式端点的字段 | 设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1,它抑制大多数预发布字段;请参阅功能传递。某些 beta 不受此标志限制;对于那些,设置匹配的 CLAUDE_CODE_USE_* 提供商变量,以便 Claude Code 仅发送该提供商接受的内容 |
400 错误命名 thinking 或 adaptive,例如 Input tag 'adaptive' found |
上游模型构建不接受自适应推理,Claude Code 为 Claude 4.6 及更高版本的模型请求 | 升级网关的上游。在 Opus 4.6 和 Sonnet 4.6 上,CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 代替有效。模型配置能力变量仅适用于提供商配置,例如 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_VERTEX,不在 ANTHROPIC_BASE_URL 网关后面 |
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 设置为低于网关模型的输出限制 |
模型从 /model 选择器中缺失 |
网关模型名称不在 Claude Code 的内置列表中 | 启用网关模型发现或使用模型配置变量添加名称 |
| Claude Code 要求您登录,即使 curl 测试成功 | CLI 没有自己的凭证:可达的基础 URL 不是一个,项目的 .claude/settings.json 或 .claude/settings.local.json 中的 env 块仅在第一次运行向导和信任提示之后应用 |
在 Claude Code 在首次运行设置之前读取的某处设置 ANTHROPIC_AUTH_TOKEN:shell 导出、~/.claude/settings.json 中的 env 块或托管设置 |
ANTHROPIC_API_KEY 已设置但被忽略,没有提示 |
密钥需要在交互会话中进行一次性批准,之前拒绝的密钥被忽略而不再询问 | 在 /config 下使用 Use custom API key 选项启用它 |
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 以使用网关凭证,或删除网关凭证以使用第一方登录。两者不能组合 |
403 带有 HTML 正文,例如 403 Forbidden,当网关自己的日志显示没有收到请求时 |
网关前面的 Web 应用防火墙或反向代理在请求到达网关之前阻止了请求正文。Claude Code 提示包括 XML 样式标签和与跨站脚本正文规则匹配的源代码,因此短 curl 测试通过而实际会话不通过 | 从请求正文检查中豁免网关的 /v1/messages 路径。在 AWS WAF 上这是 CrossSiteScripting_Body 托管规则;在带有 ModSecurity 的 nginx 上它是等效的 OWASP CRS 正文规则 |
证书或 TLS 错误,例如 SSL certificate verification failed 或 Self-signed certificate detected,当 curl 测试成功时 |
Claude Code 的运行时不信任 curl 使用的相同证书颁发机构。常见于企业 TLS 检查代理后面 |
将 NODE_EXTRA_CA_CERTS 设置为 CA 包路径;请参阅 CA 证书存储 |
如果 Claude Code 在删除网关配置后重复提示您登录,原因通常是凭证存储而不是网关;请参阅身份验证错误。
相关资源
- LLM 网关概述:什么是网关以及它如何与 claude.ai 订阅交互
- 为您的组织推出 LLM 网关:部署和分发网关配置的面向管理员的检查清单
- 网关协议参考:Claude Code 发送到网关的内容,包括网关必须转发的标头和字段
- 设置:设置文件的位置以及如何读取
env块 - 身份验证:凭证变量、
apiKeyHelper和 OAuth 登录如何交互