Ollama本地部署与Cursor编辑器连接配置指南

在 Cursor 编辑器中集成本地大模型进行代码编写，能显著提升开发效率。然而，许多用户在配置 Ollama 后，常遇到 Cursor 无法连接的问题，提示连接失败或模型无响应。这通常并非模型本身的问题，而是 Cursor 未能正确识别到本地运行的 Ollama 服务。本文将提供一套完整的排查与解决方案，帮助您彻底打通连接路径。

一、确认 Ollama 服务已启动并监听正确地址

问题的根源往往在于网络监听配置。Ollama 默认启动时，仅绑定在 127.0.0.1:11434 这个本地环回地址上。这意味着只有本机上的应用程序可以直接访问。如果您的 Cursor 运行在 WSL 子系统内，或存在特定的网络环境配置，就可能无法“发现”该服务。

首先，请打开终端，执行 ollama serve 命令来启动服务（若已作为后台服务运行，可跳过此步）。

随后，检查服务实际监听的网络地址：

• 在 macOS 或 Linux 系统，运行 lsof -i :11434。
• 在 Windows 系统，运行 netstat -ano | findstr :11434。

关键在于：您需要确认输出结果中包含 0.0.0.0:11434 或您本机的局域网 IP 地址（例如 192.168.1.100:11434），而不仅仅是 127.0.0.1:11434。若仅为后者，则 Cursor 连接失败是必然结果。

二、设置 OLLAMA_HOST 环境变量强制绑定全接口

为确保 Ollama 服务能被更广泛的网络访问，最有效的方法是通过环境变量，强制其监听所有网络接口。

具体操作步骤因操作系统而异：

• macOS/Linux：在终端中执行 export OLLAMA_HOST=0.0.0.0:11434，然后再次运行 ollama serve。
• Windows（命令提示符）：执行 set OLLAMA_HOST=0.0.0.0:11434，再运行 ollama serve。
• Windows（PowerShell）：执行 $env:OLLAMA_HOST="0.0.0.0:11434"，再运行 ollama serve。

配置完成后，建议进行简单验证：重启 Ollama 服务，然后在浏览器中访问 http://localhost:11434/api/tags。若一切正常，您将看到一段 JSON 格式的响应，其中列出了您本地已安装的所有模型列表。若访问失败，请检查 11434 端口是否被其他进程占用，或是否被系统防火墙拦截。

三、在 Cursor 中配置 Ollama 模型端点

服务端配置妥当后，需要在 Cursor 客户端进行正确设置。Cursor 无法自动发现 Ollama，需手动指定其 API 地址和模型名称。

打开 Cursor 的设置界面（快捷键 Cmd+, 或 Ctrl+,），导航至 AI → Model Provider 页面。

在此页面，您需要完成以下关键配置：

1. 在模型提供方中选择 Ollama。
2. 在 Ollama API URL 字段中，填入您的服务地址。若为纯本地环境，填写 http://127.0.0.1:11434 即可。若涉及 WSL 或跨容器访问，则需填写您在上一步获取到的本机真实 IP 地址，例如 http://192.168.1.100:11434。
3. 在 Model Name 字段中，准确填入您已通过 ollama pull 命令下载的模型完整名称。请注意，此处名称必须与 ollama list 命令列出的结果完全一致，例如 qwen3:4b 或 llama3.2:3b，大小写及标点符号均需正确。

四、处理 WSL2 环境下 Cursor 的跨子系统访问问题

这是一个常见场景：您在 Windows 系统上使用 Cursor 编辑器，但为了获得更优的开发环境，将 Ollama 安装在了 WSL2（如 Ubuntu）子系统中。此时，Windows 系统中的“localhost”与 WSL2 子系统中的“localhost”并非同一网络实体，存在通信壁垒。

解决方案是让两者通过明确的 IP 地址进行直接通信：

1. 在 WSL2 的终端中，运行以下命令获取 Windows 主机在 WSL2 网络中的 IP 地址：cat /etc/resolv.conf | grep nameserver | awk '{print $2}'。通常会得到一个类似 172.28.16.1 的地址。
2. 在 WSL2 中，设置环境变量并启动服务：export OLLAMA_HOST=172.28.16.1:11434 && ollama serve。
3. 返回 Windows 系统中的 Cursor 设置，将 Ollama API URL 修改为上一步获取的 IP 地址，即 http://172.28.16.1:11434。
4. 最后，请务必在 Windows 防火墙设置中，为 11434 端口添加入站规则，允许来自 WSL2 子系统的网络访问。

五、验证与调试连接状态

若完成上述所有步骤后问题依旧，无需担心。Cursor 内置的开发者工具可以提供最直接的错误诊断信息。

1. 在 Cursor 中按下 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Windows/Linux），打开命令面板。
2. 输入并选择 Developer: Toggle Developer Tools，以开启开发者工具。
3. 切换到 Console（控制台）标签页。
4. 在编辑器中触发一次 AI 代码生成请求，例如选中一段代码后按下 Cmd+K。

此时，请观察控制台中打印的网络错误信息：

• 若出现 ERR_CONNECTION_REFUSED 错误，通常意味着服务未启动，或您填写的 API 地址根本不可达。
• 若出现 ERR_NETWORK_TIMEOUT 错误，表明网络可以连通，但服务未在指定时间内响应，可能是模型加载缓慢或服务进程卡顿。
• 若返回 404 Not Found 状态码，极有可能是模型名称拼写错误，或 API 路径配置有误。
• 若遇到 400 Bad Request 错误，这通常发生在请求模型执行“工具调用”（tool calling）功能时，而当前选用的模型版本可能不支持此特性。此时，建议尝试更换为更新或能力更强的模型版本，例如 qwen3:4b 或 llama3.2:3b 及更高版本。

遵循以上排查路径逐步操作，绝大多数 Cursor 连接 Ollama 的问题都能得到定位与解决。核心要点在于确保服务正在运行、连接地址准确无误、且网络防火墙未进行阻拦。成功配置后，您即可在 Cursor 编辑器中流畅地调用本地大模型，享受高效的智能编程辅助体验。