Claude Code API 403 怎么解决？先看 /status，再定位认证、模型或网关
简答：Claude Code API 403 表示某一层拒绝了请求，不等于账号一定被封，也不一定是 Claude Code 本身故障。最短路径是：保存完整错误文案，运行 <code>/status</code>，确认认证方式和 Base URL，再检查模型或部署名，最后用相同配置发送最小请求。HTML 403 优先核对代理、WAF 或网关；<code>Access to model denied</code> 优先核对模型部署与权限；独立请求成功但 Claude Code 仍失败，则优先对比本地环境变量和认证来源。
定义：Claude Code API 403 是 Claude Code、云平台、兼容网关、代理或上游模型服务返回的请求拒绝状态，具体原因必须结合响应来源、认证方式、请求地址、模型和返回内容判断。
先做 30 秒速查：确认 403 到底由哪一层返回
本文按 Claude Code 当前官方文档可核验的配置路径整理，检查时点为 2026-11-01。Claude Code 的命令、环境变量和云平台接入方式可能随版本变化；开始前先运行 claude --version 和 claude doctor，不要把旧教程中的模型名或变量直接照搬。官方安装与诊断入口见 Claude Code 设置文档。
| 现象 | 可能返回层 | 优先动作 |
|---|---|---|
Request not allowed | 账号、组织策略、网关或认证链路 | 运行 /status，确认 API provider、模型和配置来源 |
Access to model denied、permission_error | 模型供应商、项目、部署或 IAM | 核对模型部署名、区域、项目和调用权限 |
| HTML 403 或自定义网页 | 代理、WAF、防火墙或网关 | 查看 Content-Type、Server、响应体和网关日志 |
| Claude Code 403，最小请求成功 | 本地环境变量、认证优先级或模型参数 | 确保两次请求使用相同 Key、Base URL、模型、代理和运行环境 |
| 仅 Bedrock、Vertex 或 Foundry 失败 | 云平台认证、区域、项目或部署 | 不要重复 Anthropic OAuth 登录，改查对应云平台凭据和权限 |
成功判定：/status 显示的 provider、模型或资源与预期一致；短测试请求返回正常文本；如再做独立请求，必须使用同一认证、Base URL、模型、代理和终端环境。/status 的具体输出可能随版本变化，因此只把它作为配置核对入口，不把某一行固定文本当成永久格式。
第一步：确认认证方式，不要把所有 403 都当成 Key 错误
Claude Code 支持 Claude 账号登录、Anthropic API Key，以及 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 和兼容网关等路径。官方入门文档明确区分了 Console、Claude Pro 或 Max 账号和企业云平台接入；不同路径的凭据并不互相替代。查看官方认证入口
| 当前路径 | 重点检查 | 重置方式 |
|---|---|---|
| Claude 账号登录 | 账号、订阅、组织策略和 OAuth 会话 | 在交互会话中尝试 /logout 后重新执行 /login，再运行 /status |
| Anthropic API Key | Key 状态、注入终端、组织和模型权限 | 确认启动 Claude Code 的同一终端中存在 Key，不要先删除配置目录 |
| Amazon Bedrock | AWS 身份、AWS_REGION、模型访问和 IAM | 使用 AWS CLI 或既有 AWS 凭据流程；Bedrock 模式不依赖 Claude 账号的 /login |
| Google Vertex AI | Google Cloud 项目、区域、应用默认凭据和模型映射 | 使用 Google Cloud 的认证流程，区分 Claude Code 到网关和网关到 Vertex 的两层认证 |
| Microsoft Foundry | 租户、订阅、资源、项目、区域、部署名和 Entra ID 或 API Key | Entra ID 使用 az login；Foundry 模式按官方配置处理，不能按普通 OAuth 反复登录 |
| 兼容网关或 Relay | 网关 Key、Anthropic 请求格式、路由映射和上游权限 | 同时查看客户端配置和服务端日志，不能把网关返回的 403 直接归因于上游 |
如果只是账号登录异常，可先在 Claude Code 交互界面执行 /logout、/login，再重启并运行 /status。如果是 Bedrock、Vertex 或 Foundry，登录重置应使用对应云平台的凭据工具；Foundry 官方配置页面还明确说明 Foundry 模式下 /login 和 /logout 不用于该认证路径。查看 Foundry 官方配置 查看 Bedrock 官方配置
第二步：分平台检查环境变量和 Base URL
Base URL、Key 和代理变量可能改变 Claude Code 实际访问的服务。先只查看变量是否存在和指向哪个主机，不要打印完整密钥，也不要在公开日志中开启会泄露请求头的调试输出。
macOS / Linux / WSL / Git Bash
printf 'BASE=%s\n' "${ANTHROPIC_BASE_URL:-<未设置>}"; printf 'API_KEY=%s\n' "${ANTHROPIC_API_KEY:+已设置}"; printf 'AUTH_TOKEN=%s\n' "${ANTHROPIC_AUTH_TOKEN:+已设置}"; printf 'HTTP_PROXY=%s\n' "${HTTP_PROXY:-<未设置>}"; printf 'HTTPS_PROXY=%s\n' "${HTTPS_PROXY:-<未设置>}"; claude --version
Windows PowerShell
$env:ANTHROPIC_BASE_URL; if ($env:ANTHROPIC_API_KEY) { 'ANTHROPIC_API_KEY=已设置' } else { 'ANTHROPIC_API_KEY=未设置' }; if ($env:ANTHROPIC_AUTH_TOKEN) { 'ANTHROPIC_AUTH_TOKEN=已设置' } else { 'ANTHROPIC_AUTH_TOKEN=未设置' }; $env:HTTP_PROXY; $env:HTTPS_PROXY; claude --version
Windows CMD
echo %ANTHROPIC_BASE_URL% & if defined ANTHROPIC_API_KEY (echo ANTHROPIC_API_KEY=已设置) else (echo ANTHROPIC_API_KEY=未设置) & if defined ANTHROPIC_AUTH_TOKEN (echo ANTHROPIC_AUTH_TOKEN=已设置) else (echo ANTHROPIC_AUTH_TOKEN=未设置) & echo %HTTP_PROXY% & echo %HTTPS_PROXY% & claude --version
Anthropic 官方代理文档明确支持标准 HTTP_PROXY 和 HTTPS_PROXY，并说明当前 Claude Code 不支持 NO_PROXY 和 SOCKS 代理；因此不要把设置 NO_PROXY 或切换 SOCKS 当作已验证的修复方案。企业代理还需要允许访问 API 和相关服务域名，并检查自定义证书是否正确安装。查看企业代理官方文档
使用兼容网关时，Anthropic 官方网关文档示例使用 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY，并提醒第三方网关的自定义模型名和认证方式需要按网关配置填写。若网关返回自定义 HTML 或 JSON，先记录响应头和脱敏后的响应体，再让网关管理员查看路由日志。查看 LLM 网关官方配置
第三步：确认模型、部署名、项目和区域
模型权限错误不能只靠重新登录解决。Anthropic API、Bedrock、Vertex、Foundry 和兼容网关的模型字段可能分别代表模型 ID、云平台模型标识、部署名或网关自定义路由名。不要直接复制搜索结果里的模型字符串；先从当前供应商控制台或官方模型文档确认。
- Anthropic 直连：确认当前模型 ID 仍处于可用状态，并检查组织或工作区是否允许使用。
- Bedrock：确认 AWS 区域、模型访问、
bedrock:InvokeModel及流式调用权限；身份查询成功不代表目标模型一定可调用。 - Vertex：确认 Google Cloud 项目、区域、凭据和供应商映射；若经过网关，还要分别检查网关和 GCP 两侧。
- Foundry：确认资源、项目、区域、部署状态和部署名。Foundry 部署名可自定义，调用时不能只填写模型展示名称。
- 兼容网关：确认网关是否支持 Anthropic Messages API 的路径、请求头、流式行为和目标模型路由。
模型会发生退役或更名，本文不硬编码一个永久有效的模型 ID。应以当前模型状态和供应商控制台为准；Anthropic 的模型生命周期页面会列出当前状态和退役信息。查看模型生命周期文档
Foundry 的官方 Claude Code 配置要求先部署可用 Claude 模型，再在 Claude Code 中使用对应部署信息；部署名、资源和认证变量以 Microsoft 当前页面为准。查看 Foundry Claude Code 配置 查看 Foundry Claude 模型部署说明
第四步：用相同配置发送最小请求
下面的请求只适用于 Anthropic Messages API 形式的直连接口。Bedrock、Vertex、Foundry 和第三方兼容网关不能直接套用这个 URL、认证头或模型字段；它们必须使用各自的端点和凭据文档。
curl https://api.anthropic.com/v1/messages --header "x-api-key: $ANTHROPIC_API_KEY" --header "anthropic-version: 2023-06-01" --header "content-type: application/json" --data '{"model":"MODEL_ID","max_tokens":32,"messages":[{"role":"user","content":"Reply with OK"}]}'
执行前先把 MODEL_ID 替换为当前官方模型列表中确认可用的值。PowerShell 可使用以下等价请求：$body = @{ model = "MODEL_ID"; max_tokens = 32; messages = @(@{ role = "user"; content = "Reply with OK" }) } | ConvertTo-Json -Depth 5; curl.exe https://api.anthropic.com/v1/messages -H "x-api-key: $env:ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" --data $body
如果该请求成功而 Claude Code 仍返回 403，逐项对比 Claude Code 实际使用的 Key、Base URL、模型、代理、认证方式和工作目录。如果两者都失败，再查 Key 状态、组织权限、模型权限、代理和上游服务。只有响应或网关日志实际提供请求 ID 时才记录请求 ID；不要自行假设每个 403 都有可用请求 ID。
Foundry、Bedrock、Vertex 与网关的专项分流
Microsoft Foundry
Foundry 403 重点检查 Azure 租户、订阅、资源、项目、区域、部署名、部署状态和调用角色。Entra ID 模式先在对应租户执行 az login，再用 az account show 确认当前账号和订阅；API Key 模式则检查 Foundry 资源或部署详情页中的密钥。Foundry 官方配置示例使用 CLAUDE_CODE_USE_FOUNDRY、资源信息和模型部署配置，变量名称与当前页面不一致时应以当前页面为准，不要混用旧教程。查看 Foundry 配置、认证和验证步骤
Amazon Bedrock
Bedrock 模式重点核对 AWS_REGION、AWS 默认凭据链、模型访问、IAM 和区域可用性。Anthropic 文档说明 Bedrock 模式的认证由 AWS 凭据管理，因此 /login 和 /logout 不是刷新 AWS 凭据的方式。可先运行 aws sts get-caller-identity，但该命令成功只证明身份可识别，不证明该身份拥有目标模型的调用权限。查看 Bedrock 认证与模型配置
Google Vertex AI
Vertex 403 需要区分 Claude Code 本地到 Google Cloud 的认证，以及兼容网关到 Vertex 的上游认证。至少核对项目、区域、应用默认凭据、模型映射和网关路由；不要用 Anthropic API Key 的直连请求替代 Vertex 测试。
兼容网关
网关返回的 403 可能来自网关自己的 ACL、模型路由、余额或并发策略，也可能是上游返回后被网关转发。只有响应头、响应体或服务端日志能证明来源。Anthropic 官方网关文档还提醒，第三方网关不由 Anthropic 维护或审计，因此网关的字段、模型名和日志行为必须以其当前文档为准。查看网关配置边界
修复后验收与安全清单
- 重新打开一个终端，避免旧变量继续生效。
- 执行
claude --version、claude doctor，记录版本和安装方式。 - 启动 Claude Code，执行
/status，核对 provider、模型、资源和配置来源。 - 发送不包含敏感文件内容的短测试请求，例如只要求返回 OK。
- 在相同认证、Base URL、模型、代理和运行环境下执行最小请求。
- 仍失败时，保存完整错误文本、时间、供应商、模型、区域、响应头和脱敏响应体；仅在实际提供时记录请求 ID。
一次只修改一个变量。不要同时更换 Key、模型、Base URL 和代理，否则无法判断真正原因。不要把 API Key、AWS 密钥、Azure Key、Google 凭据或带认证信息的代理 URL 放进公开仓库、截图、工单或调试日志。
常见问题
Claude Code API 403 是不是账号被封了？
不一定。403 只说明某一层拒绝请求，可能来自账号、组织策略、模型权限、云平台 IAM、网关 ACL、代理或 WAF。先看完整错误文案、响应头和 /status，再判断返回来源。
已经登录了，为什么仍然 API 403？
“已登录”不代表当前请求一定使用该会话。环境变量、网关凭据、Bedrock、Vertex 或 Foundry 可能接管请求。请检查 API provider、Base URL、Key 来源、模型和当前终端环境。
HTML 403 和 JSON 403 有什么区别？
HTML 403 更适合优先核对代理、WAF、防火墙或网关页面，但这只是经验性定位，不是 HTTP 403 的固定含义。JSON 403 也可能由网关或上游返回，必须结合 Content-Type、Server、错误字段和服务端日志确认。
为什么 curl 成功，Claude Code 仍然 403？
两次请求往往并不等价，可能使用了不同 Key、Base URL、模型、代理、认证头或运行环境。只有配置完全相同，才能进一步怀疑 Claude Code 的本地配置或版本差异。
Foundry 模式能用 /login 和 /logout 吗？
不能按普通 Claude 账号 OAuth 的方式处理。Foundry 官方配置说明显示，Foundry 模式下这两个命令被禁用；Entra ID 应使用 Azure CLI，API Key 模式则检查 Foundry 配置中的密钥和资源信息。
Bedrock 模式为什么重复 /login 没用？
Bedrock 使用 AWS 凭据链、区域和 IAM 权限，Claude 账号登录不会替代 AWS 身份。应检查 AWS_REGION、AWS CLI 登录状态、模型访问和调用权限。
可以直接删除 ~/.claude 修复 403 吗？
不建议把删除配置目录作为第一步。先尝试对应认证方式的退出与重新登录，再用 /status 验证；云平台模式则使用 AWS、Google 或 Azure 的凭据流程。确需清理时先备份，并只删除已确认有问题的配置。
常见问题
Claude Code API 403 是不是账号被封了？
不一定。403 只说明某一层拒绝请求，可能来自账号、组织策略、模型权限、云平台 IAM、网关 ACL、代理或 WAF。先看完整错误文案、响应头和 /status。
已经登录了，为什么仍然 API 403？
环境变量、网关凭据、Bedrock、Vertex 或 Foundry 可能接管请求。请检查 API provider、Base URL、Key 来源、模型和当前终端环境。
为什么 curl 成功但 Claude Code 仍然 403？
两次请求可能使用了不同 Key、Base URL、模型、代理、认证头或运行环境。只有配置完全相同，才能进一步定位 Claude Code 本地配置或版本差异。
Foundry 模式能用 /login 和 /logout 吗？
不能按普通 Claude 账号 OAuth 处理。Foundry 官方配置说明显示，这两个命令在 Foundry 模式下被禁用，应使用 Azure CLI 或 Foundry API Key。
Bedrock 模式为什么重复 /login 没用？
Bedrock 使用 AWS 凭据链、区域和 IAM 权限。应检查 AWS_REGION、AWS CLI 登录状态、模型访问和调用权限，而不是重复 Claude 账号登录。
相关阅读
- Claude Code 接 Anthropic 兼容 API 的配置与验证
- Windows Claude Code 配置 API Key 的分平台步骤
- CLI 工具配置 API Key 时如何确认登录方式
- 查看更多 AI API 接入与错误排查指南