OpenCode配置Ollama本地方案：无需API、4步部署免费编程助手

你有没有想过，用AI辅助写代码可以完全不花钱，甚至断网也能用？有一种方法，能让你在自己的机器上运行一套AI编程助手，不仅免费，而且代码数据永远不会离开你的硬盘。

这就是 OpenCode + Ollama 的组合方案。作为一个折腾过不少开发工具的程序员，我用过从最早的 GitHub Copilot 到后来价格不菲的 Claude Code，再到各种按 Token 计费的 API 接入方案。不得不承认，付费服务的体验确实香，但每月账单累积起来，钱包是真的有点扛不住。直到我把目光投向了 Ollama + OpenCode 这套本地部署方案。

为什么要折腾本地模型？

在鼓吹这套方案之前，有必要先给你泼点冷水：本地模型并没有你想象中那么“神奇”。

首先，响应速度完全取决于你的显卡。如果你指望用核显或者入门级独显跑个 7B 模型，还能快如闪电，那根本不现实。高端卡和普通卡之间的差距，大概就是超跑和家用代步车的区别——都能上路，但推背感天差地别。

其次，智力水平严格受限于参数规模。7B 的模型打磨得再好，在逻辑复杂度上也不可能超越 70B 参数的大模型。这是算力约束下的物理规律，不是换个开源模型就能突破的瓶颈。

第三，配置过程本身可能深坑不断。Windows 下的路径问题、macOS 的权限限制、Linux 的驱动兼容性……每一个环节都可能让你踩坑，消耗不少排查时间。

所以，如果你在严肃的生产环境中需要极高精度的代码输出，我还是会建议老老实实用商业 API。专业的事交给专业的云端服务，确实更省心。

那为什么还要费劲写这篇文章？因为本地部署有两个让开发者无法拒绝的“真香”场景：

第一，极致省钱。 重要的事情值得说三遍：省钱、省钱、还是省钱。你可以在本地想怎么用就怎么用，完全不担心账单。一口气跑几万 Token 的实验，试错成本几乎为零。很多时候你只是想验证一个想法是否跑得通，换成 API 的话每次调用都要算着小数点后几位扣费，难免束手束脚。本地模型完全没有这种心理负担，你让它改十遍、跑十遍，它也不会朝你要一分钱。

第二，绝对隐私。 代码离网处理，不上传云端。对于那些包含公司内部逻辑、商业机密，或者单纯不想提前曝光个人项目的代码来说，这一点至关重要。你的代码永远老实地躺在你自己的硬盘上，甚至可以直接断开互联网运行，安全感直接拉满。

此外，本地模型还有一个隐藏福利：正因为不花钱，你不会再有“这次调试会不会太烧钱”的心理包袱。想调就调，想试就试，这种高度自由的试错过程反而更容易激发出一些意想不到的解法。

一句话总结：本地模型可能不是最强的，但它一定能给你前所未有的自由感，尤其是在学习和实验场景下。

你的硬件能扛住多大的模型？

在开始动手配置之前，先对照一下你的硬件水平，免得兴致勃勃装好了，结果跑起来卡成幻灯片。

下面是一份目前比较主流的本地编程模型清单，我按参数量和硬件需求做了分类，供你参考：

推荐模型	参数规模	建议内存	适合场景	编程能力
qwen2.5-coder:3b	3B	8GB	能跑就行	⭐⭐ 够用
llama3.2:3b	3B	8GB	能跑就行	⭐⭐ 够用
qwen2.5-coder:7b	7B	16GB	主流推荐	⭐⭐⭐⭐ 较强
llama3.1:8b	8B	16GB	通用能力强	⭐⭐⭐⭐ 较强
deepseek-coder-v2	16B/236B	32GB+	代码能力最强	⭐⭐⭐⭐⭐ 最强
codestral	22B	32GB	专业编程	⭐⭐⭐⭐⭐ 最强

稍微展开说说各个型号的特点：

qwen2.5-coder 系列 是阿里通义千问的代码专用模型。3b 版本胜在轻快，非常适合内存紧张的机器，查查文档、改改简单 bug 绰绰有余。7b 版本则堪称主流配置的“甜点”型号，编程能力在同级中表现出色，性价比极高。至于 16b 以上版本，代码理解力会有质的提升，但也需要更大的内存支持。

llama3 系列 是 Meta 的开源之作。8b 版本的通用能力很强，不光是写代码，帮你起草文档、扮演对话伙伴都游刃有余，内存开销稍高一些，但换来的体验提升是值得的。

deepseek-coder-v2 属于代码能力的第一梯队。值得注意的是，其 16B 是指激活参数量，总参数量高达 236B。这是开源模型里的“旗舰”产品，但内存需求也相当感人——基本 32GB 起步。如果你的机器有 64GB 内存或专业级大显存显卡，可以首选它。

codestral 则是 Mistral AI 推出的专业编程模型，22B 的规模属于中等偏大，编程能力很强，同样需要大内存来驱动。

硬件选择建议：

• 8GB 内存：别挣扎了，老老实实用 qwen2.5-coder:3b 或 llama3.2:3b。虽然能力有限，但至少能跑起来。开着 IDE 同时运行可能会有点卡，但还算能忍。
• 16GB 内存：这是当下的主流配置。qwen2.5-coder:7b 和 llama3.1:8b 都能流畅运行，体验不错。如果你需要同时开着 IDE、一堆浏览器标签和数据库，建议关掉一些后台程序，或者降级用 3b 版本。
• 32GB 以上内存或配备高端显卡（显存 8GB+）：可以大胆尝试 16B 以上的模型。处理复杂逻辑时，你就能明显感觉到大模型的优势了。

一个小提示：如果你的内存刚好卡在 16GB，建议先从 7b 版本开始用，习惯之后再尝试升级。模型可以随时通过命令更换，无需重新配置环境。

从零开始配置：一步步跟着做

这部分是全文最核心的实操环节，我尽量做到手把手带你走通。

第一步：安装 Ollama

Ollama 是运行模型的基石，必须先装好。

macOS 用户 直接用 Homebrew，一行命令搞定：

brew install ollama

Linux 用户 使用官方提供的一键安装脚本：

curl -fsSL https://ollama.com/install.sh | sh

这个脚本会自动检测你的系统并完成依赖安装。如果遇到权限问题，记得在命令前加上 sudo。

Windows 用户……这里有个大坑。官方虽然提供了 Windows 原生版本，但实际测试下来问题不少。内存管理效率不如 Linux，底层调用也可能出现一些莫名其妙的错误。我的建议是，安装 WSL2 （Windows Subsystem for Linux），然后在 Linux 子系统中玩这套方案。WSL2 的体验和原生 Linux 几乎没有差别，而且社区资料丰富，踩坑后更容易找到解决方案。

具体操作路径是：控制面板 → 程序 → 启用或关闭 Windows 功能 → 勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”。之后去 Microsoft Store 下载 Ubuntu 或 Debian，最后在里面执行 Linux 的安装步骤。

安装完成后，验证一下：

ollama --version

但凡能看到版本号，比如 ollama version 0.5.4，就说明安装成功了。如果提示 command not found，检查一下你的 PATH 环境变量。

第二步：下载模型

模型就是 AI 的“大脑”，选对了就成功了一半。我推荐先用 qwen2.5-coder 试试手，这个模型在同量级下编程能力相当能打。

7b 版本大约 4GB，下载速度取决于你的网络：

ollama pull qwen2.5-coder:7b

如果你只是想浅尝辄止，可以下载更轻量的 3b 版本，大概 2GB，几分钟就能搞定：

ollama pull qwen2.5-coder:3b

模型下载完毕后，核对一下：

ollama list

你应该能看到类似这样的输出：

NAME                     ID           SIZE      MODIFIED
qwen2.5-coder:7b         4f7a7c3e...  4.7GB    4 minutes ago
qwen2.5-coder:3b         8b3a9d1...   1.9GB    2 minutes ago

如果列表为空，说明下载不成功或名称有误，请重新执行 pull 命令。

第三步：启动 Ollama 服务

开发期间需要让 Ollama 在后台运行。有两种方式。

方式一：前台运行（推荐）

ollama serve

这会启动一个长期运行的服务，默认端口是 11434，并自动暴露一个兼容 OpenAI 接口的 API。终端会实时显示请求日志，方便调试。

方式二：系统服务托管
如果你用的是 Linux 且使用 systemd，可以将其设为开机启动：

sudo systemctl enable ollama
sudo systemctl start ollama

macOS 用户可以用 launchd。不过，我通常建议先用手动启动的方式，等一切稳定了再考虑配置成服务，这样出问题时更容易定位原因。

第四步：配置 OpenCode

这是最关键，也最容易出错的一步。八成的问题都出在这里。我们先创建配置目录：

mkdir -p ~/.config/opencode

然后编辑配置文件。OpenCode 支持全局配置（~/.config/opencode/opencode.json）和项目级配置（项目根目录下的 opencode.json）。一般建议用全局配置，一劳永逸。将下面的内容复制进去：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (本地)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:7b": {
          "name": "通义千问Coder 7B",
          "limit": {
            "context": 32768,
            "output": 4096
          },
          "modalities": {
            "input": ["text"],
            "output": ["text"]
          }
        }
      }
    }
  },
  "model": "ollama/qwen2.5-coder:7b"
}

我来解释一下这几个关键字段：

• baseURL：Ollama 服务的地址，末尾的 /v1 绝对不能少，缺了就会报 404。
• models 下的键名：必须和你 ollama list 里看到的名字完全一致。qwen2.5-coder:7b 的冒号不能错写成横线 -，这是个无数人踩过的坑。
• limit.context：模型支持的上下文长度，7b 版本一般支持 32K。
• limit.output：单次响应的最大 Token 数。
• model：指定默认使用的模型。

⚡ 三个必须牢记的深坑：

坑 1：配置文件路径
路径必须是 ~/.config/opencode/opencode.json。既不是 ~/.opencode，也不是 ~/.config/opencode/config.json，更不是随便放在桌面。很多人跑来问我为什么配置不生效，十有八九是路径没写对。

坑 2：baseURL
baseURL 必须是 http://localhost:11434/v1。末尾的 /v1 是 API 路径的一部分，漏了就会连接失败。另外，除非你特意配了 SSL 证书，否则老老实实用 http 协议。

坑 3：模型名称
ollama list 里显示什么名，配置文件里就写什么名。冒号 : 和横线 - 千万不能混淆，比如 qwen2.5-coder-7b 这种写法就是错误的。

第五步：验证配置

保存配置文件后，重启 OpenCode 以加载新配置：

opencode

进入交互界面后，输入 /models 命令来查看模型列表。如果能看到一个叫 “Ollama (本地)” 的选项，并且下面有你配置的 “通义千问Coder 7B (qwen2.5-coder:7b)”，就说明配置被成功读取了。选择该模型，随便发一句“你好，介绍一下你自己”，能收到正常回复，就表示一切就绪，可以开始你的免费编程之旅了。

常见问题排查指南

这里汇总了新手最容易遭遇的几类问题，以“现象-原因-解决”的形式列出，方便你对症下药。

故障一：配置文件没有生效

表现：输入 /models 后，看不到任何 Ollama 的模型选项。
原因分析：

1. 配置文件路径不正确。
2. JSON 语法存在错误。
3. 修改配置后没有重启 OpenCode。
   解决步骤：
   首先确认路径是否正确：

   cat ~/.config/opencode/opencode.json

   能正常显示内容，则路径无误。接着，校验 JSON 格式。可以用在线 JSON 校验工具，或者直接用命令行：

   python3 -m json.tool ~/.config/opencode/opencode.json

   如果 JSON 有问题会直接报错。最后，务必重启 OpenCode。最直接的方式是关掉重开。

故障二：模型找不到

表现：选择模型后报错 model not found 或类似提示。
原因分析：

1. Ollama 服务本身没在运行。
2. 配置文件中的模型名称与 ollama list 显示的不一致。
3. baseURL 配置有问题。
   解决步骤：
   首先验证 Ollama 服务是否正常：

   curl http://localhost:11434/api/tags

   如果返回了模型列表，说明服务正常。如果报 “Connection refused”，说明服务没启动，请执行 ollama serve。然后，再次核对模型名称的拼写。再次强调：冒号 : 和横线 - 是有区别的。最后，确认你的 baseURL 携带了 /v1 后缀。

故障三：响应速度极慢

表现：发送指令后，要等很久才能收到完整回复。
原因分析：

1. 正在使用 CPU 进行推理，速度天然慢。
2. 物理内存不足，系统被迫使用磁盘上的 Swap 空间。
3. 运行的模型太大，硬件带不动。
   解决步骤：
   这是正常现象，本地模型的响应速度严格受限于你的硬件算力。如果用的是核显或 CPU 推理，响应慢是注定的。有独立显卡会快很多，一般建议 8GB 以上显存才能比较流畅地跑 7b 模型。如果实在无法忍受延迟，可以降级用更小的模型（例如从 7b 换成 3b），虽然“智力”弱一点，但“手速”能快很多。

故障四：内存爆炸 (OOM)

表现：运行一段时间后，整个系统变得非常卡顿，或者程序直接报 OOM（Out of Memory）错误并退出。
原因分析：

1. 运行的模型过大，物理内存完全撑不住。
2. 同时开启了太多吃内存的程序。
   解决步骤：
   先查看内存余量：

   # Linux 查看剩余内存
   free -h
   # macOS 查看内存压力
   top -l 1 | grep -i memory

   如果可用内存趋近于零，解决办法如下：

3. 关掉其他占用内存的程序，比如浏览器、IDE 等。
4. 换用资源需求更小的模型（如 3b 版本）。
5. 临时增加系统 Swap 空间（这会牺牲一部分速度）。
6. 终极解决方案——物理增加内存。

实际体验到底如何？

说了这么多，本地模型用起来究竟怎么样？不跟你讲虚的，和顶级云端 API 相比，差距是客观存在的。参数规模决定了智力上限，7b 模型再怎么优化，也不可能越级挑战 70B 的模型。

具体到编程任务上：

• 代码补全：可用，但遇到复杂逻辑时比较容易“猜”错。
• 代码审查：能揪出比较明显的问题，但深层次的逻辑隐患很难发现。
• 重构：处理简单重构没问题，复杂的大型重构容易跑偏。
• Bug 修复：简单的 Bug 通过一两轮对话就能解决，但复杂的 Bug 需要更细致的引导和多轮交互。

不过，对于日常的辅助编程，它完全够用了。写个工具函数、查查 API 用法、修个简单的 Bug、优化一小段代码，这些活它都能胜任。最关键的是，因为完全免费，你可以毫无心理负担地让它反复修改，从不同的角度去尝试。很多时候，这种“不心疼”的探索过程，反而能让你学到更多东西。在 云栈社区，我们也看到越来越多的开发者开始追求这种工具链的自主可控，这背后的技术信任感和低成本试错的能力，正是本地部署的魅力所在。

进阶：切换模型与微调参数

配置好之后，如果你想换用别的模型或调整运行参数，非常方便。

切换模型
三步走：

1. 下载新模型，例如 ollama pull llama3.1:8b。
2. 在 opencode.json 的 models 块中参照已有格式添加新模型的配置项。
3. 修改最外层 model 字段的值为 ollama/llama3.1:8b，然后重启 OpenCode。

调整参数
Ollama 支持配置生成参数，比如 temperature 和 top_p。可以在 options 里直接添加：

"options": {
    "baseURL": "http://localhost:11434/v1",
    "temperature": 0.5,
    "top_p": 0.9
}

• temperature：0-1 之间，值越低，输出越保守、严谨，适合代码生成；值越高，输出越发散、“有创意”，适合文案写作。编程场景建议设置在 0.3-0.5。
• top_p：另一种控制随机性的方式，通常和 temperature 二选一使用。

总结

这就是 OpenCode + Ollama 的完整本地部署流程。这套方案设置好之后，一个完全运行在你本地硬件上的免费 AI 编程助手就搭建好了。代码不上网，API 不花钱，隐私握在自己手里，这种无拘无束的编程体验，确实是任何按量付费的云端服务都给不了的。

如果你的电脑配置达标，我非常建议你亲自折腾一下。一次配置，长久受益。当然，如果你的首要目标是追求当前最强、最精准的代码生成能力，那么该为商业服务付费的钱，还是得花。但对于海量的日常学习、实验和个人项目来说，本地模型，永远滴神。快去试试吧，期待你在本地探索出更多新的玩法。