CCursor 故障排查清单:401 报错、无法登录、端口占用等 10 大常见问题秒解
CCursor 故障排查清单:401 报错、无法登录、端口占用等 10 大常见问题秒解
CCursor(Cursor++)是一款让 Cursor IDE 支持 BYOK(Bring Your Own Key)的开源工具:它在你本机运行一个本地 BYOK 服务器,把 Cursor 的 Agent / Chat / Composer 请求转发到你自己的 API Key(Anthropic、OpenAI、Gemini 等)。当出现 401 报错、无法登录、端口占用 等问题时,按这份故障排查清单逐项自查,通常几分钟就能定位原因。
排查前先做这一步:检查安装状态 🩺
绝大多数问题都可以先用 status 命令快速定位。它会逐项检查扩展、补丁注入、备份文件等状态:
npx @cometix/ccursor status
如果输出中出现红色的 ✗,把出问题的项和下文 10 个场景对照即可。相关的状态检查逻辑见 status.js,安装流程见 install.js。
1. 安装后无法登录 Cursor 账号
现象:执行 npx @cometix/ccursor install 后,Cursor 登录页一直报错或无法完成登录。
原因:BYOK 模式开启时,Cursor 的网络请求会被本地服务器拦截转发,官方登录流程会受影响。
秒解:
- 打开 Cursor 侧边栏的 Cursor++ 面板,把 BYOK 开关切到 OFF;
- 正常完成登录;
- 登录成功后再切回 ON。
💡 如果你需要用官方功能(登录、同步等),保持 BYOK OFF 即可,两种模式随时一键切换。
2. LLM 请求返回 401 / 403 / 404 报错
现象:对话时出现 401、403、404 等 HTTP 错误横幅。
原因:本地 BYOK 服务器把请求发给了上游 API,而上游拒绝了请求,通常是密钥或地址配置错误。
秒解:检查 ~/.ccursor/providers.json 中当前服务商的两项配置:
- API Key:
auth.value是否完整、是否过期、是否多复制了空格; - Base URL:
baseUrl是否与服务商要求一致(比如第三方中转地址和官方地址不同)。
修改后配置热重载即可生效,无需重启 Cursor。官方文档的对应排查项见 README.md。
3. 端口被占用,本地服务器启动失败
现象:侧边栏提示连接失败,或日志中出现 EADDRINUSE、端口冲突等字样。
原因:CCursor 的本地 BYOK 服务器默认监听 127.0.0.1:39831,若该端口已被其他程序占用,服务器就无法启动。默认端口定义见 config.ts。
秒解:在 Cursor 设置中修改扩展的端口配置项(配置键为 cursor2plus.server.port),换一个未被占用的端口保存即可。同理,采集端口 cursor2plus.collector.port(默认 14800)冲突时也可一并调整。
4. 升级 Cursor 版本后补丁失效
现象:Cursor 自动更新后,Agent 回复变慢、回到官方通道,或补丁报错。
原因:Cursor 更新会覆盖被补丁修改过的文件(如 workbench.desktop.main.js、extensionHostProcess.js),原有注入失效。
秒解:
npx @cometix/ccursor status # 确认哪些补丁缺失
npx @cometix/ccursor install # 重新打补丁(幂等,已完成的步骤会跳过)
重启 Cursor 后恢复正常。
5. 安装时报错 "Cursor installation not found"
现象:执行 install 时提示找不到 Cursor 安装目录。
原因:安装器按常见路径自动探测 Cursor(macOS / Linux / Windows 均内置探测列表),如果你的 Cursor 装在非标准位置就会失败。探测逻辑见 detect.js。
秒解:设置环境变量 CCURSOR_CURSOR_ROOT,直接指向 Cursor 的 resources/app 目录(该方式优先级最高,绕过自动探测):
# macOS 示例
export CCURSOR_CURSOR_ROOT=/Applications/Cursor.app/Contents/Resources/app
npx @cometix/ccursor install
6. 提示 "Model not found"(模型未找到)
现象:模型选择器里没有想要的模型,或发送请求时报模型不存在。
秒解:
- 在 Cursor++ 侧边栏面板中添加模型(支持搜索模型目录);
- 或手动编辑
~/.ccursor/providers.json,在对应 provider 的models数组里补一条模型定义(id、apiModel、contextTokenLimit、maxOutputTokens等字段)。
配置保存后热重载生效。
7. 配置改了却不生效
现象:改了 providers.json 或 routes.json,行为没变化。
排查顺序:
- 确认 BYOK 开关是 ON——开关状态存在
~/.ccursor/routes.json中,OFF 状态下所有改动都不会走本地转发; - 检查 JSON 语法——文件里有多余逗号、注释等语法错误时,配置会被整体忽略;
- 看日志——每个 Cursor 窗口有独立日志流(LogOutputChannel 彩色输出),能直接看到配置加载是否成功;
- 最后手段:彻底重启 Cursor(正常情况热重载即可,但个别场景重启最稳妥)。
8. 安装提示 "Found backup files from a previous installation"
现象:重装时安装器中止,提示发现上次安装遗留的备份文件。
原因:上次安装/卸载没有完整执行,磁盘上残留了 .bak 备份,安装器为避免覆盖你的修改而主动中止(见 install.js 的预检逻辑)。
秒解:先执行完整卸载清理,再重新安装:
npx @cometix/ccursor uninstall
npx @cometix/ccursor install
9. Agent / Chat 请求没有走本地,仍连官方服务
现象:明明装了 CCursor,但 API 账单(或代理日志)里没有请求。
秒解,按顺序确认:
- 侧边栏 BYOK 开关是否为 ON;
- 运行
status检查Renderer hook injected、Agent Host HTTP/1.1 router等项目是否全部为✓; - 补丁缺失时重新执行
install并重启 Cursor; - 升级 Cursor 后建议直接跑
npx @cometix/ccursor update(自动先卸载再重装,等价于一次干净升级)。
10. 想彻底卸载还原,但担心改坏了 Cursor
现象:卸载后担心残留补丁影响 Cursor 正常使用。
说明:CCursor 的每个补丁在打补丁前都会自动创建备份文件,卸载时逐项还原,是完全可逆的(包括 Cursor 3.9+ 的 singleton 路由补丁、签名绕过、KaTeX 样式修补等)。
秒解:
npx @cometix/ccursor uninstall
npx @cometix/ccursor status # 确认 "Backups" 还原情况
如果个别文件还原异常,备份文件仍在 Cursor 安装目录内(原文件名 + 备份后缀),手动换回即可。
附:常用命令速查表 🧰
| 场景 | 命令 |
|---|---|
| 首次安装 | npx @cometix/ccursor install |
| 升级重装 | npx @cometix/ccursor update |
| 检查状态 | npx @cometix/ccursor status |
| 补丁匹配预检(dry-run) | npx @cometix/ccursor check |
| 卸载还原 | npx @cometix/ccursor uninstall |
⚠️ 环境要求:Cursor IDE + Node.js ≥ 18;配置文件统一存放在
~/.ccursor/(providers.json、routes.json、cursor.db)。
更多细节可参考项目说明 README_CN.md 与 installer/README.md,CLI 命令的完整定义见 cli.js。按上面 10 个场景从上到下排查,基本能覆盖 CCursor 日常使用中的所有常见故障。