Cursor 接入常见问题

接入或使用过程中遇到报错，可先对照以下情况排查。 - 1787047604 /home/file/help/b66d3ee2-71f6-4b1b-8b72-762a51521f70.png

支持哪些操作系统？

目前支持 **Windows** 与 **macOS**。Linux 暂未适配。

安装插件前需要先登录 Cursor？

需要。请前往 Cursor 官网注册免费账户并登录后，再安装 CodePass 插件。

侧栏找不到 CodePass 插件？

确认 `.vsix` 已安装成功，并完全退出 Cursor 后重新打开（不是只关窗口）。仍不可见时，在扩展面板检查 CodePass 是否已启用。

Windows 上插件无法安装 / 补丁注入失败？

常见原因是账户权限不足，报错多为「补丁注入失败」「权限不足」。 请使用具有管理员权限的账户安装 Cursor，或以管理员身份启动 Cursor，再重新安装插件并启用 Cursor 补丁。

登录提示 Token 无效 / 401？

回到 CodePass 用户中心重新复制用户名与 128 位 Token，在插件中重新登录。不要手打 Token，也不要混用其他平台的 Key。

安装后无法使用 Agent、连接不上？

优先排查以下两项： 1. **补丁未生效**：打开插件主面板，确认 **Cursor 补丁** 为「已启用」；未启用则点击「开始使用」，完成后完全退出并重新打开 Cursor。 2. **诊断异常**：仍异常时，在「故障检测」点击开始检测，按结果处理： - **Worker API / H2 代理 / H1 中转异常**：先确认本机网络可用；若开启了 VPN，请更换节点或暂时关闭后再重新检测。 - **Cursor 设置 `disableHttp2 = true`**：当前走 HTTP/1.1 SSE 降级协议，可能影响使用。请前往 Cursor Settings → Browser & Network → Network → Http Compatibility Mode，改回 HTTP/2。 - **Cursor 设置 `http.proxy` 已配置**：本地代理可能干扰 CodePass。请前往 Cursor Settings → VS Code Settings，搜索 `proxy`，将 `Http: Proxy` 置空后保存，重载窗口再重新检测。 - **Cursor 补丁状态异常**：先完全退出并重新打开 Cursor 后再检测；若仍异常，在补丁栏点击「结束使用」并重载，再点击「开始使用」重新启用。

Cursor 更新后连不上 / Authentication Error / 模型加载失败？

常见报错：`Authentication Error`、`connection failed`、`HTTP 502`，或模型列表加载不出来。 Cursor 大版本或自动更新会覆盖 `workbench.js`，导致 Cursor 补丁失效，属正常现象。请按顺序排查： 1. **重新启用补丁**：打开 CodePass 插件，在补丁栏点击「开始使用」或「修复补丁」，完成后完全退出并重新打开 Cursor。 2. **核对 Token**：回到用户中心重新复制用户名与 128 位 Token，在插件中重新登录（勿手打）。 3. **重装插件**：仍不行时，卸载旧插件并安装最新 `.vsix`，重新填入 Token 并启用 Cursor 补丁，再完全退出后重新打开。 4. **换过网络方式仍连不上**：直连 / 系统代理都试过仍失败时，问题多半在本地补丁或鉴权，而非代理本身；回到第 1–3 步确认。 5. **清理全局状态缓存（兜底）**：以上仍无效时，先完全退出 Cursor，再按系统执行下列命令；完成后重新打开 Cursor，并回到插件内重新验证。 `$env:APPDATA` 是 Windows PowerShell 的用户应用数据目录环境变量，通常指向 `C:\Users\你的用户名\AppData\Roaming`。

如何结束使用 CodePass / 还原 Cursor？

若只需暂时停用：在插件主面板点击「结束使用」，按提示重载窗口即可还原 Cursor。 若要彻底卸载：请先点击「结束使用」完成还原，再卸载 CodePass 扩展。卸载后 Cursor 具备自愈机制；若界面仍异常，完全退出后重新打开即可。

如何确认正在使用 CodePass？

查看插件主面板：**Cursor 补丁** 为「已启用」。也可在「故障检测」中确认补丁状态为通过。用量明细可在 CodePass 用户中心按 Cursor 平台查看。