Cursor 自定義 API 配置：Base URL 作用範圍與不生效排查
Cursor 自定義 API 能做的事比很多教程說的要少：在設定裡填 OpenAI API Key 並開啟 Override OpenAI Base URL，只會影響聊天、Agent 這類會呼叫"OpenAI 格式模型"的功能，Tab 補全仍然走 Cursor 自家的模型；而且請求是先發到 Cursor 的雲端、再由雲端轉發到你填的地址，所以 localhost 和內網地址填了也不會生效。弄清這兩點，大部分"配了沒反應"的問題就能定位。
下面先把作用範圍列成一張表，再給一條排查順序。文中提到的設定項名稱以撰寫時 Cursor 的英文介面為準，Cursor 更新頻繁，選單位置可能變化，遇到不一致請以 Cursor 官方文件 和你當前版本的設定頁為準。
Cursor 的自定義 API Key 和 Base URL 到底管什麼？
在 Cursor Settings 的 Models 頁面裡，通常能看到幾組 API Key 輸入框（OpenAI、Anthropic、Google 等），OpenAI 那一組下面有一個 Override OpenAI Base URL 的開關。它的含義是：凡是 Cursor 按 OpenAI 介面格式去呼叫的模型，都改為把請求發到你填的地址，並帶上你填的 Key。
幾個容易誤解的地方：
| 問題 | 實際情況 | 影響 |
|---|---|---|
| 覆蓋的是一個模型還是全部？ | 開啟 Override 後作用於所有走 OpenAI 格式的模型，不是隻改你新加的那個 | 你的端點不認識的模型名會直接報錯 |
| Tab 補全會走自定義端點嗎？ | 不會。Tab 用的是 Cursor 自家的補全模型 | 自定義 Key 不能替代 Cursor 訂閱裡的補全額度 |
| 請求從哪裡發出？ | 從 Cursor 的伺服器發出，不是從你的電腦直接發出 | localhost、127.0.0.1、192.168.x.x 無效，地址必須公網可達 |
| 所有功能都能用自定義模型嗎？ | 不一定。部分功能（例如某些 Agent 能力、程式碼應用）依賴 Cursor 自己的模型或特定能力，自定義模型可能不可選或表現不同 | 同一個模型在 Ask 能用、在 Agent 報錯是常見現象 |
| 填了 Key 會不會還走 Cursor 額度？ | 走自定義 Key 的那部分請求按你的 Key 計費；沒被覆蓋的功能（如 Tab）照常用 Cursor 的 | 賬單要分兩邊看 |
| 程式碼會不會經過 Cursor？ | 會。即使用自己的 Key，提示詞也是在 Cursor 服務端拼裝後轉發 | 涉及隱私時要同時看 Cursor 和端點方兩邊的資料政策 |
如果你選自定義端點是出於資料方面的考慮，要知道資料會同時經過 Cursor 和端點提供方兩家，兩份政策都要讀。怎麼讀資料政策可以參考用第三方 AI API 時，程式碼和對話會被看到嗎。
為什麼填了 Base URL 還是不生效？
Cursor 論壇裡的同類求助，原因大致是這幾類：
- 地址從公網訪問不到。 前面說過，請求由 Cursor 服務端發出。你本機能 curl 通，不代表 Cursor 的伺服器能訪問到。本地起的代理、公司內網閘道器、只在本機 hosts 裡解析的域名都屬於這一類。
- 路徑少了或多了
/v1。 大多數 OpenAI 相容端點要求 Base URL 寫到/v1為止，例如https://api.example.com/v1，Cursor 再自己拼接/chat/completions。寫成https://api.example.com或https://api.example.com/v1/chat/completions都可能 404。具體以端點方文件為準。 - 介面格式不匹配。 Override OpenAI Base URL 只會發 OpenAI 格式的請求。如果端點只支援 Anthropic 的 Messages 格式，或者對 OpenAI 格式支援不完整（比如不支援流式、不支援 tools 欄位），就會出現 Ask 能用、Agent 報錯的情況。
- 模型名不對。 你在 Cursor 裡新增的模型名要和端點
/v1/models返回的 id 完全一致，大小寫和字首都算。開啟 Override 後，Cursor 內建的其他 OpenAI 模型名也會發到你的端點，端點不認識就報錯，所以建議把用不到的模型在列表裡關掉。 - 網路層的 HTTP/2 問題。 有些網路環境（公司代理、部分安全軟體）對 HTTP/2 長連線處理不好，表現為請求掛起或流式輸出中斷。Cursor 設定的 Network 部分提供 HTTP 相容模式，可以切到 HTTP/1.1 再試。注意這個設定影響的是你的電腦到 Cursor 伺服器這一段，不是 Cursor 到你端點的那一段。
- Key 驗證沒過。點 Verify 時 Cursor 會發一個測試請求；驗證沒透過時，先看報錯原文定位原因，不要反覆重填。
一條可以照做的排查順序
按下面順序做，每一步只改一個變數。
第 1 步：先確認 Cursor 本身沒出問題
自定義端點不通時，先排除 Cursor 服務端故障，因為請求必須經過它。開啟 Cursor 掛了嗎 看當前報告，或在 API 狀態頁 查同步過來的 Cursor 官方狀態頁事件。cdnping 每 15 分鐘同步一次 Cursor 官方狀態頁。按 cdnping 同步到的記錄，2026-09-17 到 2026-10-17 期間 Cursor 狀態頁共有 25 起事件，其中 major 5 起、minor 20 起；例如 2026-10-13 00:22（UTC）開始的 "Degraded performance and errors across Cursor services" 持續約 165 分鐘。cdnping 自己的探測從 2026-10-17 才開始，這裡的事件數取自官方狀態頁的歷史記錄，視窗只有一個月，不是長期統計。
如果這段時間裡 Cursor 有事件，先等它恢復再排查自己的配置。事件等級和元件怎麼看，可以參考怎麼看 OpenAI 狀態頁和 Claude 狀態頁，方法對 Cursor 狀態頁同樣適用。如果同一時段其他 AI 服務也在報錯，可以對照 AI 服務故障盤點：2026 年 9–10 月 判斷是不是上游的共性問題。
第 2 步：用 curl 從公網驗證端點
不要只在本機測。最好在一臺雲伺服器上，或至少換一個網路執行：
# 把 BASE 換成你在 Cursor 裡填的 Base URL（通常以 /v1 結尾）
BASE="https://api.example.com/v1"
KEY="sk-xxxx"
# 1) 列模型：確認地址可達、Key 有效，並拿到準確的模型 id
curl -sS "$BASE/models" -H "Authorization: Bearer $KEY" | head -c 800; echo
# 2) 非流式對話：把 your-model-id 換成上一步返回的 id
curl -sS "$BASE/chat/completions" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"model":"your-model-id","messages":[{"role":"user","content":"ping"}]}'
# 3) 流式對話：Cursor 聊天使用流式，必須單獨測
curl -sSN "$BASE/chat/completions" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"model":"your-model-id","stream":true,"messages":[{"role":"user","content":"ping"}]}'
判斷方法：
- 第 1 條返回 HTML 頁面或 404：Base URL 路徑不對。
- 第 1 條通、第 2 條報 model not found：模型名不對。
- 第 2 條通、第 3 條沒有逐行返回
data:開頭的內容：端點不支援流式，Cursor 裡會表現為卡住或報錯。 - 三條都通，Cursor 裡仍然不行：問題在 Cursor 側的配置或功能限制，繼續第 3 步。
如果想順便看連線質量，可以用 cdnping 首頁的線上測速，它在瀏覽器裡測各家 AI API 的首次連線（含 DNS 與 TLS 握手）和往返時間。不過這測的是"你的瀏覽器到端點"，和"Cursor 伺服器到端點"不是同一條路徑，只能作為參考。延遲由哪幾段組成，見 AI API 延遲拆解：連線建立、閘道器往返與首 token 時間。
第 3 步：在 Cursor 裡收窄變數
- 在 Models 列表裡只保留一個你確認存在的模型 id，其他 OpenAI 模型先關掉。
- 重新點 Verify，記下報錯原文。
- 先在 Ask（問答）模式發一句簡單的話；能用之後，再切到 Agent 模式試同樣的問題。
- Ask 正常、Agent 報錯：大機率是端點對 tools/function calling 的支援不完整，或該功能本身不支援自定義模型。前者問端點方，後者看 Cursor 文件。
- 兩個模式都卡住、流式中斷：到 Network 設定裡切 HTTP 相容模式（HTTP/1.1），重啟 Cursor 後再試。
第 4 步：確認地址確實是公網可達的 HTTPS
如果你的端點跑在本地或內網，Cursor 服務端連不到它，這是架構決定的，換配置解決不了。需要部署到一個有公網域名、證書有效的地址上。順帶檢查一下域名解析是否在不同網路下一致，以及證書鏈是否完整，瀏覽器開啟 https://你的域名/v1/models 不報證書警告是最低要求。
排查檢查表
把上面的內容壓縮成一張表，排查時逐項勾：
| 檢查項 | 怎麼確認 | 透過標準 |
|---|---|---|
| Cursor 服務正常 | /down/cursor、/status | 當前無進行中的事件 |
| Base URL 路徑 | curl $BASE/models | 返回 JSON 模型列表 |
| 公網可達 | 在另一臺機器或網路執行 curl | 與本機結果一致 |
| 模型 id | 對照 /models 返回 | 與 Cursor 中填寫的完全一致 |
| 流式支援 | curl 帶 "stream":true | 逐行返回 data: |
| 其他模型已關閉 | Cursor Models 列表 | 只啟用端點支援的模型 |
| Verify 結果 | 設定頁 | 無報錯 |
| Ask / Agent 分別測試 | Cursor 聊天面板 | 至少 Ask 可用 |
| HTTP 相容模式 | Network 設定 | 流式卡頓時切 HTTP/1.1 再試 |
選端點時還要看什麼？
自定義端點接進 Cursor 以後，所有 OpenAI 格式的請求都會經過它，它出問題時 Cursor 的聊天和 Agent 也跟著不可用。接入前建議確認這幾項：
- 它返回的是不是你選的模型。 可以做一些一致性檢查，方法見怎麼確認 API 給你的是哪個模型。
- 可用率和計費是否公開、可核對。 評估方法見 AI API 中轉站怎麼選：可用率、計費、資料政策 8 項檢查。
- 其他工具能不能共用。 如果你同時在用 Claude Code、Codex，配置方式不一樣，可以對照 Claude Code 自定義 API 與 Codex、OpenCode 介面地址配置。Claude Code 側的連線報錯見 Claude Code 連線超時和報錯怎麼排查。
舉個例子，AGI Plan 是一個同時相容 OpenAI 和 Anthropic 介面格式的聚合閘道器（AGI Plan 是 cdnping 的商業合作方），Cursor 屬於"能填介面地址 + API Key"的工具之一，接入方式就是上面這套：Base URL 填它的地址，模型名照它 /models 的返回填寫。它在 https://agiplan.dev/api/status/requests?month=YYYY-MM 公開逐小時、逐能力組的請求成功與失敗計數，不需要登入，可以自己下載核對；站方也明確說明自己不是官方授權渠道。無論選哪家，都請先讀清服務條款，並遵守所在地的法規和各模型提供方的使用政策。
