cursor-byok/README-CN.md

cursor-byok

cursor-byok 是一个运行在本机的 Cursor 模型网关，帮助你在 Cursor 中使用自己配置的模型服务。

English README · 使用指南 · 下载 · 提交问题

项目简介

cursor-byok 是一个开源的本地模型网关。它在你的设备上运行服务，接收 Cursor 发出的 Agent 请求，将请求转发到你配置的模型服务，并尽可能保留 Cursor Agent 的工具调用、Skills、MCP 和多轮对话能力。

你可以连接兼容 OpenAI 或 Anthropic 协议的服务，自定义服务地址、模型 ID、API Key 和请求参数，也可以使用 Cursor 平台默认选项之外的模型通道。

Important

cursor-byok 免费且开源，但你连接的模型服务商可能会按用量收费。本项目是独立项目，与 Cursor 或其开发者没有关联，也未获得其认可。

主要功能

• 自定义模型通道：配置自己的 API 地址、凭据和模型 ID。
• 多种 API 协议：支持 OpenAI Responses API、OpenAI Chat Completions API 和 Anthropic Messages API 兼容服务。
• 模型管理：添加、复制、编辑、排序模型配置，并批量测试连接。
• 连接性能测试：查看首字延迟、生成速度、总耗时和原始服务商响应。
• Agent 工作流：继续使用工具调用、Skills、MCP 和多轮对话。
• 会话指标：查看 Token 用量、缓存命中率、对话轮次和估算价值。
• TAB 补全服务：在公益服务、官方直连和自定义服务之间选择连接方式。
• 跨平台运行：支持 macOS、Windows 和 Linux。

快速开始

1. 从 GitHub Releases 下载适合你操作系统的最新版本。
2. 启动 cursor-byok，打开 Cursor 配置，按提示初始化本地 CA（证书颁发机构）。
3. 在模型设置中添加模型，填写服务地址、API Key 和模型名称，然后保存并运行 测试。
4. 确认测试通过后，保持 cursor-byok 运行。
5. 首次升级 Cursor 或首次配置模型后，完全退出并重新启动 Cursor，然后新开一个对话。在模型列表中选择已配置的模型，开始使用 Agent。

完整的安装步骤、配置说明和常见问题，请参阅中文使用指南。

Tip

首次升级 Cursor 或首次完成配置后，必须完全退出并重新启动 Cursor，再新开一个对话。配置前已经打开的对话不会加载新连接；使用自定义模型时，请在模型列表中手动选择该模型，不要选择 Auto。

模型配置

每个模型配置都是独立的上游通道，可以单独设置服务商、协议、凭据和生成参数。

类型与协议选择

模型系列	模型类型	请求协议
Claude 系列	Anthropic	Messages API
GPT / OpenAI 系列	OpenAI	Responses API
其他模型	OpenAI	Chat Completions API

GPT 系列建议使用 Responses API。如果使用 Chat Completions，可能无法保留提示词缓存，导致速度变慢和费用增加。

常用字段

• 模型类型：选择 OpenAI 或 Anthropic，决定上游接口格式。
• 请求协议：OpenAI 类型需要继续选择 Responses API 或 Chat Completions API。
• 服务器地址：可以填写服务商基础地址，让应用按协议追加标准端点，也可以填写完整请求 URL 并原样使用。
• API Key：填写上游服务要求的访问密钥。密钥保存在本机，用于发送模型请求。
• 模型名称：填写服务商接口接受的模型标识，也可以使用 获取模型 读取服务商返回的模型列表。
• 显示名称：Cursor 模型列表中显示的名称，不会改变发送给上游的模型标识。
• 备注：显示在 Cursor 的模型说明中。

还可以根据模型能力设置上下文窗口 Token、最大输出 Token、推理或思考强度、自定义 Headers，以及 OpenAI 或 Anthropic 的额外参数。自定义 Headers 和额外参数必须是 JSON 对象，只应填写服务商明确支持的字段。

保存配置后运行 测试，确认地址、协议、API Key、模型标识和流式响应都正常，再在 Cursor 中使用该模型。

TAB 补全服务

Cursor 的 Tab 补全由独立的 TAB 服务处理，不经过模型通道。你可以在 系统设置 → TAB 设置 中选择以下模式：

• 使用公益服务（默认）：使用项目作者部署的公共服务，无需额外配置。
• 直连：直接连接当前 Cursor 账号对应的官方 TAB 服务，适合账号拥有官方额度的情况。
• 自定义：自行部署 cursor-tab-server，然后填写 TAB 服务地址。

修改 TAB 设置后，建议重启 Cursor 并新开一个对话，确保新的连接方式生效。

与官方账号并存

新版设计支持 cursor-byok 与 Cursor 官方服务并存：

• 直接在 Cursor 中登录自己的账号。如果之前使用旧版生成的 fake 账户，请先退出该账户，再登录自己的账号。
• 账号拥有官方额度时，官方模型和本地模型可以随时切换混用。
• Auto 只使用官方模型，不会自动使用你配置的本地模型。账号没有官方额度时，请手动选择自己配置的模型。
• 插件、代码库索引等 Cursor 功能可以继续使用。

数据流转

Cursor 客户端
    │
    │ Agent 请求与工具结果
    ▼
cursor-byok 本地服务
    │
    │ OpenAI / Anthropic 兼容请求
    ▼
你配置的模型 API

API Key、模型配置和应用设置保存在本机。模型请求仍会发送到你选择的上游服务商，请根据对应服务商的隐私政策和计费规则使用。

项目结构

cursor-byok/
├── apps/
│   ├── desktop/       # React、Vite、Tauri 桌面应用
│   └── docs/          # Next.js 与 Fumadocs 中文/英文文档站
├── server/            # 本地服务、Cursor 请求处理和模型转发
├── crates/
│   └── semble-core/   # 本地代码索引与搜索核心库
├── cursor-proto/      # Cursor 协议定义
├── benchmarks/        # 代码搜索和索引基准测试
├── images/            # README 展示图片
├── Cargo.toml         # Rust 工作区配置
└── Makefile           # 常用开发、检查和构建命令

本地开发

环境要求

• Rust 工具链和 Cargo
• Node.js 与 npm
• Tauri 2 的系统构建依赖
• Docker（仅在构建 Docker 镜像时需要）

安装依赖

npm --prefix apps/desktop install
npm --prefix apps/docs install

启动开发环境

启动桌面前端：

make dev-web

启动桌面应用：

make dev-desktop

启动文档站：

make dev-docs

文档站默认地址为 http://localhost:3000。

检查与构建

运行完整检查：

make check

分别构建各部分：

make build-web       # 构建桌面前端
make build-server    # 构建 Rust 本地服务
make build-docs      # 构建文档站
make build-desktop   # 构建 Tauri 桌面安装包
make build-docker    # 构建 Docker 镜像

文档内容位于 apps/docs/content/docs 和 apps/docs/content/blog。修改文档侧边栏时同步更新 apps/docs/content/docs/meta.json。

路线图

项目将继续改进模型兼容性、Agent 工具、本地运行稳定性和自托管体验，并探索支持更多 IDE、聊天和 Agent 工作流。

计划与进展请参阅发布路线图。

社区与反馈

• 中文使用指南
• GitHub Issues
• Telegram 社区
• QQ 群：1095916242、1094411438、1095918002、1094419321

提交问题时，请附上操作系统、cursor-byok 版本、模型类型、请求协议、已脱敏的服务地址、错误信息和复现步骤。请勿公开 API Key 或其他凭据。

参与贡献

欢迎提交 Issue 和 Pull Request。提交代码前请先阅读项目中的开发说明，并运行 make check 确认格式、测试和前端构建检查通过。

许可证

本项目采用 MIT License 开源。