在Claude Code和Cursor中使用Ollama（模型 locaux)

#为何在 Claude Code 或 Cursor 中使用 Ollama？

三个反复被提及的原因。首先是隐私：受 NDA 约束的客户项目、专有代码、文件中以明文保存的机密信息——这些内容都不应该发送给第三方。其次是成本：Cursor Pro 每月收费 20 美元，Claude Code 会消耗 Anthropic 的 token，频繁使用时，费用很快就会达到每月 50–100 美元。使用 Ollama，购买 GPU 后费用就是零。最后是抗故障能力：即使 Anthropic 的 API 出现故障，或您的 ADSL 连接中断，您的助手也不会停止运行。

这是一个实实在在的取舍：本地运行的 Qwen3-Coder 30B 在涉及多个文件的复杂智能体任务上，不及 Claude Sonnet 4.6 或 GPT-5。但对于80%的日常用途——补全代码、重构、编写测试、解释代码块、生成提交——一个9B至30B、采用 Q4 量化的编程模型已经绰绰有余。您也可以同时保留云端服务，用来处理更棘手的任务。

#Ollama 的 OpenAI 兼容端点

自 0.1.24 版本起，Ollama 在提供原生 API 的同时，新增了与 OpenAI ChatCompletions API 兼容的端点。正是这一特性使得后续功能得以实现：任何 OpenAI 客户端（Python SDK、Node SDK、Cursor、Cline、Aider、Continue 等）均可直接使用 Ollama，无需修改，仅需更改 base URL 即可。

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder:30b",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

响应格式与 OpenAI 相同：choices[0].message.content、包含 prompt_tokens 和 completion_tokens 的 usage 字段，以及通过 stream: true 支持流式传输。API 密钥会被忽略——你可以在 Authorization 请求头中发送任意内容，Ollama 都会接受。不过，许多客户端不接受空字段：填入 ollama 或 anything 即可满足它们的要求。

#先决条件

Ollama 0.5+

ollama --version 应能返回结果。在 Windows 上，系统托盘中的图标应处于活动状态。如果您从零开始，请参阅适用于您操作系统的 Ollama 安装指南。

配备 12 GB 显存的 GPU，或内存为 16 GB 及以上的 Mac M 系列电脑

一个 Qwen 3.5 9B Q4 约为 6.6 GB，一个 Devstral 24B Q4 约为 14 GB，一个 Qwen3-Coder 30B-A3B Q4 约为 19 GB。RTX 3060 12 GB 显存为 Qwen 3.5 9B 的最低可用配置；RTX 4070/4080 16 GB 或 Mac M3/M4 可完整运行 Devstral 24B 和 Qwen3-Coder 30B 模型。

Cursor 0.40+ 或 Claude Code CLI

从 cursor.com 获取 Cursor（内置 OpenAI 自定义模式）。通过 npm install -g @anthropic-ai/claude-code 安装 Claude Code。

对环境变量具备基本了解

对于Claude Code，需配置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。

#1. 将Cursor连接至Ollama

Cursor 提供了官方选项，可连接到兼容 OpenAI 的端点。这种方式非常适合聊天（Ctrl+L）和内联编辑（Ctrl+K）。但 Composer 智能体和 Tab 自动补全仍只能使用 Cursor 云端模型——这是 Anthysphere 明确认可的产品限制。

1. 01
   下载代码模型

   在 12 GB 显存上，Qwen 3.5 9B（qwen3.5:9b）是很好的起点：法语能力尚可，支持工具调用，具备 256k 上下文。在 16 GB 显存上，请换用 Devstral 24B（devstral:24b）；在 24 GB 显存上，请换用 Qwen3-Coder 30B-A3B（qwen3-coder:30b），这是一款标杆级代码 MoE 模型。
2. 02
   打开 Cursor 的设置

   Ctrl+Shift+J（Mac 上为 Cmd+,）→ Models 选项卡。您会看到 Cursor 的模型列表（claude-3.5-sonnet、gpt-5 等），每个模型都有切换开关。
3. 03
   添加自定义模型

   点击底部的 Add Model。输入 Ollama 模型的准确名称：qwen3-coder:30b。勾选复选框以启用该模型。
4. 04
   设置基础URL

   在 OpenAI API Key 部分，展开 Override OpenAI Base URL，输入 http://localhost:11434/v1，然后点击 Save。API Key 字段可填写任意内容（如 ollama 即可），Cursor 不接受空字段。
5. 05
   检查连接

   点击 Verify。Cursor 会向您的 Ollama 发送一个测试请求。如果返回 200，按钮会变为绿色，模型会出现在聊天界面的模型选择器中。

ollama pull qwen3-coder:30b

配置完成后，Cursor 的聊天功能（Ctrl+L）和内联编辑功能（Ctrl+K）就能使用您的本地模型。聊天面板顶部的模型选择器会列出 qwen3-coder:30b；如果您想临时切换，仍可使用 Cursor 的云端模型。

#2. 将 Claude Code 连接到 Ollama

Claude Code（Anthropic 的 CLI 工具）原生使用 Anthropic 的 Messages API，而非 OpenAI 的 Chat Completions API。两种协议有所不同（角色、工具调用格式、流式传输）。因此，要让 Claude Code 与 Ollama 通信，需要一个小型协议转换器——也就是代理服务，一端接收 Anthropic Messages 格式的请求，另一端发出 OpenAI Chat Completions 格式的请求。

实现这一功能的代表性项目叫 claude-code-router（GitHub 上的 musistudio/claude-code-router）。只需一条命令即可安装，它在本地的一个端口上运行，并支持按模型设置路由规则（例如：将 haiku 路由到 Ollama，将 sonnet 路由到真正的 Claude）。

1. 01
   安装Claude Code

   npm install -g @anthropic-ai/claude-code si ce n'est pas déjà fait. claude --version doit répondre.
2. 02
   安装 claude-code-router

   npm install -g @musistudio/claude-code-router. Le binaire ccr est ajouté au PATH.
3. 03
   在 Ollama 中拉取模型

   优先选择支持工具调用（tool calls）的模型：qwen3-coder:30b、devstral:24b 或 glm-4.7-flash。如果不支持工具调用，Claude Code 将无法调用其内部工具（Read、Edit、Bash 等），从而失去 90% 的实用价值。
4. 04
   配置路由器

   创建 ~/.claude-code-router/config.json 文件，其中 Providers 字段指向 Ollama，并配置一个名为 Router 的规则，将Claude模型路由至您的本地模型。
5. 05
   通过 ccr 启动

   使用 ccr code 代替 claude。封装程序会在后台启动代理服务器，导出指向该代理服务器的环境变量 ANTHROPIC_BASE_URL，然后启动 Claude Code。在 Claude Code 内，可通过 /model 切换路由。

ollama pull qwen3-coder:30b
# ou pour du pur agent de code
ollama pull devstral:24b

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "devstral:24b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,qwen3-coder:30b",
    "think": "ollama,devstral:24b",
    "longContext": "ollama,qwen3-coder:30b"
  }
}

ccr code
# Claude Code démarre, mais les requêtes filent vers Ollama
# Vérifier : /model affiche qwen3-coder:30b

不使用路由器的极简方案：也可以直接导出 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 环境变量，配置为使用兼容 Anthropic 的代理（以 --anthropic 模式运行的 LiteLLM 和 y-router 都属于这类代理）。这种方案更轻量，但缺少按任务设置规则的灵活性。

#3. 选择哪个编程模型：本地运行的 Qwen3-Coder 与 Devstral 对比

在 Ollama 上，2026 年夏季有几个模型系列在编程领域占据主导地位：Qwen3-Coder（阿里巴巴）、Devstral（Mistral AI），以及 GLM 4.7 Flash（Z.ai）或 gpt-oss（OpenAI）等通用 MoE（混合专家）模型。它们都开放权重，并可在消费级硬件上以 Q4 量化运行。

Qwen3-Coder 30B-A3B (Alibaba, Apache 2.0)

2026 年的全能标杆。工具调用支持可靠，支持多语言（法语表现尚可），擅长 Python/JS/Go/Rust，上下文长度为 256k。这是一个激活参数量为 30 亿的 MoE 模型：速度媲美 14B 稠密模型，质量达到 30B 模型的水平。Q4 量化后约占 19 GB。拉取标签：qwen3-coder:30b。

Devstral 24B (Mistral AI，Apache 2.0)

专为软件工程（SWE）智能体设计（多文件编辑、代码库导航）。在 Aider、OpenHands 中表现出色，推而广之，在 Claude Code 中也表现出色。24B 稠密模型在 Q4 量化下约占 14 GB，可装入 16 GB 显存。拉取：devstral:24b。

GLM 4.7 Flash (Z.ai, MIT) / gpt-oss 20B (OpenAI)

两款 MoE 模型都很擅长智能体模式。GLM 4.7 Flash（30B-A3B，约 19 GB）是出色的工具调用协调模型；gpt-oss 20B（约 14 GB，MXFP4，131k 上下文）速度更快，16 GB 即可容纳。拉取标识：glm-4.7-flash 或 gpt-oss:20b。

Qwen 3.5 9B（适用于 8–12 GB 显存 GPU 的备选方案）

仅需 6.6 GB，是一款代码能力扎实的通用模型，支持 256k 上下文和视觉。在显存紧张、尚未转向 24B 及以上模型时，是一个不错的备选。拉取：qwen3.5:9b。

采用 Q4_K_M（推荐的量化方式）时，各模型规模所需的 VRAM：7B ≈ 5 GB，14B ≈ 9 GB，24B ≈ 14 GB，32B ≈ 19 GB，70B ≈ 40 GB。上下文还会额外占用显存：32k token 的上下文需额外预留 2 至 4 GB，具体取决于模型。

#与云端相比的局限：本地方案在哪些方面落后

我们坦诚地说说，本地模型在哪些方面做得不如 Claude Sonnet 4.6 或 GPT-5：

上下文窗口

Ollama 默认将 num_ctx 限制在 4096 个 token；根据模型不同，可提升至 32k 甚至 128k，但需以 VRAM 为代价。Cursor 配合 Sonnet 云端版本可稳定处理 200k token。在大型单仓库项目中，云端可读取全部内容，本地则需选择性加载。

多步推理

当智能体连续进行 10 次彼此存在依赖关系的工具调用时，9–14B 模型会迷失方向。Sonnet 则能保持思路连贯。对于真正复杂的智能体编排，云端方案仍遥遥领先。

对较新 API 的了解

开放权重模型有知识截止日期（通常在 2025 年），不了解之后发布的 API。云端 Cursor 则受益于持续更新和网页搜索工具。

首token延迟

看似反直觉，云端可能启动得更快（无需加载模型）。在本地，两次调用之间模型会保持已加载的“热状态”——处理完第一个提示后，优势就会转回本地。

电力成本

RTX 4090 在负载下的功耗为 350 W。每天持续编程 8 小时 = 每月约 70 kWh = 在法国约 15 欧元。这仍远低于 Cursor 每月 20 美元加上 Claude 每月 50 美元的费用，但并非免费。

#技巧与故障排除

Cursor 返回 "OpenAI API key invalid"

API Key 字段必须填写非空值。填入 ollama、sk-anything 或任何看起来合理的字符串即可。这只是形式上的要求：Ollama 会忽略这个请求头。

Cursor无法识别该模型

Cursor（Add Model）中的模型名称必须与 ollama list 返回的名称完全一致（包括标签，例如 qwen3-coder:30b）。不能只写 qwen3-coder，也不能写 Qwen3 Coder。

Claude Code 陷入循环或反复提出同样的请求

本地模型经常无法正确调用工具。请确认模型支持函数调用（运行ollama show qwen3-coder:30b → 在capabilities中查找tools字样）。换用规模更大的模型，或简化任务。

回答在 2-3 句话后被截断

默认num_ctx = 4096。对于Claude Code和Cursor在代码库上下文场景下，可提升至16384或32768。使用Ollama：创建一个自定义Modelfile，设置PARAMETER num_ctx 32768，并执行ollama create coder-32k -f Modelfile。内存开销真实存在（KV缓存额外占用2-4 GB）。

显存已满，OOM

使用过程中，请检查 ollama ps。如果在 GPU/CPU 混合加载状态下看到 >100% loaded，说明模型有一部分转移到了系统内存中，运行速度会变得非常慢。解决方法：采用更激进的量化（Q3_K_M）、使用更小的模型，或降低 num_ctx。

每条回复延迟超过 5 秒

要么是模型有一部分转由 CPU 处理（见上一点），要么是 Ollama 在每次请求时都重新加载模型。请检查 OLLAMA_KEEP_ALIVE（默认值为 5 分钟）。设置 OLLAMA_KEEP_ALIVE=2h，让模型保持已加载、随时可用的状态。

#深入了解

您已经通过 Ollama 为 Cursor 或 Claude Code 提供代码模型服务。接下来可以顺势探索以下方向：

在编辑器中补全代码（FIM 行内补全）

《免费本地 Copilot》指南介绍如何安装 Continue.dev / Tabby / CodeGeeX，以实现类似 Copilot 的行内代码补全——这是 Cursor 聊天功能的自然补充。

选择合适的量化

Q4_K_M、Q5_K_M、Q8_0：《选择量化方式》指南比较了代码模型的实际质量损失，并解释了 Q3 在哪些情况下仍然可用。

定制代码模型

《使用 Ollama Modelfile 自定义模型》指南展示了如何设置 num_ctx、系统提示和温度参数，以打造契合您技术栈的编码模型。