一、环境准备

项目最低要求推荐配置
操作系统Windows 10+/macOS 12+/Ubuntu 20.04+Ubuntu 22.04 LTS / macOS Sonoma+
CPUx86_64 / ARM64（支持 AVX2/NEON）8核+，多核调度优化
内存16 GB32 GB+（运行 9B/27B 模型）
显卡无（CPU 可推理）NVIDIA GPU 8GB+ VRAM（RTX 3060/4060+）
磁盘15 GB 可用空间50 GB SSD（模型缓存+项目文件）
网络首次拉取需外网后续可完全离线运行
依赖环境Python 3.9+ 或 Node.js 18+pip / npm 最新版

💡 提示：无 GPU 用户建议使用 q4_K_M 量化版本，响应速度可提升 3~5 倍。

二、详细部署步骤

2.1 安装并启动 Ollama

# Linux / macOS

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

# Windows

访问 https://ollama.com/download 下载 .exe 安装包，按向导完成安装

# 启动服务（默认监听 http://localhost:11434）

ollama serve &

2.2 拉取 Gemma 4（或替代版本）

# 尝试拉取 gemma4（若未发布会自动提示可用版本）

ollama pull gemma4:9b

# 当前稳定替代方案

# ollama pull gemma3:9b          # 平衡性能与显存

# ollama pull gemma3:27b-q4_K_M  # 高配设备推荐量化版

# 验证模型可用性

ollama list

ollama run gemma4:9b “Hello, test local inference.”

2.3 安装 OpenCode

# 方式 1：pip 安装（Python 生态）

pip install opencode-cli

# 方式 2：npm 安装（Node.js 生态）

npm install -g @opencode/cli

# 验证安装

opencode –version

📌 注：不同发行版的 OpenCode 包名可能略有差异，请以 GitHub 官方仓库为准。本文以标准 CLI 版本为例。

2.4 配置 OpenCode 对接 Ollama

OpenCode 默认支持 OpenAI 兼容协议，只需修改 API 端点与模型名称即可对接本地 Ollama。

🔹 方法 1：环境变量（推荐，临时/CI友好）

export OPENAI_API_BASE=http://localhost:11434/v1

export OPENAI_API_KEY=ollama

export OPENCODE_MODEL=gemma4:9b

🔹 方法 2：配置文件（持久化）

创建 ~/.opencode/config.yaml（Windows: %USERPROFILE%\.opencode\config.yaml）：

api:

  base_url: http://localhost:11434/v1

  api_key: ollama

model: gemma4:9b

context_window: 8192

temperature: 0.3

max_tokens: 4096

auto_commit: true

theme: dark

🔍 验证连通性

# 测试 Ollama OpenAI 兼容接口

curl -s http://localhost:11434/v1/chat/completions \

  -H “Content-Type: application/json” \

  -H “Authorization: Bearer ollama” \

  -d ‘{“model”:”gemma4:9b”,”messages”:[{“role”:”user”,”content”:”Return only: OK”}]}’ | grep -o ‘”content”:”[^”]*”‘

# 预期输出：OK

三、操作与使用指南

3.1 启动与基础交互

# 进入项目根目录

cd /path/to/your/project

# 启动 OpenCode（自动加载上下文与配置）

opencode

# 交互示例

> /add src/main.py tests/test_core.py

> 为 extract_data 函数添加类型注解与异常处理逻辑

> 生成对应的单元测试，覆盖边界情况

> /explain ./config.yaml 第 12-18 行

> /undo          # 撤销最近一次代码修改

> /commit        # 自动生成 git commit 并提交

> /exit

3.2 核心命令速查

命令功能说明
/add <file>将文件加入上下文（支持 *.py、src/**/*.ts 等通配符）
/drop <file>移除指定文件上下文
/clear清空对话历史，释放内存与上下文窗口
/ask纯问答模式，不修改本地文件
/code强制进入代码生成/重构模式
/diff查看当前会话产生的代码变更
/commit自动生成符合 Conventional Commits 规范的提交
Ctrl+C中断当前流式生成
!!重复执行上一条指令

3.3 高级使用技巧

  1. 动态上下文注入：配合 Git 精准控制上下文范围

opencode $(git diff –name-only HEAD~1 | grep ‘\.py$’)

  1. 系统提示词定制：在配置文件中追加 system_prompt 字段

system_prompt: |

  你是一名资深后端工程师。遵循 SOLID 原则，优先使用类型安全写法，禁止硬编码密钥，所有外部输入必须校验。

  1. 调整上下文窗口：Ollama 默认 8K，可通过启动参数或配置文件调整

# 临时扩大至 16K（需足够显存/内存）

ollama run gemma4:9b –num_ctx 16384

  1. 多文件并行处理：使用 /add 批量加载后，用 @refactor 触发跨文件重构（依赖 OpenCode 版本支持）。

四、同类方案对比

方案架构模型支持隐私性成本部署难度适用场景
Ollama + OpenCode + Gemma4纯本地任意 Ollama 模型⭐⭐⭐⭐⭐零 API 费⭐⭐☆敏感代码、离线开发、深度定制、成本敏感
Claude Code (官方)云端 API仅 Anthropic Claude⭐⭐☆$15~$100/月⭐☆☆快速迭代、Claude 生态依赖、企业合规允许云端
GitHub Copilot云端OpenAI/Codex 闭源⭐☆☆$10/月⭐☆☆IDE 无缝集成、企业统一采购、非技术场景
LM Studio + Cursor本地+云端混合多格式 GGUF⭐⭐⭐混合计费⭐⭐☆可视化偏好、跨模型对比、教学演示
vLLM + OpenCompass + IDE 插件本地集群全量开源⭐⭐⭐⭐⭐硬件成本高⭐⭐⭐⭐算法团队、压测基准、高并发服务

🔍 方案选择建议

五、常见问题与性能优化

问题原因解决方案
Connection refusedOllama 服务未启动或端口被占lsof -i :11434 检查，执行 ollama serve
CUDA out of memory模型超出显存换 q4_K_M 量化版，或加 –num_gpu 0 强制 CPU
代码生成质量差提示词模糊/上下文不足明确语言、框架、约束条件；用 /add 注入依赖文件
响应极慢（>10s/字）无 GPU 或模型过大换 3B 模型，或启用 –threads 8 并行 CPU 推理
OpenCode 无法识别模型API 路径或参数不匹配确认 base_url 含 /v1，api_key 非空，模型名与 ollama list 一致

🛠 性能调优清单

  1. GPU 加速：export OLLAMA_NUM_GPU=99（优先使用全部可用显存）
  2. 量化策略：优先 Q4_K_M 或 Q5_K_M，平衡速度与质量
  3. 上下文控制：单次 /add 不超过 15 个核心文件，避免窗口溢出
  4. 缓存清理：定期执行 ollama rm <model> + rm -rf ~/.ollama/models/blobs
  5. 服务守护：使用 systemd（Linux）或 launchd（macOS）设置 Ollama 开机自启