不用按Token付费!OpenCode+Ollama部署Qwen3-Coder
不想为AI编程助手持续支付API费用?教你用OpenCode、Ollama和Qwen3-Coder搭建本地编程环境,详解显卡要求、安装步骤、模型配置与常见故障排查。

一、这套组合为什么值得单独写一篇
本地部署 AI 编程助手,过去最大的阻力不是模型能力,而是工程链路太长。要自建推理服务、自己写 OpenAI 兼容层、自己维护客户端插件,任何一环版本不匹配就跑不起来。
OpenCode + Ollama + Qwen3-Coder 这套组合,把三段拼图各自补齐了:
- OpenCode 是当前 GitHub 上 star 数达到 22.7 万的开源编程 Agent 项目,内置支持 200 多个模型提供商,模型切换只改一个配置字段。
- Ollama 承担本地运行时,负责权重下载、显存调度与服务暴露,对外提供 OpenAI 兼容的
/v1接口。累计下载量已超过 10 亿次。 - Qwen3-Coder 是阿里千问团队面向代码场景训练的模型系列,在 Ollama 上的下载量已突破 1100 万次。30B 版本采用 MoE 架构,激活参数 3.3B,上下文窗口 256K。
三者拼在一起的意义在于:代码不出本机。除了 Ollama 拉取权重那一次外网请求,后续所有推理都发生在本地环路,不经过任何第三方 API。数据合规要求严格的团队、内网隔离环境、或者单纯不想为每次补全付 token 费的个人开发者,都能直接受益。
完整链路搭建时间大约 15 分钟,前提是硬件达标。
二、架构分层与数据流向
整条链路分三层,从上到下依次是客户端、运行时、模型。
| 层级 | 组件 | 职责 | 关键参数 |
|---|---|---|---|
| 客户端 | OpenCode | 编程 Agent 界面、上下文收集、工具调用 | 200+ 模型提供商内置 |
| 运行时 | Ollama | 权重管理、显存调度、OpenAI 兼容 API | 默认监听 127.0.0.1:11434 |
| 模型 | Qwen3-Coder 30B | 代码生成与补全推理 | 256K 上下文、激活 3.3B、显存 19GB |
数据流向清晰:OpenCode 读取项目文件、构造提示、通过 HTTP 调用本地 Ollama 的 /v1/chat/completions 接口,Ollama 加载模型完成推理并返回结果。中间没有任何外部网络跳出。
这也是这套方案与云端 API 的核心差异:延迟由本地显存带宽和 GPU 算力决定,不受公网链路影响;成本固定为电费和硬件折旧,不随调用量线性增长。
三、硬件门槛与模型选型
选型表先给出,再解释判断逻辑。
| 模型 | 显存占用 | 上下文 | 激活参数 | 适用场景 |
|---|---|---|---|---|
| qwen3-coder:30b | 19GB | 256K | 3.3B(MoE) | 桌面级 GPU 日常开发 |
| qwen3-coder:480b | 290GB | 256K | — | 多卡服务器、NAS 集群 |
| qwen2.5-coder:7b | 4.7GB | 32K | — | 8GB 内存老机器 |
| qwen2.5-coder:14b | 9.0GB | 32K | — | 16GB 内存办公本 |
判断规则很简单:
- 显存 24GB 及以上(例如 RTX 4090、RTX 3090),直接上
qwen3-coder:30b,这是本文主推配置。 - 内存 20GB 左右的老机器,先用
qwen2.5-coder:7b,4.7GB 显存、32K 上下文足够覆盖单文件级别的补全和重构。qwen2.5-coder 系列在 Ollama 上的累计下载量已超过 2380 万次,社区排错资料最丰富。 - 16GB 内存的办公本,用
qwen2.5-coder:14b,9.0GB 占用仍有余量。 - 多卡服务器或 NAS 集群才考虑 480B,单机桌面场景不现实。
苹果平台另有一条路径。MLX 框架在 2026 年 11 月 9 日的版本中已对 Apple Silicon 做了推理优化,Qwen3-Coder 在 M 系列统一内存上的占用可压到约 27GB,相比通用路径有明显下降。这意味着 32GB 统一内存的 Mac 可以跑起 30B 版本,不必依赖 NVIDIA 显卡。
需要强调的是:显存占用和上下文长度是两个独立约束。30B 版本标称 256K 上下文,但实际能稳定用满多少,取决于推理框架的 KV Cache 实现、批处理策略和并发规模。选型时按显存先卡住,再实测长上下文表现,不要反过来用标称参数去推硬件。
四、五步落地流程
第一步:安装 Ollama
macOS 与 Linux 用官方脚本:
curl -fsSL [https://ollama.com/install.sh](https://ollama.com/install.sh) | shmacOS 也可以用 Homebrew:
brew install ollama安装完成后启动服务:
ollama serve验证服务是否正常:
curl [http://127.0.0.1:11434/api/tags](http://127.0.0.1:11434/api/tags)返回 JSON 列表即表示运行时已就绪。如果这一步失败,后面所有环节都不必继续,先解决端口监听问题。
第二步:拉取模型
# 主力模型,30B,显存 19GB
ollama pull qwen3-coder:30b
# 老机器备选 7B
ollama pull qwen2.5-coder:7b
# 办公本备选 14B
ollama pull qwen2.5-coder:14b拉取完成后做一次冒烟测试:
ollama run qwen3-coder:30b "用 Python 写一个每秒打印一次 Hello World 的脚本"能正常返回代码,说明模型加载、显存分配、推理链路三项全部通过。这一步比在 OpenCode 里试要快得多,出错时定位也更直接。
第三步:安装 OpenCode
三种安装方式按平台选择:
# 通用脚本
curl -fsSL [https://opencode.ai/install](https://opencode.ai/install) | bash
# npm
npm i -g opencode-ai@latest
# Homebrew
brew install sst/tap/opencodeß验证:
opencode --version第四步:配置本地模型
OpenCode 会自动发现本地运行的 Ollama 实例,但项目级配置需要显式声明模型标识。在项目根目录创建 opencode.jsonc:
{
"$schema": "[https://opencode.ai/config.json](https://opencode.ai/config.json)",
"model": "ollama/qwen3-coder:30b"
}模型 ID 的格式规则是 ollama/<模型名>:<标签>。几个常见写法:
// 7B 版本
"model": "ollama/qwen2.5-coder:7b"
// 14B 版本
"model": "ollama/qwen2.5-coder:14b"如果 Ollama 不在默认地址,或者跑在远程机器上,需要补充 provider 配置:
{
"$schema": "[https://opencode.ai/config.json](https://opencode.ai/config.json)",
"model": "ollama/qwen3-coder:30b",
"provider": {
"ollama": {
"options": {
"baseURL": "[http://192.168.1.100:11434/v1](http://192.168.1.100:11434/v1)"
}
}
}
}本机默认监听地址不需要写 apiKey,Ollama 侧不做鉴权。
第五步:在项目里跑起来
进入项目目录直接启动:
cd /your-project
opencodeOpenCode 会读取当前目录的 opencode.jsonc,把请求路由到本地 Ollama。
如果只想跑一次性的代码任务,不改配置文件:
opencode run --model ollama/qwen3-coder:30b --agent build "帮我写一个分页查询工具函数 paginate_users"这条命令适合验证链路是否打通,也适合集成到 CI 里做离线代码生成。
五、几个容易踩的细节
OpenCode 显示无法连接模型,但 `ollama serve` 明明在跑。 先确认端口:curl [http://127.0.0.1:11434/api/tags](http://127.0.0.1:11434/api/tags)。返回空白或报错,说明服务实际没有监听。macOS 上如果任务栏里有 Ollama 应用图标,它可能已经在后台接管了服务生命周期,手动再起一个 ollama serve 反而会冲突。
`qwen3-coder:30b` 下载很慢。 Ollama 的权重缓存目录在 ~/.ollama/models(Linux 下为 /root/.ollama/models),权限受限时可改 OLLAMA_MODELS 环境变量指向其他路径。下载支持断点续传,中断后重新执行 ollama pull 会从断点继续,不会重头开始。国内网络环境下,如果长时间停滞,先确认 Hugging Face 侧镜像是否可达,再考虑配置代理。
30B 跑起来了,但上下文一长就卡。 这是显存被 KV Cache 吃满的典型表现。降低并发数、缩短单次输入、或者改用更激进的量化版本都能缓解。不要指望标称的 256K 在 24GB 卡上全量可用。
六、本地与云端的成本边界
这套方案的经济性有明确适用范围,越过边界后反而不划算。
本地模型够用的任务: 单文件函数补全、单元测试改写、命名与格式规范化、小范围 bugfix、文档注释生成。30B 版本在这些任务上与云端旗舰模型的差距不明显,而边际成本为零。
建议切换云端的任务: 跨仓库的多步重构、需要长链条推理的复杂缺陷定位、依赖大规模检索的任务拆解、以及输出质量直接关联商业结果的高价值代码。这类任务上模型能力差距会明显拉开,本地模型额外消耗的时间和返工次数,比 token 费用更贵。
一条实用的判断规则:如果本地模型已经稳定承接了约 80% 的日常任务,剩下的 20% 就应该接云端 API,而不是继续加硬件。此时工程上的重点是让本地与云端共用一套调用抽象,避免切换时改动业务代码。koalaapi 作为 API 网关,可以统一管理多家模型的接入与路由,让本地 Ollama 与云端模型在同一条调用链上共存,按任务类型分流而不必重写客户端。
七、结语
这套组合的核心价值不在"免费",而在"可控"。硬件是可预期的固定投入,模型是可替换的模块,数据不出本机。三件事叠在一起,才让本地部署从实验性方案变成可长期运行的工程选择。
选型上按显存卡第一道门槛:24GB 以上直接上 qwen3-coder:30b,20GB 以下从 qwen2.5-coder:7b 起步。配置上守住一个原则:模型标识集中在 opencode.jsonc 里维护,不要散落在命令行和历史脚本中。这样换模型时只改一行,验证链路时也只改一行。
对多数个人开发者和小团队,这套本地栈足以覆盖日常编程任务的绝大部分。真正需要云端算力的场景,用网关做按需分流,比一次性堆满本地硬件更务实。

