打通 Cursor 与 OpenRouter API 的终极排错指南

这份文档将引导您完成从基础设置到解决各种棘手错误的全部流程，确保您能成功在 Cursor 中使用 OpenRouter 提供的强大模型。

第一部分：基础设置

这是所有操作的起点，请确保每个细节都正确无误。

获取 OpenRouter API 密钥：

登录 OpenRouter.ai 账户。
在账户设置中创建并复制一个新的 API Key。

配置 Cursor：

打开 Cursor 设置 (Settings -> Models -> API Keys)。
关键步骤：在 OpenAI API Key 字段中，粘贴您从 OpenRouter 获取的 API 密钥。
启用 Override OpenAI Base URL 开关。
确保下方的 URL 地址是：https://openrouter.ai/api/v1。

第二部分：核心难点 — 解决“验证”按钮无响应的 Bug

这是最常见也最令人困惑的问题。当您点击“Verify”按钮后没有任何反应，这通常是 Cursor 的一个界面 Bug，需要使用高级方法绕过。

打开开发者工具：

在 Cursor 中，按下快捷键 Ctrl + Shift + P (Mac: Cmd + Shift + P) 打开命令面板。
输入 Developer: Toggle Developer Tools 并回车。

允许粘贴代码：

在打开的开发者工具窗口中，切换到 Console (控制台) 选项卡。
您会看到一个安全警告。请在控制台中输入 allow pasting 并按回车。

运行“欺骗”脚本：

将以下代码完整复制并粘贴到控制台，然后按回车运行。

(function() {
  const originalFetch = window.fetch;
  window.fetch = async function(url, options) {
    if (url.includes('chat/completions')) {
      return new Response('{}', {
        status: 200,
        statusText: 'OK',
        headers: {'Content-Type': 'application/json'}
      });
    }
    return originalFetch(url, options);
  };
})();

完成验证：

不要关闭开发者工具，切回 Cursor 设置界面，再次点击 Verify 按钮。
此时，验证应该会立即通过。成功后即可关闭开发者工具。

第三部分：常见后续错误及解决方案

即使验证通过，在实际使用中也可能遇到新的错误。以下是两个最关键的错误及其解决方法。

错误一：`ERROR_BAD_USER_API_KEY` (密钥无效或模型权限问题)

错误表现：当您在聊天窗口提问时，收到 “Unauthorized User API key” 的错误。

问题诊断：这个错误提示具有误导性。如果您已通过 curl 命令测试成功，那么问题不是 API 密钥本身错了，而是您当前选择的模型，您的账户无权使用。

解决方案：

回到 Settings -> Models 页面。
添加一个最基础、最通用的模型进行测试，例如 openai/gpt-3.5-turbo。
在聊天窗口选择这个基础模型提问。如果成功，则证明您的整体连接是通的。

错误二：`No endpoints found that support tool use` (模型功能不支持)

错误表现：在使用某些需要分析代码、联网等复杂功能时，出现此 404 Not Found 错误。

问题诊断：这是因为您选择的模型不支持 Cursor 请求的 “工具使用” (Tool Use) 高级功能。

解决方案：

访问 OpenRouter.ai 网站的 Models 页面。
使用筛选器，勾选 Features -> Tool Use，筛选出支持此功能的模型。
从列表中选择一个模型（如 google/gemini-pro, anthropic/claude-3-sonnet-20240229 等），复制其完整名称。
回到 Cursor 中，添加并选择这个功能更强大的新模型。

第四部分：其他潜在问题检查

如果以上步骤仍未解决问题，请检查您的 settings.json 文件 (Ctrl/Cmd + Shift + P -> Preferences: Open User Settings (JSON))：

代理问题：检查是否存在 "http.proxy" 设置。如果您的代理软件配置不当，可能会干扰 API 请求。最简单的测试方法是暂时移除或注释掉此行，然后重启 Cursor。
协议问题：如果在代理环境下遇到连接问题，可以尝试添加 "cursor.general.disableHttp2": true 来强制使用兼容性更好的 HTTP/1.1 协议。

希望这份详尽的指南能为您提供清晰的路线图，祝您使用愉快！