开源 AI 编程助手搭建指南：OpenCode 配 Ollama 本地模型

开源终端编程助手 OpenCode 于 2026 年 10 月 11 日发布 1.19.0 版本，把自动更新改为需显式执行 /update 命令，并规定升级到 OpenCode 2 只能通过 opencode upgrade --major。这一改动让此前依赖自动更新的安装与旧教程描述不再一致。

一份搭建指南给出 12 个步骤、约 60 分钟的方案：由 Ollama 在本机运行 Qwen3-Coder 30B 模型，OpenCode 在终端调用该模型，同时预留一个自带密钥的云端模型作为困难任务的后备，最终得到一个可运行、带权限策略与测试的项目。

为何选择本地优先

Stack Overflow 在 2025 年 4 月对开源 AI 的分析中给出一个数字：61% 的受访开发者信任开源 AI 用于开发工作，而信任专有 AI 的比例为 47%。这一差距被用来说明，接受任意模型的终端代理为何比单一厂商助手增长更快。同一机构 2025 年的开发者调查还显示，在构建 AI 代理的开发者中，51% 使用 Ollama 这类常用于本地运行模型的开源工具。两项数据均来自 2025 年，属于基线而非最新读数。

OpenCode 官网的表述是：该工具 100% 免费使用，并自带一组免费模型，连接其他提供商可能产生额外费用。也就是说客户端本身不收费，付费的是背后的模型。本地优先的设计正是把日常的编辑、测试运行和重构交给本机 GPU 上的模型，只让需要前沿模型的任务走按量计费的 API。

隐私是第二个理由。本地模型不会把源代码发送到任何地方，这对客户仓库、受监管环境和受保密协议约束的项目都有意义。需要留意的是，OpenCode 自带的免费模型运行在其托管服务上，使用方便但并不在本地；若要求严格的纯本地策略，需要显式选择自己的 Ollama 模型并避开这些默认项。

托管侧的价格压力也让混合方案更可行。OpenAI 于 2026 年 10 月 21 日推出 GPT-6 Sol 与 GPT-6 Luna，Google 的 Gemini 4 Argon 于 10 月 13 日全面可用并采用 introductory rate。便宜的备用模型使“本地优先、卡住再上云”的流程对多数独立开发者而言负担得起。

三件套如何分工

整套方案由三部分组成，各司其职。Ollama 负责运行模型，并在本机暴露一个兼容 OpenAI 的 HTTP 端点；OpenCode 是代理，负责读取文件、提出修改、执行 shell 命令，并与所配置的端点通信；托管提供商是可选项，藏在一个从不写入配置文件的 API 密钥之后。

OpenCode 的文档列出其支持 75 家以上提供商，以及任何使用兼容 OpenAI 协议的服务器。这一协议是粘合剂：Ollama、LM Studio、llama.cpp 等服务器都暴露相同的 /v1 路由，因此更换底层引擎无需改变代理的行为方式。Aider、Cline、Goose 和 Kilo Code 等其他开源代理也能读取同样的端点，从而避免被单一前端锁定。

版本沿革对固定版本的安装很关键。1.19.0 增加了通往 OpenCode 2 的升级路径，并把更新移到终端界面中的 /update 命令；1.19.1 停止会话共享；1.19.2 让 1.x 线保持在 1.x 构建上；1.19.3 增加了由模型推理选项生成的推理变体；2026 年 10 月 22 日列出的 1.19.4 把内置 Bun 运行时升级到 1.4.4，包含覆盖 Brotli、TLS、HTTP/1.1、HTTP/2、HTTP/3、WebSocket 和 fetch 的安全修复。

第三方追踪站点描述了带共享后台服务、代码模式和后台子代理的 OpenCode 2 线，但其确切版本号的说法相互冲突，官方 1.x 发布页仍把 v1.19.4 标为最新的 1.x 构建。因此指南以有文档且稳定的 1.x 线为目标，并在末尾演示如何在单独副本中安全评估版本 2。Claude Code、Codex CLI 与 OpenCode 之间四天一更新的节奏也提醒，固定版本比追逐版本更能让可用配置保持可用。

版本与硬件前提

指南列出开工前需要备齐的组件，版本以 2026 年 10 月 22 日为准，标注为预发布的版本应避开。Ollama 使用 v0.40.8，这是 10 月 21 日的最新稳定版，v0.40.9 仅为预发布；OpenCode 使用 1.19.x 线，v1.19.4 被列为最新 1.x，内置 Bun 1.4.4，因此无需单独安装 Node 或 Bun；本地模型为经 Ollama 运行的 Qwen3-Coder 30B，Ollama 已更新其工具调用以提升速度与可靠性。

其余前提包括：任意较新的 Git 2.x 版本，用于审阅和回退代理的修改；Python 3.12 或更新版本，用于示例项目和 pytest；操作系统为 Linux、macOS（Apple Silicon）或带 WSL 的 Windows，命令以 POSIX shell 书写；托管 API 密钥为可选项，来自 Anthropic、OpenAI 或 Google 账户，仅用于第 7 步的云端后备。

硬件方面，4 位量化的 30B 级编程模型大约需要 20 GB 空闲 GPU 显存或统一内存，提高上下文窗口后需求更多。24 GB 的 NVIDIA 显卡或 32 GB 以上内存的 Apple Silicon Mac 可以胜任。机器较小时，可从 Ollama 模型库选择更小的编程模型，但多文件编辑能力会相应减弱；步骤本身不变，只是模型名不同。此外还需约 25 GB 空闲磁盘空间存放模型文件、一个顺手的终端，以及一小时不被打断的时间。若计划使用托管后备，应为该工具单独创建一个 API 密钥。

本地模型的部署步骤

第一阶段共三步。第一步安装 Ollama 并确认版本：Linux 上使用官方安装脚本最省事，macOS 和 Windows 使用 ollama.com 的桌面安装包；安装后确认版本并检查后台服务是否响应。预期输出接近 ollama version is 0.40.8 以及 {"version":"0.40.8"}。若第二条命令没有输出，说明服务未运行：Linux 上可用 systemctl status ollama 查看原因，macOS 上打开一次 Ollama 应用即可启动菜单栏服务。Ollama 已从本地运行器发展为带付费云层的混合平台，安装程序可能提示登录，跳过即可，本指南不需要 Ollama 账户。

第二步拉取支持工具调用的编程模型。代理需要模型能够发出“读取此文件”“运行此命令”这类结构化请求，而不只是聊天。Qwen3-Coder 30B 是合适的默认选择，因为 Ollama 更新了其工具调用以提升速度与可靠性。执行 ollama pull qwen3-coder:30b 后用 ollama list 确认。下载体积较大，可以先启动再继续阅读。基础跑通后还有两个较新的开源模型值得关注：Ollama 列出的 NVIDIA Nemotron 3.5 Lightning 是 300 亿参数、30 亿激活参数、面向持续运行并调用工具的代理；v0.40.8 发布说明据称还加入了 Recursive 的 Apache-2.0 许可 Flint 编程模型，具备推理与多轮工具使用能力。Flint 的细节在核对模型页面前应视为未确认，任何候选模型都应在自己的仓库上基准测试后再切换。

第三步用 Modelfile 提高上下文窗口。编程代理每次请求都会塞入大量内容：系统提示、规则、文件内容、工具结果和历史。默认上下文过小会让模型悄悄忘记先前的轮次，看起来像变笨，实际是截断。做法是创建一个派生模型：建立工作目录，写入包含 FROM qwen3-coder:30b 与 PARAMETER num_ctx 32768 的 Modelfile，执行 ollama create qwen3-coder-32k -f Modelfile，再用 ollama run qwen3-coder-32k 让它回复单个词 ready 以验证。更大的窗口占用更多内存，模型加载期间应观察 ollama ps；若处理器一列显示 CPU 占比，说明模型已溢出 GPU 显存，生成会变得很慢，此时应把 num_ctx 降到 16384 或更小。

权限与云端后备

指南的最终产物是一个可工作的仓库，包含固定版本的 OpenCode 1.x 安装、本地提供商配置、收紧的权限策略、项目规则、一个审阅子代理、两个包装脚本，以及一套由助手自己扩展并通过的测试。所有文件都完整列出，可以照原样复制项目。

云端后备以自带密钥的方式接入，密钥不写入配置文件，只在需要时通过一个词的切换启用，用于困难任务。指南建议为这个工具单独申请密钥，并在安全章节说明原因。托管模型只是可选项，本地模型承担日常任务，前沿模型只在必要时按量计费。

关于版本 2，指南建议在单独副本中安全评估，而不是直接替换现有安装。第三方对 OpenCode 2 的描述包括共享后台服务、代码模式和后台子代理，但版本号说法不一，官方 1.x 页面仍以 v1.19.4 为最新。对希望稳定使用的读者，固定 1.x 线是当前更稳妥的选择。

要点

OpenCode 1.19.0 于 2026 年 10 月 11 日发布，更新改为手动 /update
升级至 OpenCode 2 仅能通过 opencode upgrade --major
指南共 12 步、约需 60 分钟
本地模型选用 Qwen3-Coder 30B，由 Ollama 提供
30B 模型 4 位量化约需 20GB 显存或统一内存