Claude Code ANTHROPIC_AUTH_TOKEN 错误：完整配置修复

当出现Claude Code ANTHROPIC_AUTH_TOKEN 错误：完整配置修复这一查询时，修复通常从一个问题开始：Claude Code 是否把凭据发送到了你的网关实际读取的请求头里？

对于 Claude Code 的网关路由，ANTHROPIC_AUTH_TOKEN 会发送 Authorization: Bearer ...。ANTHROPIC_API_KEY 会发送 x-api-key: ...。即使值本身有效，放在错误变量中的令牌也可能看起来像无效密钥、过期登录或损坏的网关。

当你设置了 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_BASE_URL、Claude Code 配置文件、VS Code 扩展或 CI 工作流之后，Claude Code 仍然失败时，请使用这份运行手册。

快速修复

在编辑你机器上的每个设置文件之前，先从最小范围的诊断开始。

1. 选择一个凭据变量。
2. 在同一个 shell 中导出网关基础 URL 和该凭据。
3. 对 $ANTHROPIC_BASE_URL/v1/messages 发送一个单 token 的 curl 请求。
4. 从同一个 shell 启动 Claude Code。
5. 运行 /status，并确认 Anthropic base URL 和预期的凭据来源都已显示。
6. 如果 curl 成功，但 Claude Code 仍然要求你登录，请把凭据移动到 Claude Code 在首次运行设置之前就能读取的位置，例如 ~/.claude/settings.json、shell 导出变量或受管设置。

对于 bearer token 网关：

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"

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": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

对于 x-api-key 网关：

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_API_KEY="REPLACE_WITH_GATEWAY_KEY"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

带有消息 id 和 content 的 JSON 响应表示 URL 和凭据有效。401 表示网关拒绝了凭据，或者收到了它不会读取的请求头中的凭据。

Claude Code ANTHROPIC_AUTH_TOKEN 错误：完整配置修复检查清单

将此表用作工作诊断表。在确认活动变量、请求头和设置优先级之前，不要轮换密钥。

选择 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY

ANTHROPIC_AUTH_TOKEN 用于 bearer token。Claude Code 会将其发送为：

Authorization: Bearer <token>

ANTHROPIC_API_KEY 用于 API 密钥。Claude Code 会将其发送为：

x-api-key: <key>

如果你的网关团队只说“token”或“Authorization header”，先使用 ANTHROPIC_AUTH_TOKEN。如果他们说“API key”或“x-api-key”，则使用 ANTHROPIC_API_KEY。如果你是猜的并收到了 401，请在轮换密钥之前切换变量。

在排查期间不要同时设置这两个变量。否则，Claude Code ANTHROPIC_AUTH_TOKEN 错误：完整配置修复 就会从认证问题变成认证优先级问题。

把变量放在 Claude Code 实际读取的位置

Shell 导出变量适合第一次测试，因为它们很容易取消设置：

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"
claude

它们只对该终端会话以及从中启动的程序生效。如果你从别处打开 VS Code、桌面应用或后台代理，这个导出变量可能不会被看到。

对于持久的用户级 CLI 配置，请使用 ~/.claude/settings.json：

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

对于单个项目，请使用 .claude/settings.local.json，并在添加凭据之前确保它已加入 gitignore。不要把凭据放在 .claude/settings.json 中，因为该文件 предназнач于与仓库共享。

当 shell 导出和设置文件中的 env 块设置了同一个变量时，Claude Code 会使用设置文件中的值。这就是为什么 /status 比 echo $ANTHROPIC_AUTH_TOKEN 更可靠。

修复 VS Code 扩展

Claude Code VS Code 扩展有自己的启动检查。在 VS Code 用户设置中，通过 claudeCode.environmentVariables 配置网关变量：

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

使用 VS Code 命令 Preferences: Open User Settings (JSON)。然后重新启动扩展会话并运行 /status。如果扩展仍然提示登录，说明它在自己的登录检查中没有看到该凭据。

修复 GitHub Actions

Claude Code GitHub Actions 从工作流的 env 块读取 ANTHROPIC_BASE_URL。对于 x-api-key 网关，将网关密钥作为 action 输入传递：

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-token 网关，action 仍然需要 anthropic_api_key 来满足其启动检查，而 ANTHROPIC_AUTH_TOKEN 则是 Claude Code 作为 Authorization: Bearer 发送的值：

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 }}

将这些值保存在 GitHub Secrets 中。不要把网关凭据粘贴到工作流日志、问题评论或已提交的文件里。

使用 /status 作为真实性检查

在任何配置更改之后，运行：

/status

对于 Anthropic 格式的网关，Status 选项卡应该显示：

Anthropic base URL: https://llm-gateway.example.com
Auth token: ANTHROPIC_AUTH_TOKEN

或：

Anthropic base URL: https://llm-gateway.example.com
API key: ANTHROPIC_API_KEY

如果缺少 base URL 这一行，说明 ANTHROPIC_BASE_URL 没有传到会话中。如果凭据来源是已保存的登录信息，Claude Code 就没有在使用网关凭据。如果两者看起来都正确，但消息仍然失败，那么问题现在很可能出在网关路由、上游兼容性、代理行为或证书信任上。

关于 Claude Code 网关路由的 Flatkey 说明

Flatkey 在 Claude Code 的两种不同工作流中都很有用，而且这种区别很重要。

对于来自项目或代理技能的 OpenAI 兼容模型调用，Flatkey 的 base URL 是：

https://router.flatkey.ai/v1

对于 Claude Code 自己的网关路径，请遵循 Anthropic Messages 格式的网关设置，除非网关自己的 Claude Code 说明明确要求，否则不要在 ANTHROPIC_BASE_URL 后面添加 /v1。一个典型的提供商模式是：

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

然后运行 /status，发送一个简短提示，并检查网关账本或日志。将 Claude Code SKILL.md 设置 与此路径分开：技能教 Claude Code 如何从你的仓库中调用 Flatkey 支持的模型和工具；网关路由则控制 Claude Code 将其自身的 Claude 系列流量发送到哪里。

如果你正在跨提供商标准化代理流量，请将本文与 Claude API proxy vs multi-model router 和 Flatkey API quickstart 指南搭配阅读。

当 token 不是根本问题时的网关运维检查

一些 Claude Code ANTHROPIC_AUTH_TOKEN 错误：完整配置修复 的搜索最初看起来是本地设置问题，最后却落到了网关上。如果单 token curl 可以通过身份验证，并且 /status 看起来正常，请检查这些网关侧条件：

如果你的网关前置的是一个不接受完整 Anthropic Messages 请求形状的提供方，请使用该提供方特定的变量，而不是 ANTHROPIC_BASE_URL，或者在网关内部桥接该 schema。不要盲目剥离字段；那样只会把一个可见错误变成稍后出现的能力故障。

可复制的调试记录

在将问题交给同事或网关运维人员时，请使用这份记录：

claude_code_auth_debug:
  date_checked: 2026-09-22
  surface: cli # cli | vscode | github_actions | agent_sdk | desktop
  claude_code_version: ""
  expected_gateway_base_url: "https://llm-gateway.example.com"
  variable_used: "ANTHROPIC_AUTH_TOKEN"
  expected_header: "Authorization: Bearer"
  status_tab_base_url_seen: false
  status_tab_credential_source: ""
  curl_status_code: ""
  curl_response_shape: "json_message | 401 | html_200 | dns_error | tls_error | other"
  settings_files_checked:
    - "~/.claude/settings.json"
    - ".claude/settings.local.json"
    - ".claude/settings.json"
  shell_started_claude: false
  saved_login_present: unknown
  gateway_logs_received_request: unknown
  suspected_fix: ""

这份记录会迫使排查过程把三件事区分开：Claude Code 读取了哪里的配置、它发送了哪个头，以及网关返回了什么。

常见问题

我应该使用 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY？

当网关期望 bearer token 或 Authorization 头时，使用 ANTHROPIC_AUTH_TOKEN。当网关期望 x-api-key 时，使用 ANTHROPIC_API_KEY。如果你不确定，先使用 ANTHROPIC_AUTH_TOKEN，用 curl 请求验证；如果收到 401，再切换。

为什么 /status 没有显示我的 base URL？

ANTHROPIC_BASE_URL 没有传到 Claude Code 进程中。请从同一个 shell 启动 claude，把值移到正确的设置文件中，或者配置你正在使用的界面，例如 VS Code 设置或 GitHub Actions 的 env。

为什么 curl 可以工作，但 Claude Code 仍然要求我登录？

基础 URL 可访问，但 Claude Code 在需要凭据时没有可用的凭据。请将 ANTHROPIC_AUTH_TOKEN 或正确的凭据变量放入 shell 导出、用户设置或托管设置中，让 Claude Code 在首次运行设置之前读取到。

我可以把 token 放在 .claude/settings.json 里吗？

不要把密钥放在 .claude/settings.json 中，因为它是共享的项目文件。请使用 ~/.claude/settings.json、.claude/settings.local.json、托管设置、密钥管理器或 CI 密钥。

ANTHROPIC_AUTH_TOKEN 会把 Claude Code 路由到非 Claude 模型吗？

不会。它只会改变 Claude Code 认证到所配置的 Anthropic 格式网关的方式。网关可能会根据其自身实现来路由或桥接请求，但 Claude Code 仍然期望在 ANTHROPIC_BASE_URL 路径上看到 Claude API 的形状。

最终最安全的验证是什么？

运行一次 token 的 curl 请求，从已配置的入口启动 Claude Code，运行 /status，发送一个简短提示，并确认网关账本或日志显示了该请求。这四步检查是 Claude Code ANTHROPIC_AUTH_TOKEN 错误：完整配置修复 背后的持久性修复。

已检查的来源

• Anthropic Claude Code 文档：将 Claude Code 连接到 LLM 网关，访问于 2026-09-22。
• Anthropic Claude Code 文档：设置文件及优先级，访问于 2026-09-22。
• Anthropic Claude Code 文档：Claude Code 网关兼容性指南，访问于 2026-09-22。
• Claude 帮助中心：在 Claude Code 中管理 API 密钥环境变量，访问于 2026-09-22。
• Flatkey 公开 SKILL.md，访问于 2026-09-22。
• Flatkey 知识库：产品概览、营销策略、品牌语调。