Cursor 401 Unauthorized 怎么办？按账号、API Key 与 MCP 分步排查
简答：Cursor 401 Unauthorized 通常表示当前请求没有通过认证，常见位置是 Cursor 账号登录态、自定义 API Key、Base URL 与凭据传递方式。先确认 401 来自 Cursor 账号还是外部模型接口，再按“重新认证→验证 Key→核对入口→隔离 MCP”的顺序排查。不要把 401 当成模型不存在或限流问题，也不要直接删除未经核实的本地凭据文件。
定义：401 Unauthorized 是认证失败状态，表示服务端没有接受当前请求中的有效身份凭据；它不同于 403 权限不足、404 路径或模型不存在，以及 429 请求过多。
先看这一张表：401 到底来自哪一层
排查 Cursor 401 的第一步不是换模型，而是确认错误发生在什么环节。Cursor 既可能在登录账号时拒绝认证，也可能已经进入外部模型接口后，被 API 网关拒绝。两者的修复动作不同。
| 现象 | 优先怀疑位置 | 先做什么 | 成功标准 |
|---|---|---|---|
| 打开 Cursor 或登录时提示 Unauthorized、Login rejected | Cursor 账号登录态 | 退出账号并重新登录；检查浏览器完成的是否是同一账号 | 账号页面恢复，重新打开编辑器后不再要求认证 |
| 只在启用自定义模型后出现 401 | API Key、Base URL 或供应商入口 | 在设置中重新填入 Key，点击 Verify，并核对服务商要求的请求入口 | Verify 成功，模型列表或测试请求返回正常响应 |
| 模型能显示，但发送消息仍然 401 | 当前账号、项目或模型调用权限 | 把“能看到模型”和“有权调用模型”分开验证 | 实际最小请求返回成功，而不只是模型选择器出现名称 |
| 关闭 MCP 后 401 消失 | MCP 服务的环境变量、OAuth 或远程接口 | 单独检查 MCP 配置，不要把 MCP Token 当成模型 API Key | 逐个启用 MCP 后能确定具体服务 |
| 偶发失败并伴随 429、超时或 5xx | 请求频率、网络或服务端状态 | 先按实际 HTTP 状态码分流 | 错误类型与重试策略匹配 |
Cursor 官方文档说明，自定义 API Key 位于 Cursor Settings → Models，填写后需要点击 Verify；自定义 Key 只适用于标准聊天模型，部分依赖专用模型的功能不会因此切换到外部 Key。
最短排查步骤：从账号到 API Key 逐层确认
- 记录完整错误位置。保存错误出现的界面、时间、HTTP 状态码和响应体关键字段；把 API Key 中间内容打码，不要上传完整密钥或 Cookie。
- 确认是否是 Cursor 账号认证。如果错误发生在登录、账号页面或 Cursor 内置服务，而不是发送外部模型请求之后，先退出并重新登录。若使用 Cursor CLI，可按照官方认证文档运行
cursor-agent status查看状态，必要时运行cursor-agent logout清除已存储的 CLI 认证，再运行cursor-agent login重新认证。CLI 的这些命令只说明 CLI 登录状态，不等于桌面端自定义模型 Key 已经有效。 - 确认自定义 Key 的入口。进入 Cursor 设置中的 Models，删除输入框中多余的空格、引号和换行，重新粘贴 Key，然后点击 Verify。Cursor 文档列出的供应商包括 OpenAI、Anthropic、Google、Azure OpenAI 和 AWS Bedrock，但具体可用模型、认证方式和部署路径仍以对应供应商文档及当前控制台为准。
- 核对 Base URL 的完整路径。如果使用兼容接口，不要只检查域名。比较服务商提供的完整 Base URL、协议版本、路径和鉴权头；有些服务要求在客户端填写根地址，有些要求填写包含版本路径的入口。若无法从服务商当前文档确认路径，不要凭经验追加
/v1、/chat/completions或其他后缀。 - 核对 Key 与入口是否属于同一产品。一个服务商的 Key 不一定能访问另一个网关、区域或项目。特别是 Google API 场景，官方错误文档把 401 归为 Key 缺失、无效或过期，并把 403 单独定义为权限不足；因此应检查请求域名、鉴权头、Key 绑定项目和 API 限制，而不是只更换模型名称。
- 验证实际调用权限。模型选择器能列出名称，不代表当前项目一定有权调用。先选择一个已在当前控制台确认可用的标准聊天模型，发出最小文本请求；如果仍然返回 401，继续查认证链路，不要先扩大上下文、启用工具或切换流式。
如果重新登录后账号功能正常，但只有自定义模型失败，问题范围通常已经从“Cursor 账号登录”收窄到“外部接口认证”。这是排查中的定位结论，不代表某个具体服务商必然故障。
最小请求怎么验证：只测试认证，不制造新的变量
Cursor 设置页面中的 Verify 是最短路径；如果需要在 Cursor 之外复现，必须使用目标接口官方文档提供的请求格式。下面只给出通用检查模板，不是已核验的具体服务商命令。占位符、Base URL、模型 ID、鉴权头和请求路径都必须从当前官方文档或控制台确认，不能直接复制后当作可运行实例。
curl -i "$BASE_URL" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"MODEL_ID","messages":[{"role":"user","content":"Reply with OK"}]}'这个模板只用于说明核验思路：BASE_URL、MODEL_ID 和鉴权格式必须与目标接口匹配。密钥应通过环境变量传入，例如 API_KEY，不要写进 Shell 历史、项目文件、截图或 Cursor 规则文件。
检查结果时至少记录四项：
- HTTP 状态码：401 优先查身份凭据；403 查权限、项目或服务限制；404 查路径和模型；429 查限速或配额。
- 响应体：保留错误类型、消息、请求 ID 和服务名，遮盖 Key、Token、邮箱和私有路径。
- 鉴权方式：确认目标接口要求 Bearer、专用请求头、查询参数、OAuth，还是云平台凭据；不能把一种接口的 Key 传给另一种网关。
- 实际模型：先从当前项目的模型列表或控制台确认模型 ID，再进行最小文本请求；不要把列表可见误写成当前账号必然可调用。
以 Gemini API 为例，Google 官方文档把 401 解释为 API Key 缺失、无效或过期，并建议核验 Key；其 Key 文档还要求关注 Key 类型、项目关联、API 限制和安全存储。若你在 Cursor 中使用 Google 兼容入口，必须确认 Cursor 当前支持的鉴权方式与目标入口一致，不能仅凭模型名称判断配置正确。
MCP 也返回 401：与模型 API Key 分开排查
MCP 是另一条认证链路。Cursor 官方文档说明，MCP 服务可以通过环境变量传递 API Key 或 Token，远程 SSE 和 Streamable HTTP 服务还可能使用 OAuth；因此 MCP 返回 401 时，不能直接认定是 Cursor 的模型 Key 失效。
- 在 Cursor 中暂时关闭或移除一个 MCP 服务，确认模型对话是否恢复。
- 一次只重新启用一个 MCP，记录具体服务名称、传输方式和错误响应。
- 检查
.cursor/mcp.json或用户级 MCP 配置中的环境变量名称是否与 MCP 服务端要求一致。 - 如果服务要求 OAuth，重新完成该 MCP 服务的登录流程；不要把模型 API Key 填到 OAuth Token 字段。
- 确认环境变量在 Cursor 启动时可见。修改 Shell 配置后，需要按照系统和客户端的实际行为重新启动相关进程。
Cursor 官方 MCP 文档列出了项目级配置和用户级配置，并明确提醒 MCP 服务器可能访问外部服务、数据和代码。若某个 MCP 的 Token 曾出现在日志、仓库或截图中，应在对应服务端撤销并重新生成，而不是只在本地修改配置。
关于 auth.json、系统 safe-storage 或某个固定缓存文件路径，当前已核实的 Cursor 官方资料不足以支持一个跨平台通用删除命令。因此本文不提供猜测性的文件路径。若退出重登和单个 MCP 隔离仍不能解决，应使用 Cursor 当前版本支持的账户退出、MCP 登录、诊断日志和官方支持渠道处理。
错误分流：哪些情况不要按 401 处理
| 状态码或表现 | 通常表示 | 处理动作 |
|---|---|---|
| 401 Unauthorized | 认证信息缺失、无效、过期，或鉴权方式与入口不匹配 | 检查登录态、Key 完整性、鉴权头、项目和目标域名 |
| 403 Forbidden | 身份已识别，但没有访问资源的权限 | 检查项目、组织、区域、模型权限和 Key 限制 |
| 404 Not Found | 路径、版本、部署名或模型 ID 不存在 | 对照当前官方 API 文档和控制台确认完整路径 |
| 429 Too Many Requests | 请求频率、并发或配额超限 | 降低并发并按服务商规则退避；不要靠反复换 Key 解决 |
| 超时或流式中断 | 网络、代理、连接保持或服务端处理时间问题 | 先用非流式最小请求确认认证，再单独测试流式 |
Google 官方 API 错误文档也将 401、403、404 和 429 分开处理。对于 401，不建议无限重试，因为凭据没有变化时，重试通常不会改变认证结果；对于 429，才需要依据服务商规则考虑退避。
安全边界：修复 401 时不要泄露 Key
- 不要把完整 API Key、Cursor 登录 Token、OAuth 刷新 Token 放进工单、论坛、截图、仓库或公开日志。
- 如果 Key 曾经泄露，先在对应平台撤销或轮换，再更新 Cursor 设置和环境变量。
- 优先使用环境变量或系统密钥存储，避免把密钥硬编码到项目代码、MCP 配置仓库或客户端规则中。
- 只授予当前任务需要的最小权限；MCP 服务器和外部工具可能访问文件、网络或第三方数据，安装前先审查来源和权限。
- 修改配置后只验证一个变量：先验证账号，再验证 Key，再验证模型，最后启用 MCP 和工具。一次改多个变量，会让 401 的根因难以判断。
如果需要使用 API 中转或 OpenAI 兼容接口，先确认服务商公开的 Base URL、支持协议、模型 ID 和认证方式。无法从当前官方资料逐项核验的内容，应标记为“需核实”，不要根据客户端能否保存配置就推断接口一定支持。
常见问题
Cursor 能看到模型，为什么发送消息仍然 401？
模型列表可见只说明客户端拿到了某种目录信息，不等于当前项目、账号或 API Key 有调用权限。请在当前控制台确认项目和模型权限，再用一个最小文本请求检查实际 HTTP 状态码与响应体；如果仍是 401，优先检查鉴权方式和 Key 是否属于该入口。
重新登录后仍然 401，是不是一定要删除本地缓存？
不一定。先区分桌面端账号登录和外部模型 API 认证：如果账号页面已经正常，只有自定义模型请求失败，就不应把问题归因于本地登录缓存。当前已核实的官方资料没有提供一个适用于所有系统和版本的 auth.json 或 safe-storage 删除路径，因此不要执行未经核实的删除命令。
把 OpenAI、Anthropic 或 Google 的 Key 互换测试可以吗？
不建议。不同供应商的 Key、Base URL、鉴权头和模型路径可能不同。Cursor 官方列出多个可接入供应商，但这不表示它们共享认证格式。应按照目标供应商的当前文档填写，并通过 Verify 或最小请求分别验证。
MCP 报 401 会影响 Cursor 的普通模型对话吗？
可能影响部分依赖该 MCP 的任务，但不应直接推断模型 API Key 失效。先关闭单个 MCP，再测试普通对话；如果普通对话恢复，检查该 MCP 的环境变量、OAuth 状态、远程 URL 和服务端权限。
401 时应该不断重试或更换模型吗？
不应该。认证凭据没有变化时，重复请求通常不会解决 401；更换模型还可能把认证问题混淆成模型兼容性问题。先记录状态码和响应体，验证 Key、入口、项目和鉴权方式，确认认证成功后再检查模型。
常见问题
Cursor 401 和 403 的排查重点有什么不同？
401 先检查身份凭据、Key、鉴权头和目标入口；403 则重点检查项目、组织、区域和模型权限。请以原始 HTTP 状态码和响应体为准，不要只看客户端摘要。
Cursor 的 Verify 成功是否代表所有功能都能使用？
不代表。Cursor 文档说明自定义 API Key 主要用于标准聊天模型，依赖专用模型的功能可能仍使用 Cursor 内置模型。Verify 成功后还要用实际功能和目标模型分别验证。
如何判断 401 是 MCP 引起的？
暂时关闭一个 MCP 后发送同一条普通模型请求；如果恢复，再逐个启用 MCP，并检查对应的环境变量、OAuth 登录状态和远程服务响应。不要把 MCP Token 与模型 API Key 混用。
排查 401 时可以直接删除 auth.json 吗？
不建议。当前已核实的官方资料没有提供适用于所有系统和版本的通用 auth.json 删除路径。优先使用客户端或 CLI 提供的退出、登录和 MCP 登录命令，避免误删配置或凭据。
相关阅读
参考资料
- Cursor API Keys：自定义 API Key、Verify 与支持的供应商（docs.cursor.com）
- Cursor CLI Authentication：登录、状态检查与退出认证（docs.cursor.com）
- Gemini API 官方错误码：401、403、404 与 429 的区分
- Gemini API 官方 Key 文档：项目、限制与安全存储