跳至主要內容

本地 AI 编程：OpenCode + Ollama + qwen3-coder 完全指南

dotli2026/2/12开发工具OpenCodeOllamaAI 编程qwen3-coder大约 11 分钟

本地 AI 编程：OpenCode + Ollama + qwen3-coder 完全指南

适用场景：注重代码隐私、需要断网可用、希望零成本使用 AI 编程助手的开发者

在 AI 辅助编程日益普及的今天，如何在本地环境搭建一套完整的 AI 编程工作流成为开发者关注的焦点。本文将介绍如何通过 OpenCode、Ollama 和 qwen3-coder 大模型，打造一套完全本地化的 AI 编程解决方案。

🌟 为什么选择本地 AI 编程？

优势说明
🔒 隐私安全代码完全留在本地，敏感代码不上传云端
🚀 离线可用无网络环境下也能正常工作
💰 零成本无需支付 API 调用费用
⚙️ 自定义能力强可自由选择模型和配置参数
🎯 低延迟本地推理响应更快

📦 工具介绍

什么是 OpenCode？

OpenCode 是一个开源的 AI 编程助手，核心是一个基于终端的 CLI 工具（使用 Go 语言开发），可以与 VS Code、Cursor、Windsurf 等主流编辑器集成。

核心特性：

  • ✅ 多平台支持：Terminal、Desktop、IDE 扩展
  • ✅ 多模型兼容：支持 OpenAI、Anthropic、Google 等云端模型，也支持 Ollama、LM Studio 等本地模型
  • ✅ 终端交互：通过 TUI（终端用户界面）与 AI 交互
  • ✅ 免费额度：提供免费的模型额度可用

什么是 Ollama？

Ollama 是一个开源的大语言模型本地运行框架，让在本地运行大模型变得简单。它支持众多开源模型，包括 Llama、Qwen、DeepSeek 等。

主要特点：

  • 一键安装和运行模型
  • 支持 GPU 加速
  • OpenAI 兼容的 API 接口
  • 丰富的模型库

什么是 qwen3-coder？

Qwen3-Coder 是阿里巴巴通义千问团队推出的代码专用大模型，专为代码理解和生成优化。它在代码补全、代码解释、Bug 修复等任务上表现出色。

核心优势：

  • 💻 代码能力突出：支持 92 种编程语言
  • 🧠 上下文理解强：256K 长上下文处理能力
  • ⚡ 响应速度快：针对推理做了专项优化
  • 📜 开源可定制：Apache 2.0 许可证

🔧 环境准备

1. 安装 Ollama

macOS:

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

Linux (Ubuntu/Debian):

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

Linux (RHEL/CentOS/Fedora):

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

Windows:

  1. 访问 Ollama 官网 下载安装程序
  2. 或者在 PowerShell 中运行：
    winget install Ollama.Ollama

安装完成后，Ollama 服务会自动启动，默认监听 http://localhost:11434。

2. 拉取 qwen3-coder 模型

ollama pull qwen3-coder@14b

模型大小选择指南：

根据硬件配置选择合适的模型大小，强烈建议使用量化版本以节省显存：

模型版本推荐显存特点适用场景
qwen3-coder:1.8b2GB+响应最快快速原型、学习测试
qwen3-coder:4b4GB+均衡选择日常开发
qwen3-coder:7b8GB+代码理解复杂任务
qwen3-coder:14b16GB+能力强专业开发
qwen3-coder:32b32GB+最强性能企业级应用

量化版本推荐：

# Q4 量化：推荐平衡选择（显存占用约减少 40%）
ollama pull qwen3-coder@14b-q4_K_M

# Q5 量化：更高精度（显存占用约减少 30%）
ollama pull qwen3-coder@14b-q5_K_S

# Q8：接近原始精度（显存占用约减少 20%）
ollama pull qwen3-coder@14b-q8_0

3. 验证模型安装

# 简单测试
ollama run qwen3-coder "请介绍你自己"

# 代码能力测试
ollama run qwen3-coder "写一个快速排序算法，要求带注释"

# 等待输出完成后按 Ctrl+D 退出

如果返回代码或模型介绍，说明模型安装成功。

4. 确认 Ollama API 可用

# 检查服务状态
curl http://localhost:11434/api/tags

# 查看运行中的模型
ollama list

返回模型列表表示服务正常运行。

🛠️ 安装 OpenCode

安装 CLI 工具

macOS / Linux (使用 Homebrew)

brew install opencode-ai/opencode/opencode

如果 Homebrew 不可用，可以直接下载二进制文件：

macOS:

curl -L https://github.com/opencode-ai/opencode/releases/latest/download/opencode_darwin_amd64 -o /usr/local/bin/opencode

Linux:

curl -L https://github.com/opencode-ai/opencode/releases/latest/download/opencode_linux_amd64 -o /usr/local/bin/opencode

设置执行权限：

chmod +x /usr/local/bin/opencode

Windows

winget install opencode

💻 安装 VS Code 扩展

code --install-extension opencode

或者在 VS Code 扩展市场搜索 "OpenCode" 安装。

扩展会自动检测并激活 CLI 工具。

⚙️ 配置 OpenCode

配置文件位置

# macOS: ~/Library/Application Support/opencode/config.json
# Linux: ~/.config/opencode/config.json
# Windows: %APPDATA%/OpenCode/config.json
# VS Code 用户目录：~/.config/Code - User/User/globalStorage/opencode/opencode/config.json

基础配置（默认使用 Ollama 本地模型）

{
  "provider": "ollama",
  "model": "qwen3-coder@14b-q4_K_M",
  "baseUrl": "http://localhost:11434",
  "llmSystemPrompt": "你是一个专业的软件开发助手，精通多种编程语言和框架。请提供清晰、高效、符合最佳实践的代码。回答时使用简洁的中文。",
  "maxTokens": 4096,
  "temperature": 0.7,
  "timeout": 120
}

环境变量配置（推荐）

在 ~/.zshrc 或 ~/.bashrc 中添加：

export OPENCODE_PROVIDER=ollama
export OPENCODE_MODEL="qwen3-coder@14b-q4_K_M"
export OPENCODE_BASE_URL=http://localhost:11434
export OPENCODE_LLM_SYSTEM_PROMPT="你是一个专业的软件开发助手，精通多种编程语言和框架。请提供清晰、高效、符合最佳实践的代码。回答时使用简洁的中文。"
export OPENCODE_MAX_TOKENS=4096
export OPENCODE_TEMPERATURE=0.7
export OPENCODE_TIMEOUT=120

然后在 VS Code 中重启以应用环境变量。

VS Code 中配置

在 VS Code 设置 (Ctrl+,) 中添加：

{
  "opencode.provider": "ollama",
  "opencode.model": "qwen3-coder@14b-q4_K_M",
  "opencode.baseUrl": "http://localhost:11434",
  "opencode.ollama.enableContextWindowManagement": true,
  "opencode.ollama.contextWindow": 128000,
  "opencode.maxTokens": 4096,
  "opencode.maxContext": 8192,
  "openable.modelTemperature": 0.7,
  "opencode.terminationMessage": "用户不再生成代码时",
  "opencode.timeout": 120
}

注意： VS Code 扩展会自动读取上述环境变量。

项目级配置

在项目根目录创建 .opencode.json：

{
  "provider": "ollama",
  "model": "qwen3-coder@14b-q4_K_M",
  "baseUrl": "http://localhost:11434",
  "systemPrompt": "你是一个 Python 专家，擅长使用 Flask/Django/FastAPI 框架。请遵循 PEP8 规范，使用类型注解，代码需有完整注释。",
  "exclude": [
    "**/node_modules/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
    "**/*.min.js",
    "**/vendor/**",
    "**/third_party/**",
    "**/*.test.*",
    "**/*_test.*",
    "**/__tests__/**",
    "**/*.log"
  ]
}

🚀 使用指南

启动 OpenCode

# 直接启动
opencode

# 指定工作目录（推荐用于项目开发）
opencode -c /path/to/project

# 调试模式（会显示详细的调试信息）
opencode -d

# 使用环境变量指定的工作目录
export OPENCODE_DIR=/path/to/project
opencode

VS Code 集成使用

  1. 打开集成终端（`Ctrl+``）
  2. 在终端中输入 opencode 启动
  3. AI 助手会在终端中响应用户输入
  4. 按 Tab 键补全可能的命令

VS Code 中可以直接使用 AI 助手，无需每次在终端启动。

核心功能场景

1. 代码补全与生成

> 创建一个 Python HTTP 服务器，支持静态文件服务

AI 会生成一个简单、安全的 HTTP 服务器代码。

2. 代码解释与审查

选中一段代码后：

> 解释这段 Rust 代码做了什么，分析时间和空间复杂度

AI 会详细分析代码的功能、性能特性和潜在问题。

3. Bug 修复

将报错信息发送给 AI：

> 修复这个报错：
> error: expected function body because this is not marked as async
> 提示：函数应该返回什么类型

4. 重构优化

> 重构这段代码，提高可读性和执行性能
> [粘贴代码]

5. 代码生成带测试

> 生成一个 Node.js 模块，处理 JSON 数据解析，包含单元测试示例

🔒 安全配置（重要！）

1. 排除敏感文件

在 config.json 中添加排除规则：

{
  "exclude": [
    "**/.git/**",
    "**/.env/**",
    "**/secrets/**",
    "**/credentials/**",
    "**/.docker/**",
    "**/Dockerfile",
    "**/docker-compose.yml",
    "**/.github/**",
    "**/package.json",
    "**/yarn.lock",
    "**/pnpm-lock.yaml",
    "**/Cargo.toml",
    "**/go.mod",
    "**/Gemfile",
    "**/Podfile",
    "**/*.pem",
    "**/*.key",
    "**/id_rsa"
  ],
  "ignoreUserFiles": true
}

2. 限制最大上下文窗囗

防止过大代码被发送：

{
  "maxContext": 8192,
  "maxContextPercentage": 0.9
}

3. 禁用自动上传（某些配置下）

确保不在配置中包含任何上传相关选项。

⚡ 性能优化

1. 使用量化模型（大幅节省显存）

# 拉取 14B 模型 Q4 量化版本（推荐！）
ollama pull qwen3-coder@14b-q4_K_M

# 显存占用对比
# 14B 原始模型：约 28GB
# 14B Q4_K_M：约 14GB（节省 50%）
# 14B Q5_K_S：约 16GB
# 14B Q8_0：约 25GB

2. 调整上下文长度

{
  "maxContext": 8192,
  "maxContextPercentage": 0.7
}

3. GPU 加速配置

# 检查 GPU 是否被 Ollama 识别
ollama list

# 查看 GPU 详细信息
nvidia-smi

# 确保 Ollama 服务使用 GPU
# macOS/Linux: 安装会自动使用 GPU（如果有）
# Ubuntu: ollama serve --cuda (如需特殊配置)

4. 优化 OpenCode 响应速度

{
  "maxTokens": 2048,
  "temperature": 0.5,
  "timeout": 60,
  "includeContext": true
}

5. 模型响应时间测试

# 测试响应速度
time ollama run qwen3-coder@14b-q4_K_M "请写一个 Python Hello World"

🐛 常见问题排查

Q: 启动 OpenCode 显示 "模型不存在"

A:

# 1. 确认模型已下载
ollama list

# 2. 如果有模型列表但报错，尝试重新拉取
ollama pull qwen3-coder@14b-q4_K_M

# 3. 重启 Ollama 服务
ollama serve

Q: 连接 Ollama 超时

A:

# 1. 检查 Ollama 服务状态
curl http://localhost:11434/api/tags

# 2. 查看 Ollama 日志
tail -f /proc/$(pgrep ollama)/fd/1 2>/dev/null || echo "无法读取日志"

# 3. macOS/Linux 检查端口占用
lsof -i:11434 || netstat -tlnp | grep 11434

# 4. Windows 检查端口
netstat -ano | findstr 11434

# 5. 确保 Ollama 服务正在运行
# macOS：系统偏好设置中确认 Ollama 应用启动
# Linux：systemctl status ollama
# Windows: 任务管理器检查 Ollama 进程

Q: 模型响应太慢

A:

  1. 使用更小的模型：切换到 qwen3-coder@4b-q4_K_M 或 qwen3-coder@1.8b
  2. 使用量化版本：所有模型优先使用 Q4_K_M 版本
  3. 确保 GPU 加速：检查 ollama list 确认模型使用 GPU
  4. 减少上下文长度：设置 maxContext 为较小值
  5. 减少并发请求：避免同时在多个模型生成复杂内容

Q: VS Code 扩展无法启动

A:

# 1. 确认 CLI 工具已安装
which opencode          # macOS/Linux
where opencode          # Windows

# 2. 检查添加到 PATH
echo $PATH              # macOS/Linux
echo %PATH%             # Windows

# 3. 在 VS Code 设置中确认
# 编辑 settings.json，确保：
{
  "opencode.provider.cliBin": "opencode",
  "opencode.terminal.enable": true
}

Q: 提示 "Provider not found: ollama"

A:

# 确保配置文件中 provider 使用小写
{
  "provider": "ollama",
  "baseUrl": "http://localhost:11434"
}

# 如果是环境变量问题：
export OPENCODE_PROVIDER=ollama

# 重启 VS Code

Q: 模型下载缓慢或被墙

A:

# 1. 指定镜像源（可选）
OLLAMA_MODELS="/your/cache/folder" ollama pull qwen3-coder@14b-q4_K_M

# 2. 使用离线镜像文件（已下载后可离线使用）
# 在另一台机器上通过 Ollama Proxy 下载

# 3. 考虑使用镜像加速站（需要科学上网环境）

Q: 显存不足导致 OOM

A:

# 1. 切换更小模型
ollama rm qwen3-coder@14b
ollama pull qwen3-coder@7b-q4_K_M

# 2. macOS 使用 Apple Silicon 优化
# 在 Mac 上是 Metal 加速，无需担心显存

# 3. Linux 减少批处理大小
OLLAMA_NUM_THREAD=4 ollama run qwen3-coder "..."
OLLAMA_MAX_LOADED_MODELS=1

# 4. 使用模型卸载（如果支持）
OLLAMA_KEEP_LOADED=true

📋 快捷操作清单

一键初始化配置（macOS）

# 1. 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 2. 拉取模型
ollama pull qwen3-coder@14b-q4_K_M

# 3. 安装 OpenCode
brew install opencode-ai/opencode/opencode

# 4. 配置文件
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/config.json << 'EOF'
{
  "provider": "ollama",
  "model": "qwen3-coder@14b-q4_K_M",
  "baseUrl": "http://localhost:11434",
  "llmSystemPrompt": "你是一个专业的软件开发助手，请提供清晰、高效的代码，使用简洁的中文回答。",
  "maxTokens": 4096,
  "temperature": 0.7
}
EOF

# 5. 环境变量
echo 'export OPENCODE_PROVIDER=ollama' >> ~/.zshrc
echo 'export OPENCODE_MODEL="qwen3-coder@14b-q4_K_M"' >> ~/.zshrc
echo 'export OPENCODE_BASE_URL=http://localhost:11434' >> ~/.zshrc

source ~/.zshrc

VS Code 快速设置

在 VS Code settings.json 中添加：

{
  "opencode.provider": "ollama",
  "opencode.model": "qwen3-coder@14b-q4_K_M",
  "opencode.baseUrl": "http://localhost:11434",
  "opencode.exclude": [
    "**/.git/**",
    "**/.env/**",
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/*.min.js",
    "**/vendor/**"
  ]
}

然后重启 VS Code。

🎯 最佳实践

  1. 选择合适的模型

    • 开发测试：qwen3-coder@4b-q4_K_M 或 qwen3-coder@7b-q4_K_M
    • 生产项目：qwen3-coder@14b-q4_K_M
    • 快速响应：qwen3-coder@1.8b

  2. 保持配置简洁

    • 从基本配置开始，逐步添加高级选项
    • 避免过度配置，让 AI 处理大部分决策

  3. 利用项目级配置

    • 不同项目类型使用不同的 systemPrompt
    • 为前端/后端/移动端分别定制提示词

  4. 结合云端与本地模型

    • 简单任务：使用本地模型
    • 复杂推理/知识库：使用云端模型（如 Claude）

  5. 定期检查更新

    • 关注 Ollama 新版本
    • 留意 qwen3-coder 的最新量化版本

🌐 其他本地编程模型推荐

模型特点推荐版本适用场景
qwen3-coder代码能力优秀，中文优化14b-q4_K_M全能选择
deepseek-coder开源最强代码模型7b-q5_K_M, 33b复杂任务
codeLlamaMeta 出品，代码生成强7b-q4_K_M, 34b代码生成
StarCoder开源代码模型15b-q4_K_M/32b-q4_K_M代码理解
Phi-3/3.5微软小钢炮3.8b轻量快速
Yi-Coder01.AI 出品9b, 34b代码推理

总结

通过 OpenCode + Ollama + Qwen3-Coder 的组合，你可以在完全本地化的环境中享受 AI 辅助编程的便利：

  • ✅ 隐私保护：代码不上传云端
  • ✅ 零成本：无需 API 费用
  • ✅ 离线可用：断网环境下正常工作
  • ✅ 低延迟：本地推理速度快
  • ✅ 可定制：自由选择模型和配置

随着本地大模型能力的不断提升，这套方案的效果已经非常接近云端服务。如果你是注重代码隐私和安全性的开发者，强烈建议体验本地 AI 编程的乐趣！

参考资源