---
title: 用 Ollama 在 OpenCode 中配置 Gemma 4（2026 年指南）
description: >-
  在本地运行 Google 的 Gemma 4，并将其接入 OpenCode 作为终端编程助手。适用于 Mac 的 Ollama + OpenCode
  完整配置教程。
date: 2026-04-04T00:00:00.000Z
location: 旧金山 · 2026 年 4 月 4 日
image: /images/gemma-4-ollama-opencode-setup-hero.jpg
keywords: >-
  gemma 4 opencode, ollama gemma 4, opencode 本地模型, gemma 4 ollama 配置, 本地运行 gemma
  4, opencode ollama 教程
faq:
  - question: 可以在 OpenCode 中将 Gemma 4 作为本地模型使用吗？
    answer: >-
      可以。安装 Ollama，拉取 gemma4 模型，然后在 ~/.config/opencode/opencode.jsonc 中将 Ollama
      添加为自定义 provider，使用 @ai-sdk/openai-compatible 适配器，将 baseURL 设为
      http://localhost:11434/v1.，然后在 然后在 OpenCode 中用 /models 切换到该模型即可。
  - question: Gemma 4 配合 OpenCode 运行需要多少内存？
    answer: >-
      默认的 Gemma 4 8B 模型通过 Ollama 加载后大约占用 9.6GB。配备 16GB 统一内存的 Mac 可以流畅运行该模型，同时使用
      OpenCode 也没问题。26B 变体需要 24GB 以上内存，不建议在大多数消费级硬件上使用。
  - question: Gemma 4 在 OpenCode 中进行交互式编程够快吗？
    answer: >-
      在 Apple Silicon 上配合 Ollama v0.19+，得益于 MLX 后端，Gemma 4 8B
      的运行速度完全可用。它能很好地处理代码补全、解释和简单编辑。对于需要前沿级推理能力的复杂任务，可以添加 Haimaker 作为第二个
      provider 来访问云端模型。
locale: zh-cn
translationKey: gemma-4-ollama-opencode-setup
---
OpenCode 是一款终端编程助手，能对接任何 OpenAI 兼容的 API。让它对接本地 Ollama 实例上运行的 Gemma 4，你就有了一个完全免费的编程助手——代码不出本机。

下面以 Apple Silicon Mac 为例，走一遍完整流程：安装 Ollama → 拉取 Gemma 4 → 接入 OpenCode。

## 前置要求

- 搭载 Apple Silicon（M1/M2/M3/M4/M5）且至少 16GB 统一内存的 Mac
- macOS，且已安装 Homebrew
- 已安装 OpenCode（参见 [opencode.ai](https://opencode.ai) 或通过包管理器安装）

Gemma 4 默认的 8B 模型加载后大约占用 9.6GB，因此 16GB 统一内存足以同时运行 Ollama 和 OpenCode，不会有问题。

## 第一步：安装 Ollama

```bash
brew install --cask ollama-app
```

这会将 `Ollama.app` 安装到 `/Applications/`，并将 `ollama` CLI 安装到 `/opt/homebrew/bin/ollama`。

## 第二步：启动 Ollama

```bash
open -a Ollama
```

等待菜单栏图标出现，然后验证服务是否正在运行：

```bash
ollama list
```

## 第三步：拉取 Gemma 4

```bash
ollama pull gemma4
```

下载约 9.6GB。验证：

```bash
ollama list
# NAME             ID              SIZE      MODIFIED
# gemma4:latest    ...             9.6 GB    ...
```

测试一下：

```bash
ollama run gemma4:latest "Hello, what model are you?"
```

检查 GPU 加速：

```bash
ollama ps
# Should show CPU/GPU split, e.g. 14%/86% CPU/GPU
```

Apple Silicon 上的 Ollama v0.19+ 会自动使用 Apple MLX 框架来加速推理。

## 第四步：配置 OpenCode 使用 Gemma 4

OpenCode 的配置文件位于 `~/.config/opencode/opencode.jsonc`。将 Ollama 添加为自定义 provider：

```jsonc
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:latest": {}
      }
    }
  }
}
```

由于 Ollama 在本地运行，不需要 API 密钥。但 OpenCode 要求有一个 auth 条目，因此在 `~/.local/share/opencode/auth.json` 中添加一个占位符：

```json
{
  "ollama": {
    "type": "api",
    "key": "ollama"
  }
}
```

重启 OpenCode，用 `/models` 切换到 `ollama/gemma4:latest`。

## 第五步：保持 Gemma 4 常驻内存

Ollama 默认在闲置 5 分钟后卸载模型。如果你全天都在使用这个助手，就会频繁遇到不必要的冷启动。

将 keep-alive 设为无限期：

```bash
launchctl setenv OLLAMA_KEEP_ALIVE "-1"
```

重启 Ollama 使设置生效。要让该设置在重启后仍然保留，请将其添加到 `~/.zshrc`：

```bash
export OLLAMA_KEEP_ALIVE="-1"
```

启用开机自启动：点击 Ollama 菜单栏图标 → **登录时启动**（Launch at Login）。

#### 开机自动预加载

创建一个 LaunchAgent，让 Gemma 4 在每次重启后都保持热加载、随时可用：

```bash
cat << 'EOF' > ~/Library/LaunchAgents/com.ollama.preload-gemma4.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ollama.preload-gemma4</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/ollama</string>
        <string>run</string>
        <string>gemma4:latest</string>
        <string></string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>StartInterval</key>
    <integer>300</integer>
    <key>StandardOutPath</key>
    <string>/tmp/ollama-preload.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/ollama-preload.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.ollama.preload-gemma4.plist
```

这会每 5 分钟向模型发送一个空提示，使其保持在内存中。

## Gemma 4 在 OpenCode 中擅长的场景

Gemma 4 8B 免费且本地运行，在日常编程工作中出乎意料地好用：

- **代码解释。** 问它某个函数是干什么的、模块结构是怎样的、某个正则匹配什么。回答清晰，在标准代码库上准确率也很高。
- **快速编辑。** 修个拼写错误、更新 import、给类型定义加个字段、重命名变量。单文件修改是它的强项。
- **样板代码生成。** 配置文件、测试桩、API 路由脚手架、Dockerfile 模板。这类常见模式对推理能力要求不高。
- **Shell 命令求助。** 忘了 `git` 的某个选项或 `jq` 的某个过滤器？Gemma 4 直接给你命令，不用再去 Stack Overflow 搜一圈。

## 不足之处

- **多步推理。** 需要跨多个文件进行规划或理解复杂控制流的任务，往往产出不完整。
- **大规模重构。** 如果需要跨代码库协调修改，8B 模型会顾此失彼。它可以逐个文件地改，但缺少全局视角。
- **边界情况和隐蔽 bug。** Gemma 4 能发现明显的问题，但会遗漏那些需要深入领域知识或仔细推理才能发现的 bug。

## 进阶：添加 Haimaker 使用云端模型

本地运行的 Gemma 4 覆盖了基本需求。一旦碰到它搞不定的场景（复杂调试、跨文件重构、需要深度推理的任务），你就需要云端模型了。[Haimaker](https://haimaker.ai) 提供一个 API 密钥即可访问 Claude Opus、GPT-5、Gemini Pro 等模型。

将 Haimaker 作为第二个 provider 与 Ollama 并列添加：

```jsonc
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:latest": {}
      }
    },
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {},
        "openai/gpt-5": {},
        "google/gemini-2.5-pro": {}
      }
    }
  }
}
```

将你的 Haimaker API 密钥添加到 `~/.local/share/opencode/auth.json`：

```json
{
  "ollama": {
    "type": "api",
    "key": "ollama"
  },
  "haimaker": {
    "type": "api",
    "key": "YOUR_HAIMAKER_API_KEY"
  }
}
```

现在你可以在 OpenCode 中用 `/models` 在本地模型和云端模型之间切换。简单任务用 Gemma 4，任务变难时切换到 Sonnet 或 GPT-5。

在 [haimaker.ai](https://haimaker.ai) 注册获取 API 密钥，并浏览[模型目录](https://haimaker.ai/models)。

<a href="https://app.haimaker.ai/sign-up?utm_source=blog&utm_medium=cta&utm_campaign=gemma4-opencode" class="cta-button">获取 HAIMAKER API 密钥</a>

## 故障排查

**Provider 未显示在 /models 中。** 编辑配置文件后请重启 OpenCode。OpenCode 运行期间不会重新加载 `opencode.jsonc` 的更改。

**"Model not found"错误。** 确保配置中的模型 ID 与 Ollama 显示的完全一致。运行 `ollama list` 并使用所显示的名称——通常是 `gemma4:latest`。

**Ollama 认证错误。** 虽然 Ollama 不需要认证，但 OpenCode 的 provider 系统要求在 `auth.json` 中有一个条目。占位符 `"key": "ollama"` 就够了。

**响应缓慢。** 确保你使用的是 Ollama v0.19+ 以获得 Apple Silicon 上的 MLX 加速。运行 `ollama --version` 检查版本。同时关闭占用统一内存的应用——开了大量标签页的浏览器是最常见的原因。

**上下文窗口问题。** Gemma 4 支持较大的上下文窗口，但在 16GB 硬件上，建议将输入控制在 32K token 以内以保持稳定的输出质量。如果你注意到长提示的响应质量下降，大概率就是这个原因。

## 常用 Ollama 命令

| 命令 | 说明 |
|---|---|
| `ollama list` | 列出已下载的模型 |
| `ollama ps` | 显示正在运行的模型及内存占用 |
| `ollama run gemma4:latest` | 交互式对话 |
| `ollama stop gemma4:latest` | 从内存中卸载模型 |
| `ollama pull gemma4:latest` | 更新到最新版本 |
| `ollama rm gemma4:latest` | 删除模型 |

---

*已经在使用 Haimaker 配合 OpenCode？查看完整的[自定义 provider 配置指南](/blog/how-to-add-haimaker-opencode)以添加更多模型。*