1. Cursor Remote-SSH 连不上时先别急着重装
Cursor 是基于 VS Code 分支做的编辑器，Remote-SSH 这套远程开发能力它基本照搬了过来，但扩展市场、扩展版本策略和 VS Code 并不完全同步。这就导致一个很典型的现象：同一台远程主机，VS Code 里 Remote-SSH 连得好好的，换到 Cursor 就卡在 "Setting up SSH Host" 或者直接弹 "Could not establish connection"。你搜 "cursor ssh 连接不上" 大概率就是撞上了这个坑。
先说清楚这篇适合谁：你已经在用 Cursor 做本地开发，想通过 Remote-SSH 把代码放到远程 Linux 主机上跑；或者你之前用 VS Code 远程开发很顺，迁移到 Cursor 后连接失败。核心检索词就是 Cursor Remote-SSH 连接失败、扩展版本不匹配、VSIX 手动安装这几个。
Remote-SSH 的工作原理其实不复杂：本地 Cursor 装一个 Remote-SSH 扩展，扩展通过你配置的 SSH 命令登录远程主机，然后在远程主机上下载并启动一个 "VS Code Server" 服务端进程，本地再通过这个进程做文件读写、终端、调试。整条链路里任何一环版本对不上，都会断。
最常见的断点有三个。第一，远程主机系统内核或 glibc 太旧，新版 VS Code Server 起不来。第二，本地 Cursor 自动装的 Remote-SSH 扩展版本太新，和远程服务端协议不匹配。第三，扩展自动更新把你手动装好的旧版本又覆盖回去了。这三个里，第二个和第三个是 Cursor 特有的，因为 Cursor 的扩展管理行为跟 VS Code 有差异。
我试过在一台 CentOS 7 的老机器上折腾，VS Code 能连，Cursor 死活连不上，日志里反复出现 "Server installation failed" 和版本相关的报错。后来定位到就是扩展版本问题。下面按排查顺序一步步来，每一步都有可复制的配置和验证动作，你照着做基本能复现并修好。
先明确一个判断标准：如果 VS Code 能连、Cursor 不能连，那问题几乎一定在 Cursor 这一侧的扩展或配置，而不是网络或远程主机本身。这个判断能帮你省掉大量排查网络的时间。反过来，如果两个都连不上，那才需要去看 SSH 配置、防火墙、远程主机状态这些。
2. TaoToken 前置：给 Cursor 配好模型与 API 入口
在深入 Remote-SSH 排障之前，先把 Cursor 的模型调用链路理顺，因为很多人连上远程后第一件事就是让 Cursor 的 AI 功能在远程环境里也能用。Cursor 本身支持自定义 API 入口，你可以把模型请求指向兼容 OpenAI 协议的服务。TaoToken 提供的就是这样一个统一入口，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。
这里要区分两件事：Remote-SSH 解决的是 "代码在哪台机器上跑"，TaoToken 解决的是 "AI 请求发到哪个模型服务"。两者不冲突，但配置位置不同。Remote-SSH 的配置在 Cursor 的 settings.json 和 SSH config 里，模型 API 的配置在 Cursor 的模型设置或环境变量里。
如果你打算在远程主机上跑 Cursor 的 AI 功能，注意一个细节：Cursor 的 AI 请求默认是从本地发起的，不是从远程主机发起。所以你在本地配好 API 入口就行，远程主机不需要单独配。但如果你在远程终端里跑命令行工具（比如某些 CLI Agent），那远程主机上需要能访问到 API 地址。
配置模型入口时，Base URL 填 https://taotoken.net/api ，Key 用你在控制台生成的 API Key，Model ID 按你实际要用的模型填。这三件套（Base URL + Key + Model ID）是任何兼容 OpenAI 协议的客户端都要对齐的，缺一个都会报 401 或 model not found。
获取 Key 的路径是：登录后进控制台，在 API Keys 页面创建。文档在 https://taotoken.net/doc 可以查到具体的请求格式和可用模型列表。如果你只是想先验证模型能不能通，用模型对话页面 https://taotoken.net/chat 发一条消息最快，不用写代码。
对于长期在远程主机上做编码、跑 Agent 的场景，Coding Plan 会更合适，地址是 https://taotoken.net/coding-plan 。它针对高频编码请求做了优化，比按次调用更划算。这个不是必须的，但如果你每天大量用 AI 写代码，值得看一眼。
把模型入口配好之后，再回到 Remote-SSH 的排障。顺序上建议先修连接，再调模型，因为连接不通的话，远程环境里的 AI 功能根本没法验证。
3. 可复制配置：settings.json 与 SSH config 片段
这一节给可直接复制的配置。先看 Cursor 的 settings.json，路径在本地机器上：
- Windows:
C:\Users\<你的用户名>\AppData\Roaming\Cursor\User\settings.json - macOS:
~/Library/Application Support/Cursor/User/settings.json - Linux:
~/.config/Cursor/User/settings.json
关键配置片段如下，重点是关掉 Remote-SSH 扩展的自动更新，否则你手动装的旧版本会被覆盖：
{ "remote.SSH.showLoginTerminal": true, "remote.SSH.useLocalServer": false, "remote.SSH.connectTimeout": 60, "remote.SSH.remotePlatform": { "your-host-alias": "linux" }, "extensions.autoUpdate": false, "extensions.autoCheckUpdates": false, "remote.SSH.enableRemoteCommand": true }逐条解释。showLoginTerminal设为 true 后，连接时会弹出终端显示 SSH 登录过程，方便你看卡在哪一步。useLocalServer设为 false 是很多老服务器的兼容关键，它让连接走标准 SSH 而不是本地代理模式，能绕开一部分 "local proxy failed" 的报错。connectTimeout给到 60 秒，老机器建立连接慢，默认值容易超时误判。remotePlatform显式声明远程主机是 linux，避免 Cursor 猜错平台。extensions.autoUpdate和autoCheckUpdates都关掉，这是防止手动装的 VSIX 被自动更新覆盖的核心。
再看 SSH config，路径在~/.ssh/config（Windows 也是这个路径，在用户目录下）：
Host your-host-alias HostName 192.168.1.100 User youruser Port 22 IdentityFile ~/.ssh/id_rsa ServerAliveInterval 30 ServerAliveCountMax 6 TCPKeepAlive yesServerAliveInterval和ServerAliveCountMax是防断连的，远程开发长时间挂着，没有心跳容易被中间网络设备掐断。TCPKeepAlive yes配合使用。这些参数对 Cursor 和 VS Code 都生效，因为底层都是调 ssh 命令。
如果你用的是密钥登录且密钥有 passphrase，建议在本地用 ssh-agent 加载，否则 Cursor 每次连接都可能卡在密码输入。加载命令：
eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_rsaWindows 上用 PowerShell 的话，先确认 OpenSSH Authentication Agent 服务已启动，然后ssh-add同样可用。
配置改完后，重启 Cursor 让 settings.json 生效。注意 Cursor 有时候不会立即重载扩展配置，最稳妥是彻底退出再打开。
4. 验证请求与成功结果：从日志到连接恢复
配置就位后，开始逐条验证。第一步，先在本地终端确认 SSH 本身能通：
ssh -v your-host-alias-v打开详细日志，你能看到密钥协商、认证、登录全过程。如果这一步就失败，那问题不在 Cursor，先修 SSH。如果这一步成功，说明网络和认证没问题，继续下一步。
第二步，在 Cursor 里按Ctrl+Shift+P（macOS 是Cmd+Shift+P）打开命令面板，输入Remote-SSH: Connect to Host，选择你的主机别名。这时如果showLoginTerminal开了，会弹出终端。观察终端输出，重点看有没有 "Server installation" 相关的行。
第三步，看 Cursor 的 Remote-SSH 输出日志。路径是：View→Output，右上角下拉选Remote-SSH。这里会打印扩展版本、服务端下载地址、安装结果。如果看到类似 "Downloading server" 后失败，或者 "Server version mismatch"，基本就是版本问题。
第四步，确认扩展版本。在 Cursor 里点左侧扩展图标，搜索Remote-SSH，点进去看版本号。同时打开 VS Code，同样看它的 Remote-SSH 版本号。两个版本不一致时，把 Cursor 的版本回退到和 VS Code 一致，或者回退到一个已知能连老服务器的版本。
回退的具体操作：先在 Cursor 扩展面板里卸载 Remote-SSH，然后手动下载指定版本的 VSIX。下载链接格式是：
https://marketplace.visualstudio.com/_apis/public/gallery/publishers/ms-vscode-remote/vsextensions/remote-ssh/0.113.1/vspackage把0.113.1换成你要的版本号。下载下来是个.vsix文件。然后在 Cursor 里Ctrl+Shift+P，输入Extensions: Install from VSIX...，选中刚下载的文件安装。
安装完记得确认extensions.autoUpdate已经是 false，否则下次重启又被更新覆盖。这一步是很多人反复失败的原因——装好了，一重启又回到新版，连接再次失败。
成功的结果长这样：命令面板执行连接后，左下角状态栏显示SSH: your-host-alias，远程文件树能正常展开，集成终端能执行uname -a并返回远程主机信息。到这一步，Remote-SSH 就算修好了。
如果你还想在远程环境里验证模型调用，可以在远程终端里用 curl 测一下 API 入口：
curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY"返回模型列表就说明远程主机到 API 的网络是通的。注意这里用的是 API 地址，不带任何查询参数。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
排障时你会遇到几类典型报错，逐个对照。
401 Unauthorized：这个通常出现在模型 API 调用，不是 Remote-SSH 本身。原因一般是 Key 没填、填错、或者 Base URL 写成了带路径的地址。检查三件套：Base URL 必须是https://taotoken.net/api，Key 从控制台复制完整，Model ID 拼写正确。如果是在远程终端里跑 CLI 工具报 401，确认远程主机的环境变量TAOTOKEN_API_KEY已经 export，且没有多余空格。
local proxy failed：这是 Remote-SSH 的报错，出现在 Cursor 尝试用本地代理模式建立连接时。解决办法就是把remote.SSH.useLocalServer设为 false，强制走标准 SSH。改完重启 Cursor。这个报错在老版本 Cursor 上尤其常见。
reading choices 相关报错：这类报错一般出现在扩展加载或服务端握手阶段，日志里会有 "Error reading choices" 或类似的解析失败。根因多半是扩展版本和服务端协议不匹配。回退 Remote-SSH 扩展版本到和 VS Code 一致，通常能解决。如果回退后还报，检查远程主机上~/.cursor-server目录（Cursor 的服务端目录）是否有残留的旧版本文件，删掉让它重新下载。
OAuth 相关报错：如果你在 Cursor 里登录账号或授权时遇到 OAuth 失败，先确认本地网络能正常访问授权页面。这类问题跟 Remote-SSH 无关，是账号体系的事。如果是在远程环境里触发 OAuth，注意回调地址默认指向 localhost，远程环境需要端口转发才能完成回调。简单办法是在本地完成授权，再连远程。
再补一个高频坑：远程主机磁盘满了。VS Code Server 和 Cursor Server 都要在远程主机写文件，磁盘满会导致服务端启动失败，日志里可能只显示 "Server installation failed" 而不说原因。用df -h检查一下~所在分区。
还有一个：远程主机的~/.cursor-server和~/.vscode-server权限不对。如果你用 root 装过又用普通用户连，目录属主会乱。ls -la ~/.cursor-server看一眼，必要时chown -R youruser:youruser ~/.cursor-server。
对照完这些，大部分连接问题都能定位。核心思路就一句：先确认 SSH 本身通不通，再确认扩展版本对不对，最后看远程服务端目录和磁盘。
6. 语义一致 CTA：把连接和模型入口都收尾
Remote-SSH 修好之后，你的 Cursor 就能在远程主机上顺畅开发了。接下来如果要把 AI 编码能力也接上，按场景选入口。
排障和接入过程中遇到 API 配置问题，去 API Keys 页面拿 Key，再去接入文档对照请求格式：API Keys 在 https://taotoken.net/api-keys ，文档在 https://taotoken.net/doc 。这两个是配模型入口的必经路径。
只是想快速验证某个模型能不能用、回答质量如何，直接用模型对话页面发消息：https://taotoken.net/chat 。不用写代码，选模型、发问题、看结果，最快确认。
如果你长期在远程主机上做编码、跑 Agent、批量改代码，Coding Plan 更合适：https://taotoken.net/coding-plan 。它针对高频编码场景做了额度优化，比零散调用省心。
最后回到 Remote-SSH 本身，给你一个实用习惯：每次 Cursor 升级后，重新检查一遍 Remote-SSH 扩展版本，因为 Cursor 大版本更新有时会重置扩展配置。把extensions.autoUpdate关掉这个动作，建议写进你的初始化清单，能省掉很多重复排障。连接恢复后，先在远程终端跑一条echo $SHELL确认环境正常，再开始干活。
