连上OpenRouter前，先用这个脚本验证你的Cursor配置

把Cursor接到OpenRouter自定义API，最让人头疼的不是配置过程本身，而是出错时你根本不知道问题出在哪一环。有时候Cursor会弹出一个明确的报错，有时候某个模式只是悄悄停止产出有用结果，界面上没有任何明显信号告诉你为什么。

在信任编辑器内的配置之前，先用一个独立脚本验证连接是否真的通了，这样将来遇到任何异常，你都能判断是Cursor客户端的问题，还是API本身出了问题。这篇文章就提供一个可以直接运行的验证脚本，以及配置Cursor时需要注意的几个关键点。

为什么要在编辑器外先验证

Cursor在自定义API连接失败时的错误信息并不总是有帮助。你可能会遇到两种情况：一种是收到清晰的错误提示，另一种是某个模式静默失效——不报错，但输出质量明显下降或干脆没有输出。这种情况下，你很难判断是Cursor的配置问题，还是OpenRouter的API密钥或端点出了问题。

在编辑器外先用一个纯脚本验证连接，就能把变量隔离出来。脚本跑通了，说明你的API密钥有效、端点配置正确、模型ID可用；如果脚本正常但Cursor仍然表现异常，问题就锁定在Cursor客户端的行为上，而不是你的凭据或端点配置。

Cursor专用的OpenRouter端点

OpenRouter为Cursor的请求格式提供了一个专用端点：https://openrouter.ai/api/v1/cursor，而不是通用的OpenAI兼容API调用所用的标准路径/api/v1。这个端点目前处于beta阶段，在假设其行为完全稳定之前，值得先查看OpenRouter自己的API文档确认当前状态。

这个专用端点的存在是有原因的——Cursor的请求格式与标准的OpenAI兼容格式存在差异，OpenRouter专门为它做了适配。如果你用错了端点路径，即使API密钥和模型ID都正确，连接也可能失败或行为异常。

验证脚本：直接跑，别猜

下面这个Python脚本会向Cursor专用端点发送一个简单的测试请求，并检查响应状态。你需要先安装requests库（pip install requests），然后把脚本中的API密钥替换成你自己的OpenRouter密钥。

脚本的核心逻辑很简单：向https://openrouter.ai/api/v1/cursor/chat/completions发送一个POST请求，要求模型回复"connection ok"，然后检查HTTP状态码和响应内容。如果返回200且内容正确，说明连接正常；否则会打印出错误信息供你排查。

脚本中预设了两个模型ID供测试：anthropic/claude-3.5-sonnet和openai/gpt-5.6-mini。你可以根据自己实际要用的模型替换这些ID。运行脚本后，它会逐个检查每个模型ID的连接情况，并打印出状态码和响应内容。

运行这个脚本能确认两件事

第一，你的OpenRouter API密钥是否有效，以及它是否有权限访问你计划使用的模型。第二，Cursor专用端点本身是否对这些模型ID正确响应。这两点独立于Cursor的界面验证，能帮你把问题定位到具体环节。

如果脚本运行成功但Cursor仍然表现异常，你就把问题隔离到了Cursor的客户端行为上——不是你的凭据或端点配置有问题。这个结论能省下大量排查时间，避免在错误的方向上反复折腾。

配置Cursor本身的步骤

脚本确认连接正常后，再在Cursor里做配置。打开Cursor → 进入Settings → Models，然后按以下步骤操作：

• 启用"Override OpenAI Base URL"选项
• 输入https://openrouter.ai/api/v1/cursor（注意不是普通的/api/v1路径）
• 在API密钥字段粘贴你的OpenRouter密钥
• 添加一个自定义模型，使用你在脚本中验证过的同一个模型ID
• 点击Verify确认配置

这里有一个容易踩的坑：Base URL必须用Cursor专用端点，而不是标准的OpenAI兼容路径。用错路径可能导致连接失败或行为异常，而且错误信息不一定能帮你快速定位到这个问题。

实际使用中哪里容易出问题

按上述方式配置后，基于聊天的模式（Chat-based modes）能立即正常工作。但Agent模式的表现就不那么一致了——Cursor对自定义API连接的支持在历史上并没有在所有模式下都保持一致，即使在相邻的文档中，你也可能找到互相矛盾的信息。

这意味着，即使脚本验证通过、Chat模式工作正常，Agent模式仍可能出现问题。这不是你的配置错误，而是Cursor对自定义API连接的支持在不同模式间存在差异。遇到这种情况，建议查阅Cursor最新的官方文档，确认当前版本对Agent模式的自定义API支持状态。

把验证变成习惯

这个脚本的价值不在于一次性验证，而在于它给了你一个可重复的排查工具。每次更换模型、更新API密钥或遇到异常行为时，先跑一遍脚本，就能快速判断问题出在哪个环节。省下的时间，远比写这个脚本花的时间多。