1. 项目概述为什么我们需要一个本地AI的“传声筒”如果你和我一样是个重度依赖 Cursor 编辑器同时又对本地大模型比如 Ollama情有独钟的开发者那你一定遇到过这个让人挠头的困境Cursor 的 AI 补全功能理论上可以配置成本地端点但实际操作时请求总是石沉大海。这背后的原因其实是一个典型的网络架构问题。Cursor 编辑器本身运行在你的电脑上但它内部的 AI 请求逻辑是先发往 Cursor 的官方云端服务器再由云端服务器转发到你配置的端点比如http://localhost:11434。问题就出在这里——Cursor 的云端服务器怎么可能访问到你个人电脑上localhost这个地址呢这就像你让一个远在千里之外的朋友去你卧室书桌上拿本书一样他根本找不到门。curxy这个项目就是为了解决这个“最后一公里”的通信问题而生的。它的名字很直白就是Cursor和Proxy的组合。本质上它是一个用 Deno 和 Hono 框架编写的轻量级代理服务器。它的核心工作就是在公网上建立一个“中转站”。你本地的 Cursor 编辑器将请求发给这个位于公网的“中转站”然后“中转站”再将请求无缝转发到你本地运行的 Ollama 服务器最后把 Ollama 的响应原路返回给 Cursor。这样一来就巧妙地绕过了“云端服务器无法访问 localhost”的限制。简单来说curxy就是为你本地的 Ollama 模型在公网上开了一个专属的“热线电话”让 Cursor 的云端服务能够通过这个号码顺利联系上你家里的“AI大脑”。这对于注重隐私、希望完全在本地处理代码生成与对话、或者单纯想免费使用开源模型的开发者来说是一个极其优雅的解决方案。2. 核心原理与架构拆解2.1 网络请求的“三角恋”与代理的“媒人”角色要理解curxy的价值我们得先看清没有它时的“三角恋”困局。标准的 Cursor Ollama 配置期望的路径是Cursor客户端 - Ollama本地服务。但现实是Cursor 为了统一管理和提供部分增值服务插入了一个“第三者”Cursor客户端 - Cursor云端服务器 - Ollama本地服务。这个“第三者”Cursor云端成了沟通的阻塞点。curxy的聪明之处在于它没有尝试去改变 Cursor 或 Ollama 的任何一方而是自己扮演了一个“媒人”或者说“接线员”的角色。它部署在一个双方都能访问的位置通过 Cloudflare Tunnel 暴露到公网从而重构了通信链路Cursor客户端 - Cursor云端服务器 - Curxy公网代理 - Ollama本地服务。在这个链条里Curxy 对 Cursor 云端来说就是一个标准的 OpenAI API 兼容端点对后端的 Ollama 来说它又是一个普通的 HTTP 客户端。它负责协议转换、请求转发和响应回传。2.2 技术栈选择为什么是 Deno Hono作者选择了 Deno 和 Hono 来构建这个代理这是一个非常贴合项目需求的、现代且高效的技术组合。Deno 的优势内置安全性与简化部署Deno 默认安全需要显式授权才能访问网络或文件系统虽然curxy用了-A全权标志但在生产观念上这是个好基础。更重要的是Deno 的jsr:包管理器使得分发和运行这个工具变得极其简单一行deno run命令即可无需处理复杂的npm install或依赖冲突。单文件可执行性虽然项目有源码但通过 JSR 发布后用户感觉上就是在运行一个“脚本”降低了使用门槛符合这类工具类项目“开箱即用”的定位。现代 TypeScript 原生支持保证了代码的健壮性和开发体验。Hono 框架的优势轻量级与高性能Hono 是一个为边缘计算设计的超轻量级 Web 框架其路由和中间件系统非常高效。对于curxy这样一个功能聚焦主要是请求转发的代理服务器来说Hono 足够小巧没有不必要的开销。优异的兼容性Hono 能轻松创建符合 OpenAI API 格式的端点方便将 Ollama 的响应“包装”成 Cursor 云端期望的格式。云原生友好Hono 本身在 Cloudflare Workers 等环境运行良好这与curxy利用 Cloudflare Tunnel 暴露服务的思路一脉相承。这个技术栈的选择体现了作者对“工具”的深刻理解用最合适的、最简洁的技术快速可靠地解决一个明确的问题同时为使用者提供近乎零配置的体验。2.3 安全考量的双刃剑OPENAI_API_KEY 的作用项目文档中提到可以通过设置OPENAI_API_KEY环境变量来限制对代理服务器的访问。这是一个重要的安全特性但我们需要正确理解其工作原理。它不是用来调用 OpenAI 官方 API 的。实际上这个“API Key”在curxy这里被用作一个简单的共享密钥认证。当你在服务端设置了OPENAI_API_KEYyour_secret_token后curxy会在其接收到的请求头中检查Authorization: Bearer your_secret_token字段。只有携带了正确 Token 的请求才会被转发给 Ollama。这意味着什么好处防止任何人拿到你的 Curxy 公网 URL 后都能免费使用你的 Ollama 算力和模型。这在共享服务器或对安全有要求的环境下是必要的。需要注意的地方在 Cursor 编辑器里配置时你需要在 “OpenAI API Key” 字段填写的同样是这个你自己定义的your_secret_token而不是一个真正的 OpenAI Key。这可能会造成一些混淆因为字段名是“OpenAI API Key”但实际功能是“Curxy 代理访问密钥”。注意这个密钥以明文形式在 Cursor 配置界面填写并通过网络传输。虽然通信过程可能经过 HTTPS 加密但请务必意识到它不是一个高强度的身份验证机制更适合用于防止非授权的偶然访问而非对抗恶意攻击。对于更高安全需求应考虑在 Curxy 前部署更完善的反向代理和认证层。3. 从零开始的详细配置与实操指南3.1 环境准备确保基石稳固在启动curxy之前我们需要确保两个核心依赖已经就绪。1. 安装并运行 OllamaOllama 是本项目的 AI 引擎必须首先安装并运行。访问官网前往 Ollama 官网根据你的操作系统Windows/macOS/Linux下载并安装。拉取模型安装完成后打开终端拉取你需要的模型。例如拉取目前社区非常流行的qwen2.5-coder模型ollama pull qwen2.5-coder:7b验证服务运行ollama serve或在安装后直接启动 Ollama 应用。默认情况下Ollama 的 API 服务会运行在http://127.0.0.1:11434。你可以在浏览器中访问http://127.0.0.1:11434/api/tags来验证如果返回了已安装的模型列表 JSON说明服务正常。2. 安装 DenoDeno 是运行curxy的 JavaScript/TypeScript 运行时。推荐安装方法使用官方的一键安装脚本这是最通用和简单的方式。# MacOS 或 Linux curl -fsSL https://deno.land/install.sh | sh # Windows (PowerShell) irm https://deno.land/install.ps1 | iex验证安装安装完成后重启你的终端运行deno --version。如果能看到版本号信息说明安装成功。Deno 的可执行文件通常会自动添加到系统路径中。3.2 启动 Curxy 代理服务器环境就绪后启动curxy本身非常简单。打开一个新的终端窗口确保 Ollama 的服务在另一个窗口或后台运行。基础启动命令deno run -A jsr:ryoppippi/curxydeno run Deno 执行命令。-A 这是一个宽松的权限标志等同于--allow-all授予脚本所有权限网络、环境变量等。对于这种需要创建 HTTP 服务器和隧道的工具这是最方便的方式。jsr:ryoppippi/curxy 直接从 JSR (JavaScript Registry) 包仓库拉取并运行curxy的最新版本。执行命令后终端会输出类似以下信息Listening on http://127.0.0.1:62192/ ◐ Starting cloudflared tunnel to http://127.0.0.1:62192 Server running at: https://remaining-chen-composition-dressed.trycloudflare.com这里有两个关键地址http://127.0.0.1:62192这是curxy在你本地机器上启动的代理服务器地址。这个地址只对你本机可见。https://...trycloudflare.com这是通过 Cloudflare Tunnel 服务为你本地服务器生成的一个临时的、公开可访问的 HTTPS 网址。这个网址就是我们要填入 Cursor 的“通行证”。带访问控制的启动命令如果你担心公网 URL 被他人滥用可以设置访问密钥OPENAI_API_KEYmy_super_secret_token_123 deno run -A jsr:ryoppippi/curxy请将my_super_secret_token_123替换为你自己设定的任意复杂字符串。记住这个字符串稍后需要在 Cursor 中配置。3.3 配置 Cursor 编辑器这是最关键的一步我们需要告诉 Cursor 使用我们刚刚搭建的代理通道。打开 Cursor 设置在 Cursor 编辑器中通过菜单栏或快捷键 (Cmd ,或Ctrl ,) 打开设置。进入 AI 设置在设置侧边栏找到“AI”选项并点击。配置自定义模型Override OpenAI Base URL 将curxy启动后给出的那个https://...trycloudflare.com网址在后面加上/v1然后完整地粘贴到这个输入框中。例如https://remaining-chen-composition-dressed.trycloudflare.com/v1。这个/v1路径是 OpenAI 兼容 API 的标准入口curxy会在此监听请求。OpenAI API Key如果你启动curxy时没有设置OPENAI_API_KEY那么 Cursor 中的这个字段可以留空。如果你启动时设置了OPENAI_API_KEY如my_super_secret_token_123那么你必须在这里填写完全相同的字符串。Model Names 在这里添加你想要在 Cursor 中使用的 Ollama 模型名称。这里的名称必须与你在 Ollama 中拉取和运行的模型名称完全一致。例如如果你拉取了qwen2.5-coder:7b这里就添加qwen2.5-coder:7b。你可以添加多个模型用逗号分隔如qwen2.5-coder:7b, llama3.2:3b。添加后这些模型会出现在 Cursor 的模型选择下拉列表中。保存并测试保存设置。现在你可以尝试在 Cursor 中触发 AI 补全例如写一段注释后按CmdK或者在 Chat 界面选择你刚配置的模型并提问。如果一切正常Cursor 的状态栏会显示正在使用你配置的模型并很快给出响应。3.4 配置过程图解与要点回顾为了更直观我们可以将整个数据流总结如下------------------- 请求 (含API Key) --------------------------- 转发请求 ------------------- | | -------------------- | | ------------- | | | Cursor 编辑器 | | Cursor 云端服务器 | | Curxy 代理 | | (你的电脑) | -------------------- | (cursor.com) | ------------- | (公网URL) | | | 返回AI结果 | | 返回结果 | | ------------------- --------------------------- ------------------- | | 本地HTTP请求 v ------------------- | | | Ollama 服务 | | (localhost:11434)| | | -------------------实操要点回顾顺序很重要先启动 Ollama再启动curxy最后配置 Cursor。URL 格式Cursor 中填写的 URL 必须是https://...trycloudflare.com/v1别忘了/v1。模型名严格一致Cursor 中 “Model Names” 填写的名字必须是你用ollama pull下载的模型全名。密钥匹配如果设置了OPENAI_API_KEYCursor 中的 API Key 必须与之完全相同。隧道是临时的Cloudflare Tunnel 提供的免费.trycloudflare.com域名是临时的每次重启curxy都会变化。这意味着你每次重启服务后都需要去 Cursor 设置里更新 URL。对于长期使用可以考虑更稳定的隧道方案如配置自定义域名。4. 高级用法、问题排查与优化建议4.1 提升稳定性和便利性超越临时隧道每次重启都改配置显然太麻烦也不利于团队共享配置。我们可以通过几种方式优化方案一使用固定子域名Cloudflare Tunnel 高级功能如果你拥有一个自己的域名并且将其 DNS 托管在 Cloudflare可以使用cloudflared隧道创建具有固定子域名的隧道。这需要你安装并配置cloudflared客户端并创建隧道配置文件。虽然步骤稍多但能获得一个像curxy.yourdomain.com这样的固定地址一劳永逸。方案二在内网服务器部署团队使用如果你和同事都在同一个内网可以将curxy和 Ollama 部署在一台内网服务器上然后通过内网穿透或路由器端口映射提供一个稳定的内网 IP 或域名。这样整个团队都可以在 Cursor 中配置同一个地址共享强大的本地模型。方案三使用反向代理如 Nginx/Caddy在运行curxy的服务器前部署一个反向代理如 Nginx可以带来诸多好处固定端口和域名将curxy运行在固定端口如 3000用 Nginx 代理到https://ai.yourdomain.com/v1。增强安全在 Nginx 层配置更严格的 HTTPS、访问日志、速率限制甚至更复杂的认证。负载均衡如果你有多台运行 Ollama 的机器Nginx 可以做负载均衡。4.2 常见问题与排查清单即使按照步骤操作也可能会遇到问题。下面是一个快速排查指南问题现象可能原因排查步骤Cursor 提示 “Failed to fetch” 或 “API Error”1. Curxy 服务未运行2. Cursor 中配置的 URL 错误3. 网络问题导致 Cloudflare 隧道不通1. 检查运行curxy的终端是否在运行有无报错。2. 核对 Cursor 中 URL 是否为curxy输出的完整https://.../v1格式。3. 尝试在浏览器中直接访问该 URL看是否能打开可能会返回 JSON 错误这正常说明服务可达。Cursor 提示 “Invalid API Key”1. 服务端设置了OPENAI_API_KEY但客户端未填或填错2. 客户端填了 Key 但服务端未设置1. 确认启动curxy的命令中是否包含OPENAI_API_KEYxxx。2. 确认 Cursor 中 “OpenAI API Key” 字段填写的值与启动命令中的xxx完全一致注意空格和大小写。Cursor 中看不到配置的模型1. “Model Names” 填写错误2. Ollama 中未拉取对应模型3. Curxy 无法连接到 Ollama1. 在终端运行ollama list确认模型名称并确保 Cursor 中填写的是完全相同的名字。2. 检查运行curxy的终端有无连接 Ollama 失败的错误日志。确保 Ollama 服务 (ollama serve) 正在运行。AI 响应速度极慢或超时1. 模型首次加载需要时间2. Cloudflare 隧道网络延迟3. 本地机器资源CPU/内存不足1. 首次使用某个模型时Ollama 需要加载模型到内存等待1-2分钟是正常的。2. 后续请求仍然很慢可能是隧道节点问题。尝试重启curxy获取新的隧道地址。3. 检查任务管理器确认内存是否充足。大模型需要大量内存。连接频繁断开Cloudflare 免费隧道的不稳定性这是免费.trycloudflare.com域名的已知问题。对于生产级使用强烈建议采用“固定子域名”或“内网部署”方案。一个实用的调试技巧在启动curxy时可以添加-L info或-L debug标志来获取更详细的日志帮助定位问题。deno run -A jsr:ryoppippi/curxy -L debug4.3 性能调优与模型选择建议curxy本身非常轻量性能瓶颈主要在于 Ollama 模型推理和网络延迟。模型选择对于代码补全这种需要低延迟的任务建议选择参数量适中、针对代码优化的模型。例如qwen2.5-coder:7b、deepseek-coder:6.7b、codellama:7b都是不错的选择。更大的模型如 34B, 70B虽然能力更强但加载和推理速度慢可能影响编码体验。Ollama 参数调整运行 Ollama 时可以通过环境变量或启动参数限制其使用的 CPU 线程数和 GPU 层数以平衡性能与系统资源。例如OLLAMA_NUM_PARALLEL2可以限制并行请求数。保持 Curxy 和 Ollama 在同一主机这是最理想的部署方式可以消除代理与 AI 引擎之间的网络延迟。避免将curxy放在一台机器而 Ollama 放在另一台机器除非它们之间的内网连接速度极快。5. 深入探索理解 Curxy 的工作机制与扩展可能5.1 拆解 Curxy 的请求转发逻辑虽然我们只是使用者但了解curxy内部如何处理请求能帮助我们在遇到复杂问题时更好地分析和解决。简单来说curxy主要做了以下几件事创建 HTTP 服务器使用 Hono 框架在本地一个随机端口如 62192启动一个 Web 服务器。监听/v1端点它会在/v1/chat/completions等路径上监听 POST 请求这些路径是 OpenAI API 的标准格式Cursor 云端服务器正是向这些端点发送请求。请求头处理与认证检查传入请求的Authorization头如果服务端设置了OPENAI_API_KEY则会验证其是否匹配。同时它可能会对请求头进行一些清洗或修改以适配 Ollama 的 API。请求体转换与转发将收到的 JSON 请求体遵循 OpenAI 格式进行必要的字段映射转换成 Ollama API 能够理解的格式。例如将model参数映射为 Ollama 的模型名将messages数组进行格式转换。调用 Ollama API向http://localhost:11434/api/chat或/api/generate发送转换后的 HTTP 请求。响应流处理Ollama 的响应通常是流式的streaming。curxy需要正确地将这个流接收下来并按照 OpenAI 的流式响应格式Server-Sent Events重新包装再传回给最初的请求方Cursor 云端服务器。启动隧道通过调用cloudflared将本地的http://127.0.0.1:62192服务暴露到一个公网可访问的 HTTPS 地址。这个过程确保了协议之间的兼容性让原本只懂 OpenAI API 的 Cursor 云端能够与提供类似但不同 API 的 Ollama 进行对话。5.2 潜在的扩展与自定义方向curxy项目本身简洁专注但它的架构为我们打开了一些自定义的可能性。如果你懂一些 TypeScript/JavaScript可以克隆其源码进行修改。支持其他本地 AI 后端理论上你可以修改curxy的转发逻辑让它不仅支持 Ollama还能支持其他提供 HTTP API 的本地推理引擎如lmstudio、text-generation-webui等。核心是写好不同 API 之间的请求/响应转换器。添加中间件功能利用 Hono 的中间件系统你可以轻松添加日志记录、请求过滤、响应缓存、甚至简单的提示词prompt预处理功能。例如在所有代码补全请求前自动添加一个“你是一名资深程序员”的系统提示。修改隧道提供商如果你不想用 Cloudflare Tunnel可以修改代码集成ngrok、localhost.run或其他内网穿透工具。当然对于绝大多数用户来说直接使用 JSR 上的版本已经足够完美。curxy的价值在于它精准地命中了一个痛点并用最小可行产品MVP的方式优雅地解决了它没有一丝多余的设计。这种“简单即美”的哲学正是优秀工具软件的标志。