---
title: 故障排查
description: 处理本地 CA、管理服务、模型连接和 Cursor 模型列表问题。
icon: Wrench
---

## 需要先初始化本地 CA

进入 **Cursor 配置**，点击 **初始化 CA**。本地 CA 只保存在本机，用于解析 Cursor 发出的 HTTPS 请求。

## 需要在系统中信任本地 CA

点击 **打开终端安装 CA**，按照终端提示完成系统授权。完成后返回应用，点击 **我已初始化，刷新**。

如果状态没有更新，请完全退出后重新启动 Cursor Byok，再次打开 Cursor 配置页面。

## 无法连接本地管理服务

1. 完全退出并重新启动 Cursor Byok。
2. 检查是否有安全软件拦截本地回环连接。
3. 如果修改过管理服务端口，将端口恢复为 `0`，让应用在启动时自动选择可用端口。
4. 再次启动应用并刷新页面。

## 模型连通性测试失败

按测试错误逐项检查：

- **认证错误**：确认 API Key 有效，且账户有权访问目标模型。
- **未找到接口**：确认模型类型、请求协议与服务器地址匹配。
- **模型不存在**：使用 **获取模型** 检查上游返回的模型标识。
- **参数错误**：暂时关闭自定义 Headers 和额外参数，再重新测试。
- **连接超时**：检查网络、系统代理和上游服务状态。

## Cursor 中看不到模型或模型不生效

先确认以下条件全部满足：

1. 本地 CA 状态正常。
2. 已保存至少一个模型配置。
3. 模型连通性测试成功。
4. Cursor Byok 正在运行。

仍然不生效时，按顺序执行一遍完整的重启流程：

1. 从托盘完全退出 Cursor Byok，重新启动。
2. 完全退出并重新启动 Cursor。
3. 新开一个对话，刷新模型列表。
4. 选择你自己配置的模型，**不要选 Auto**。

## 选 Auto 时报额度或账户错误

Auto 只会路由到 Cursor 官方模型，不会使用你配置的本地模型。账号没有官方额度时选 Auto 就会报错——请在模型列表中手动选择你配置的模型。

如果账号本身有额度，官方模型和本地模型可以随意混用，没有使用上的边界。

## 还在使用旧版的 fake 账户

新版的设计是与官方账号并存，不再需要 fake 账户，也没有“关服务”之类的操作：

1. 在 Cursor 中退出旧版生成的 fake 账户。
2. 登录你自己的 Cursor 账号。

登录自己的账号后，插件、代码库索引等 Cursor 功能都可以正常使用。

## 请求失败但测试成功

模型测试只验证基础连接。Agent 请求还会包含更长上下文、工具定义和流式响应。请检查：

- 上游模型是否支持工具调用。
- 上下文窗口和最大输出 Token 是否符合模型限制。
- 自定义参数是否与实际协议兼容。
- 调用详情中的上游状态码和响应内容。

## 继续反馈

如果问题仍然存在，请在 [GitHub Issues](https://github.com/leookun/cursor-byok/issues) 提交问题，并附上：

- 操作系统与 Cursor Byok 版本。
- 选择的模型类型和请求协议。
- 已脱敏的服务地址与错误信息。
- 复现步骤。

请勿公开 API Key 或其他凭据。