Ollama本地开发环境配置与连接指南
在 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 实例，需要你手动指定服务地址与模型名称。
打开 Cursor 设置（快捷键 Cmd+, 或 Ctrl+,），定位到 AI → Model Provider 页面。
在此页面完成以下配置：
- 在提供方列表中选择 Ollama。
- 在 Ollama API URL 字段中，填入你的服务地址。对于纯本地开发，填写 http://127.0.0.1:11434 即可。若涉及 WSL 或容器间访问，则需填入你获取到的本机真实 IP 地址，例如 http://192.168.1.100:11434。
- 在 Model Name 字段中，准确填入你已通过
ollama pull下载的模型完整名称。此名称必须与ollama list命令列出的结果完全一致，例如 qwen3:4b 或 llama3.2:3b，需注意大小写和标点符号。
四、处理 WSL2 下 Cursor 的跨子系统访问问题
这是一个典型场景：你在 Windows 上运行 Cursor，但为了获得更优的开发环境，将 Ollama 安装在 WSL2（如 Ubuntu）子系统中。此时，Windows 的“localhost”与 WSL2 的“localhost”处于不同的网络命名空间，无法直接通信。
解决方案是让两者通过 IP 地址进行直接网络通信：
- 在 WSL2 终端中，执行以下命令获取 Windows 主机在 WSL2 网络中的 IP 地址：
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'。通常会得到一个类似 172.28.16.1 的地址。 - 在 WSL2 中，设置环境变量并启动服务：
export OLLAMA_HOST=172.28.16.1:11434 && ollama serve。 - 返回 Windows 上的 Cursor 设置，将 Ollama API URL 修改为上一步获取的 IP 地址，即 http://172.28.16.1:11434。
- 最后，务必在 Windows 防火墙中为 11434 端口添加入站规则，允许来自 WSL2 网络的访问请求。
五、验证与调试连接状态
若完成上述步骤后连接依然失败，可利用 Cursor 内置的开发者工具获取直接的错误信息进行诊断。
- 在 Cursor 中按下 Cmd+Shift+P（macOS）或 Ctrl+Shift+P（Windows/Linux），打开命令面板。
- 输入并选择 Developer: Toggle Developer Tools，开启开发者工具。
- 切换到 Console（控制台）面板。
- 在编辑器中触发一次 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 中流畅地使用本地大模型来辅助编程工作。