在 MacBook Air 上搭建本地大模型环境：Ollama 与 OpenCode 配置教程

想在笔记本上离线跑一个大模型，又不想把代码和资料发到云端，Ollama 加 OpenCode 是一条门槛较低的路线：Ollama 负责在本机加载模型并暴露一个 OpenAI 兼容的 HTTP 接口，OpenCode 负责把这个接口当成模型供应商来调用，从而在终端或编辑器里获得一个可对话、可改代码的代理。这套组合适合两类人：一是有明确的离线或内网需求、必须让推理发生在自己机器上的开发者；二是云端订阅额度用尽、想临时用本地模型顶一阵的人。需要提前说明的是，本地小模型在响应速度和代码质量上都无法与云端大模型持平，把它当作应急与实验手段更现实。本文以一台 Apple Silicon 的 MacBook Air 为例，把安装、常驻、拉模型、配接口、接编辑器这几步完整走一遍。

准备工作

硬件与系统前提

本地推理的瓶颈几乎全在内存上。示例机器是一台 Apple Silicon 的 MacBook Air，统一内存 24GB，系统为较新的 macOS 版本。统一内存意味着 CPU 与 GPU 共用同一块内存池，模型权重加载一次即可被 GPU 直接访问，这也是 Apple Silicon 适合跑本地模型的原因。

24GB 这个容量决定了模型选择的边界：完整精度的中大模型基本放不下，量化版本才是现实选项。如果你的机器是 16GB 或更少，可选的模型范围会进一步收窄；如果经常需要跑更大的模型，与其在软件层面反复调优，不如直接考虑内存更大的机器。这一点在动手之前就该想清楚，否则容易在下载和试错上耗费大量时间。

需要安装的三样东西

Ollama：本地运行大模型的工具。命令行即可完成模型下载（ollama pull）与启动，同时可以作为 API 服务器对外提供接口。它本身也支持在终端里直接聊天，但本文主要用它提供接口。
OpenCode：在终端中运行的开源 AI 编码代理。除了云端模型，也可以接入本地运行的模型，这正是本文要用的能力。
VS Code：代码编辑器。安装 OpenCode 扩展后，可以在编辑器内调用 OpenCode，而不必切到终端。

三者都不需要付费账号即可开始，但模型文件本身会占用数 GB 磁盘空间，请预留足够容量。软件版本、可用模型列表与硬件要求会随时间变化，具体以各项目官网当前信息为准。

操作步骤

第一步：安装并启动 Ollama

只需要命令行和 API 服务，用 Homebrew 安装最省事：

brew install ollama

也可以从官网下载安装包，效果相同。安装完成后启动服务：

ollama serve

注意这个前台进程与终端窗口绑定，关掉终端 Ollama 也会随之退出。日常使用更推荐交给 Homebrew 的服务管理器托管，让它在登录时自动启动：

brew services start ollama

查看服务状态与停止服务分别用下面两条命令：

brew services list
brew services stop ollama

如果更习惯图形界面，Ollama 官方也提供带界面的应用，可以在应用内管理登录时是否自动启动。两种方式选一种即可，不要同时跑两份服务实例。

第二步：挑选并拉取模型

Ollama 的模型库里有大量可选模型。挑选时最实用的办法是把自己的机器配置（芯片、内存、系统）描述给一个云端 AI，让它推荐大概率能跑起来的模型；也可以直接按参数量估算，参数量越大对内存要求越高。

示例中使用的是 Google 基于与 Gemini 同源技术开发的轻量模型 gemma 系列。在 24GB 内存的机器上，量化版本是比较现实的选择——量化可以粗略理解为在尽量保留能力的前提下压缩模型的信息量，从而降低内存占用。下面几条命令把几个不同规格的版本都拉下来：

ollama pull gemma4:e2b
ollama pull gemma4:e4b
ollama pull gemma4:e2b-mlx
ollama pull gemma4:e4b-mlx
ollama pull gemma4:12b

即使是被称作轻量的模型，单个文件也有数 GB。反复试过多个模型之后，磁盘会明显吃紧，可以用下面的命令查看已下载的模型并清理不需要的：

ollama list
ollama rm <模型名>

第三步：确认模型的量化方式

同名模型可能对应不同的量化格式，直接影响速度与回答质量。查看某个模型详情里的 quantization 字段即可确认：

ollama show gemma4:e2b

示例中 gemma4:e2b 的量化方式是 Q4_K_M，也就是 4bit 量化。

标签里带 -mlx 的模型则是为 Apple 的机器学习框架 MLX 构建的。MLX 针对 Apple Silicon 的统一内存做了设计，能让 CPU 与 GPU 共享同一份内存。用同样的命令查看 gemma4:e2b-mlx，量化方式是 nvfp4，与 Q4_K_M 属于不同的量化格式。既然格式不同，同一规格下两个版本的生成速度和回答风格就可能有差异，值得分别跑一跑做对比。

另外，较早一代的 gemma3 系列（例如 gemma3n:e2b、gemma3n:e4b、gemma3:4b-it-qat）也可以下载，但在示例环境中无法被 OpenCode 正常调用。选模型时如果发现某个模型在代理里始终不可用，先换一个模型验证链路是否通畅，再判断是不是模型兼容性问题。

第四步：安装 OpenCode

同样用 Homebrew 安装：

brew install opencode
opencode --version

OpenCode 也有桌面应用，但本文的用法是在 VS Code 里调用，所以只装命令行版本即可。想在终端里直接使用时，进入项目目录后执行：

cd ~/your/project/
opencode

第五步：把 Ollama 配置成 OpenCode 的模型供应商

Ollama 提供 OpenAI 兼容的 API，因此可以用 @ai-sdk/openai-compatible 这个适配器接入。配置写在 OpenCode 的配置文件 ~/.config/opencode/opencode.json 中，结构如下：

{
  "$schema": "...",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:12b": { "name": "gemma4:12b" },
        "gemma4:e2b": { "name": "gemma4:e2b" },
        "gemma4:e4b": { "name": "gemma4:e4b" },
        "gemma4:e2b-mlx": { "name": "gemma4:e2b-mlx" },
        "gemma4:e4b-mlx": { "name": "gemma4:e4b-mlx" }
      }
    }
  }
}

几个要点：

baseURL 指向本机 Ollama 的 OpenAI 兼容端点，端口为 11434，路径为 /v1。如果 Ollama 没有启动，这里会直接连接失败。
models 下的键名必须与 ollama list 中显示的模型名完全一致，包括冒号和标签部分，写错一个字符就调不到。
想增加可选模型时，先用 ollama pull 下载，再在 models 里追加一条对应条目，不需要重启其他组件。
$schema 字段用于编辑器校验与补全，按项目说明填写对应的 schema 地址即可。

第六步：在 VS Code 中接入

编辑器这一侧几乎没有额外配置，安装 OpenCode 扩展后即可在编辑器内调用 OpenCode。扩展读取的是同一份 opencode.json，所以不需要在扩展里再单独配置一遍模型列表，终端与编辑器共用同一套供应商定义。

一个完整示例

下面从零开始，把一条最小可用链路走完，验证本地模型能否被 OpenCode 正常调用。

1. 安装并常驻服务

brew install ollama
brew services start ollama
brew services list

确认服务处于运行状态，再继续下一步。

2. 拉取一个模型并确认量化格式

ollama pull gemma4:e2b
ollama show gemma4:e2b

在输出中找到 quantization 字段，示例中为 Q4_K_M。同时记下模型名，后面配置要用。

3. 安装 OpenCode

brew install opencode
opencode --version

4. 写入配置文件

创建或编辑 ~/.config/opencode/opencode.json，只保留一个模型，便于先验证链路：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:e2b": { "name": "gemma4:e2b" }
      }
    }
  }
}

5. 在项目目录中启动

cd ~/your/project/
opencode

在 OpenCode 中选择 Ollama 供应商下的 gemma4:e2b，让它生成一段最简单的代码，例如输出 hello 的 Python 脚本。这一步能跑通，说明 Ollama 服务、模型文件、配置文件三者都对上了。

6. 换模型做对比

链路验证通过后，再拉取 gemma4:e2b-mlx，在配置文件的 models 中追加条目，用同样的提示词再跑一次。由于量化格式不同（Q4_K_M 与 nvfp4），可以直观比较两者的生成速度与回答质量，再决定日常用哪一个。

7. 清理

ollama list
ollama rm gemma4:12b

把试用后不打算保留的模型删掉，回收磁盘空间。

注意事项

速度预期要放低

在这台 MacBook Air 上，即使只是让模型输出一个 Python 的 hello 程序，响应速度也明显慢于云端付费方案。如果平时习惯使用云端编码代理，本地小模型的体验会有明显落差，容易产生「还不如不用」的感觉。把本地模型定位为应急与实验工具，心理预期会更合理。

它适合什么场景

网络不可用或不允许联网的环境中，做简单的代码生成与问答。
云端 AI 服务暂时不可用或额度耗尽时，维持基本的工作连续性。
需要让推理完全发生在本地、数据不出机器的场合。

反过来说，如果只是想要更快的回答和更强的代码能力，本地小模型并不是合适的替代品。若确实有离线使用大模型的刚性需求，提升机器配置（尤其是内存）比在软件层面反复折腾更有效。

常见坑

关掉终端后服务消失：用 ollama serve 前台启动时，终端关闭服务即停止。需要长期可用就改用 brew services start ollama。
模型名对不上：配置文件里 models 的键必须与 ollama list 的输出完全一致，标签部分不能省略或改写。
模型不被代理识别：部分模型（例如示例中的 gemma3 系列）无法被 OpenCode 调用。遇到这种情况先换模型验证链路，再判断是兼容性问题。
磁盘被模型占满：轻量模型也有数 GB，多拉几个就会明显占用空间，定期用 ollama list 检查、用 ollama rm 清理。
内存不足：24GB 内存下量化版本才是现实选择，参数量更大的模型可能加载失败或运行极慢。

最后提醒一句：模型列表、量化格式、软件版本与硬件要求都会变化，动手前请以各项目官网的当前信息为准，不要照搬本文中的具体模型标签。