Cursor 自定义中转站时 Base URL 与鉴权头怎么填?

文章导读
很多 Cursor 用户只要在设置里换一个 API Key,就以为配置完成了。实际自定义中转站时,真正决定请求能不能通的,是 Base URL 和鉴权头这两个字段。这两个字段填错,后续请求会直接报错,而且错误提示往往只是一个笼统的 401 或 connection failed。先判断场景再动手:如果你只用官方客户端、走标准接口,不需要自定义;需要改的通常是企业内网出口、自建兼容服务、第三方合规渠
📋 目录
  1. 一 自定义 Base URL 和鉴权头到底在改什么
  2. 二 Base URL 先分清“带不带 /v1”
  3. 三 鉴权头不是只填 token
  4. 四 填完配置先做连通性验证
  5. 五 容易忽略的五个检查点
A A

很多 Cursor 用户只要在设置里换一个 API Key,就以为配置完成了。实际自定义中转站时,真正决定请求能不能通的,是 Base URL 和鉴权头这两个字段。这两个字段填错,后续请求会直接报错,而且错误提示往往只是一个笼统的 401 或 connection failed。先判断场景再动手:如果你只用官方客户端、走标准接口,不需要自定义;需要改的通常是企业内网出口、自建兼容服务、第三方合规渠道,或者本地网关做了协议转换。自定义中转站不是把地址随便换一个就行,你要先拿到中转站方给出的接口约定,再回填进 Cursor 设置。

自定义 Base URL 和鉴权头到底在改什么

Cursor 发请求时只做两件事:把模型名、消息内容、参数按 OpenAI 兼容格式打包,再把请求发到你指定的服务端地址。Base URL 决定请求发到哪,鉴权头决定服务端认不认你。市面上大多数中转服务都兼容 OpenAI 协议,所以 Cursor 本身不区分“官方”和“中转”,只认地址和请求头。

如果你要对接的服务端不是 OpenAI 兼容协议,而是自己定义的接口,那么从适用场景来说,就不建议在 Cursor 里强行改 Base URL——除非你能保证 Cursor 发出的请求体结构恰好能被你的服务端解析。遇到这种情况,先确认你的服务端有没有兼容层,而不是直接怀疑 Cursor 配置。

Base URL 先分清“带不带 /v1”

常见的 Base URL 写法是 https://api.example.com/v1。有些服务端要求你填到带 /v1,有些要求省略,由服务端自己补路径;还有少数服务端要求填到 /v1/chat/completions 的上级目录。这里要看你的版本/配置,不同版本对 Base URL 的拼接方式可能不同,填完后看实际请求日志最准。

Cursor 自定义中转站时 Base URL 与鉴权头怎么填?

先用 curl 验证是最快的方式。假设你拿到的地址是 https://api.example.com/v1,可以这样发一个测试请求:

curl -i https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}],"max_tokens":5}'

如果返回正常的 choices 内容,说明地址对;如果返回 404 或 405,考虑是不是该补 /v1 或者去掉 /v1。还有一种情况是地址末尾的斜杠差异,比如 /v1/ 和 /v1 在某些版本里会拼出不同结果,这种问题靠肉眼很难发现,只能靠服务端访问日志确认。

鉴权头不是只填 token

最通用的鉴权头是 Authorization: Bearer <token>,但自定义中转站不一定会用这个格式。有些服务端用 X-API-Key,有些用自定义名称,比如 Hosted-API-Key。Cursor 的鉴权头输入框里要写完整键值,形如 Bearer sk-xxx,而不是只填 sk-xxx。部分服务端兼容不带 Bearer 的写法,但不要赌。

如果中转站要求额外带一个自定义请求头,比如 X-Project-ID,你需要先确认当前 Cursor 版本是否允许设置额外的 Header。不允许的话,就把这个头固定在中转站那一侧,不要在 Cursor 里硬塞。风险边界很清晰:返回 401 代表鉴权头格式或值不对,403 通常是 IP 白名单、地区限制或 key 没有权限,404/405 则多是路径问题。按这个方向排查,比反复换 Key 有效。

Cursor 自定义中转站时 Base URL 与鉴权头怎么填?

填完配置先做连通性验证

在 Cursor 设置界面填完,先用一个轻量模型发一句固定测试文本,不要一上来就跑到复杂任务。观察返回的错误体:OpenAI 兼容服务的错误一般是 JSON,类似 {"error":{"message":"...","type":"invalid_request_error","code":"invalid_api_key"}}。如果 Cursor 里看不到完整错误响应,就用上面的 curl 请求先验证。

如果你自己维护中转服务,打开访问日志,确认请求头里的 Authorization 确实到达了你的服务端。例如 Cursor 里写的是 https://api.example.com/v1,日志里显示实际请求的是 /v1/chat/completions,说明地址拼接正确;如果日志里出现的是 /chat/completions,那就是 Base URL 多写了一段,或者少写了 /v1。配置修改后如果没生效,别急着反复保存,先检查是不是环境变量覆盖了设置界面的值。

容易忽略的五个检查点

  • 环境变量覆盖:Cursor 支持通过环境变量注入 Key 时,设置界面里的值可能被环境变量覆盖,表现是你改了界面配置但请求还是旧的。
  • 末尾斜杠:/v1 和 /v1/ 在部分版本里解析结果不同,路径拼接可能重复,需要结合环境确认。
  • SSL 证书:内网中转站常用自签名证书,系统不信任时请求会失败,报错往往不是鉴权问题而是 TLS 握手失败。
  • 网络出口过滤:某些网络会剥掉 Authorization 头,导致 curl 正常但 Cursor 异常,这种时候抓包或看网关日志才能定位。
  • 不要手动拼 query 参数:例如在 Base URL 后面加 ?api-version=2024-02-15,除非服务端明确要求,否则容易干扰 Cursor 自己的请求构造。

配置自定义中转站,真正花时间的不是填两个字段,而是确认你填的地址和鉴权格式,与服务端约定一致。用 curl 先把请求链路打通,再把结果回填到 Cursor;遇到问题就直接看服务端访问日志,比反复重启 Cursor 有用得多。