Cursor / Claude Code 在国内用不了模型?按这个顺序查

2026-11-17 · 海桥

上个月帮一个朋友看他那台笔记本。Cursor 打开,模型选了 Claude,回车,转圈,然后一行小字:Model not available。他先把 Cursor 卸了重装,又把代理换了两个节点,一晚上没了。

我让他跑了一条命令,三秒钟定位到问题:他把 key 填进了系统环境变量,但 Cursor 是图形程序,压根没继承那个变量。

这类事我见过太多次。写下来,按排查耗时从短到长排。

先花三秒分清是客户端的问题还是 key 的问题

别一上来就翻设置。用 curl 直接打一次,把客户端排除在外:

curl -H "Authorization: Bearer $KEY" $BASE/chat/completions \
  -d '{"model":"...","messages":[{"role":"user","content":"hi"}]}'

能出 JSON,问题就在客户端那一侧;报 401 或连不上,问题在 key 或者地址,跟客户端无关。这一步做完,能省掉很多在设置页里反复点的时间。我见过有人在客户端里改了两个小时,最后发现是 key 复制时多带了一个空格。

名字对不上,报错不会告诉你

Model not available、404,这类八成是名字问题。各家对同一个模型的写法不一样,DeepSeek 要 deepseek-chat,本地 ollama 更直接——ollama list 里显示的是什么,你就得写什么。

教程里抄来的名字经常是半年前的。别猜,直接问服务端认哪些:

curl -H "Authorization: Bearer $KEY" $BASE/models

返回的 data[].id 原样填回去。这一步我后来干脆写进程序里了,配置里加个 "discover": true,让它自己去问,省掉一整类"名字猜错"的问题。

地址里那三个符号

Base URL 看着简单,错起来很隐蔽,因为报错经常指向别的地方。

写错的地方你看到的报错
末尾多一个斜杠404 或 401
该带 /v1 没带,或者反过来404
本地服务写成 https://直接连不上,没有 HTTP 状态码

照抄之前,先 curl 一下自己的地址,能返回 JSON 再往下走。这一步二十秒,比在客户端里试错快。

还有一种,看起来像网络问题其实不是

请求发出去了,界面一直转,最后超时,错误信息里什么线索都没有。我在自己的日志里撞过这个:HTTP/2 协商失败,连接看着是通的。

把客户端的 HTTP Compatibility Mode 切到 1.1,很多人这一步就好了。如果你不确定要不要试,反正它不改变任何配置,试错成本为零。

顺带说个旁证:Claude Code 那边 local proxy failed 也常是同一类问题——代理软件和客户端在协议层没谈拢,不是你的 key 有问题。

为什么这些坑会反复出现

上面每一步都不难,难的是它们会重复。你换一家模型,地址、名字、鉴权方式全变;对方调整一次区域策略,整套链路要重新验一遍。

根子在于客户端把模型钉死了。它认的是某一家的地址和某一家的名字,换人就等于换系统。

我这半年一直在做这件事的另一半:把模型那层抽出来,客户端只认一个入口。就是 mcp-bridge,一个 MCP 服务,背后接 DeepSeek、通义、智谱、Kimi 或者你本机的 ollama。换模型只改一个配置文件,客户端不动。

有个细节是我自己吃了亏才加的:上游不通时落回本机模型,同时在回执里明确写"这次是降级执行的"。不假装成功——不然你会在第二天才发现昨晚跑的东西全是用错模型出的。

另外每次调用都落一条本地记录,token、成本、延迟、失败原因,可以按项目分开。这个功能是被一个做外包的朋友催出来的,他要同时伺候三个客户,月底算不清账。

装完怎么确定真的成了

别靠感觉。跑 这五步:自检七项、体检零失败、mock 能调通、账本能出数、客户端能看到工具。哪一步断了,那一步的输出就是线索。

如果你已经卡了半天,把 python server.py --doctor 的输出发我,免费看一眼。17 项检查,通常能直接指出是哪一层。

要我远程帮你配通也行:¥499,三小时,跑不通不收钱。邮箱 1024720334@qq.com。

—— 海桥,做模型接入层。项目主页在这里。