用 Ollama 在 OpenCode 中配置 Gemma 4（2026 年指南）

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 或通过包管理器安装）

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

第一步：安装 Ollama

brew install --cask ollama-app

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

第二步：启动 Ollama

open -a Ollama

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

ollama list

第三步：拉取 Gemma 4

ollama pull gemma4

下载约 9.6GB。验证：

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

测试一下：

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

检查 GPU 加速：

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：

{
  "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 中添加一个占位符：

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

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

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

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

将 keep-alive 设为无限期：

launchctl setenv OLLAMA_KEEP_ALIVE "-1"

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

export OLLAMA_KEEP_ALIVE="-1"

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

开机自动预加载

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

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 提供一个 API 密钥即可访问 Claude Opus、GPT-5、Gemini Pro 等模型。

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

{
  "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：

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

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

在 haimaker.ai 注册获取 API 密钥，并浏览模型目录。

获取 HAIMAKER API 密钥

故障排查

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 配置指南以添加更多模型。