在 OpenCode 里接上本地模型：让代码助手真正留在自己电脑里

写代码时，很多人已经习惯了有个 AI 助手帮忙查文档、改 bug、补测试。大多数时候，这些助手跑在云端：你的代码片段被送出去，结果再返回来。方便是方便，但偶尔会让人犹豫——公司代码能不能往外传？网络不稳定时怎么办？调用量大了账单会不会突然跳一下？

OpenCode 是近几年比较受关注的开源 AI 编程助手。它主要跑在终端里，也能配合桌面或 IDE 使用，能读项目、改文件、执行命令，而且不绑定某一家模型。你既可以接 Claude、GPT 这类云端服务，也可以把本地跑起来的模型直接接进去。后一种方式，让“数据不出本机”这件事变得现实起来。

这篇文章就聊聊，怎么在 OpenCode 里接入本地模型，以及实际用的时候要注意什么。目标是让第一次接触的人也能跟着做一遍，同时把常见坑提前说清楚。

为什么要折腾本地模型

先说清楚动机。本地模型不是为了炫技，而是解决几个很具体的问题。

隐私是最直接的一条。代码、注释、甚至提交信息里，有时会夹带内部接口、业务逻辑或密钥痕迹。走云端接口，理论上服务商会声明不训练、不留存，但政策会变，合规要求也会变。本地跑的话，请求根本不离开你的机器，心理上更踏实，也更容易满足内网或涉密场景的要求。

成本是第二条。云端按 token 计费，Agent 模式会反复读文件、试改、再验证，一轮下来消耗不小。本地模型没有按量账单，适合长时间试验、批量处理，或者只是想随手问几句而不用盯着用量。

还有离线和可控。出差、内网环境、或者只是想少依赖外部服务时，本地方案更稳。你也能自己决定用哪一版模型、量化到什么程度、上下文开多大，出了问题可以自己排查，而不用等服务商恢复。

当然，本地不是万能的。模型能力受硬件限制，推理速度和效果通常不如顶尖的云端大模型。工具调用、长上下文、复杂推理，都对模型和机器有要求。把预期放在“够用、可控、省心”上，会更实际。很多人最终的选择是混合使用：日常简单任务走本地，真正棘手的问题再切回云端。

OpenCode 怎么认识本地模型

OpenCode 本身不负责跑模型，它只是个客户端。它通过标准的 OpenAI 兼容接口跟模型说话。只要你的本地服务暴露了类似 http://localhost:xxxx/v1 的地址，并且支持聊天和工具调用，OpenCode 就能接上。

这种设计的好处是灵活。换模型、换运行时，大多只需要改配置，而不用换整个助手。常见的本地运行时有这几类：

• Ollama：安装简单，拉模型方便，社区模型多，适合入门和日常使用。
• LM Studio：带图形界面，方便下载、加载和管理模型，默认端口 1234，对不太想碰命令行的人更友好。
• llama.cpp 的 server、vLLM 等：更偏性能或大规模部署，配置稍复杂，适合已经有现成服务的人。

对大多数人来说，从 Ollama 开始最省事。后面也会简单提到其他方案。

先把基础环境准备好

安装 OpenCode

官方提供了几种方式。最常见的是一键脚本：

curl -fsSL https://opencode.ai/install | bash

也可以用 npm（需要 Node.js 18 及以上）：

npm install -g opencode-ai

macOS 用户还能用 Homebrew。装完后在终端敲 opencode --version，能输出版本号就说明就绪了。建议在项目目录里启动，这样它更容易理解当前代码库的结构。

安装并启动 Ollama

去 Ollama 官网按系统下载安装，或者用对应的包管理器。装好后，它一般会在后台监听 http://localhost:11434。可以用 ollama --version 确认是否安装成功。

接下来拉一个适合写代码的模型。OpenCode 对上下文长度有一定要求（常见建议是 64k 起步），所以别只图小。可以试试：

ollama pull qwen2.5-coder:14b
# 机器更好的话可以上更大的
ollama pull qwen2.5-coder:32b

机器内存和显存够的话，优先选参数量更大、专门优化过代码的版本。拉完后用 ollama list 确认一下。如果只是想先跑通流程，也可以先用小一点的模型测试连通性，再换正式用的。

保持 Ollama 在运行状态（有些系统安装后会自动常驻），然后就可以配置 OpenCode 了。

配置文件怎么写

OpenCode 的配置通常放在用户目录下：

~/.config/opencode/opencode.json

如果没有这个目录或文件，可以自己创建。一个最基础、能用的本地配置大概是这样：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "本地 Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:14b": {
          "name": "Qwen2.5 Coder 14B"
        },
        "qwen2.5-coder:32b": {
          "name": "Qwen2.5 Coder 32B"
        }
      }
    }
  },
  "model": "ollama/qwen2.5-coder:14b"
}

几点说明：

• npm 字段指向 OpenAI 兼容的适配器，这是接本地服务的标准做法。
• baseURL 必须带 /v1，这是接口约定，漏掉很容易连不上。
• models 里的 key 要和 Ollama 里实际的模型名对得上，name 则是在界面上显示的名字，可以自己起得友好一点。
• 最外层的 model 可以设一个默认值，格式是 提供商ID/模型ID。

保存后，重新启动 OpenCode。进入界面后输入 /models，应该能看到刚才配置的本地模型。选中它，就可以开始对话了。

有些版本或插件支持自动发现本地模型，不必手动一条条写。如果觉得维护列表麻烦，可以留意社区提供的 Ollama 自动识别插件，装上后在配置里加上对应字段，重启即可扫描已下载的模型。对于经常换模型的人，自动发现会省事不少。

其他常见本地方案

LM Studio

LM Studio 界面友好，适合不太想碰命令行的人。启动本地服务器后，默认地址一般是 http://127.0.0.1:1234/v1。配置方式和 Ollama 几乎一样，只是把 baseURL 改成对应端口，模型名改成 LM Studio 里当前加载的那个。记得在 LM Studio 里打开 Local Server，并确认端口没有被占用。

llama.cpp / vLLM

如果你已经在用这些服务，同样写一个 provider，把 baseURL 指过去就行。关键是确认服务开启了 OpenAI 兼容的聊天接口，并且支持 tool calling——OpenCode 作为 Agent 会频繁用到工具（读文件、改文件、跑命令），模型如果完全不会调用工具，体验会大打折扣，经常停在“我建议你……”而不是直接动手。

一键启动

Ollama 较新的版本提供了 ollama launch opencode 这类命令，能交互式选模型并临时拉起 OpenCode。适合快速试用，但长期使用还是建议把配置写进 opencode.json，方便固定默认模型、切换和复用。临时启动不会覆盖你已有的全局配置，两者可以并存。

实际用起来会碰到的事

模型选得对不对，比配置本身更影响体验。纯聊天模型有时写代码还行，但作为 Agent 时容易在工具调用上卡壳，或者上下文一长就忘事。优先选带“coder”“code”字样、或者明确支持 function calling 的版本。参数量太小（比如 3B、7B）在复杂项目里容易力不从心，14B、32B 会稳妥一些，当然也更吃内存和显存。

速度是另一件事。本地推理受硬件限制明显。有独立显卡、内存充足时，响应会快很多；纯 CPU 跑大模型，等待时间会让人失去耐心。可以先用量化版本（Q4、Q5 等）平衡速度和质量。不同模型量化后的表现差异不小，值得自己试几轮。

上下文窗口也要留意。OpenCode 处理整个项目时，会把不少文件内容塞进上下文。窗口太小，模型容易“忘”了前面的约定或已经改过的地方。配置里有时可以单独限制 context 和 output 的上限，根据机器情况调整。窗口开太大，内存占用和速度又会受影响，需要折中。

权限方面，OpenCode 能读文件、写文件、跑命令。本地模型虽然不出网，但工具权限仍然存在。刚开始用时，建议把自动执行级别设得保守一点，重要操作先确认再放行。熟悉之后再逐步放开，能减少误操作带来的麻烦。

如果模型列表里看不到本地项，先检查几件事：Ollama 是否在跑、端口是否对、配置文件路径是否正确、JSON 有没有语法错误、baseURL 末尾的 /v1 有没有漏。有时改完配置需要完全退出再重新启动 OpenCode。也可以先用 curl 测一下本地接口是否正常返回，排除服务本身的问题。

什么时候值得用本地，什么时候还是云端更合适

本地方案特别适合这些场景：代码敏感、需要离线、调用量很大想控制成本、或者只是想把工具链完全掌握在自己手里。内网开发、开源贡献前的自测、长时间重构试验，都是比较典型的用法。

如果任务对模型能力要求很高——比如复杂架构重构、跨多文件深度推理、需要最新知识或很强的通用理解——云端大模型目前仍然更强。很多人的做法是两者结合：日常补全、简单修改、解释代码用本地，真正棘手的问题再切到云端。OpenCode 支持多提供商，在界面里切换并不麻烦。

也有人把本地模型放在另一台有显卡的机器上，通过内网或隧道访问。配置时把 baseURL 改成那台机器的地址即可，原理一样。注意防火墙和网络延迟，否则 Agent 来回调用工具时会明显变慢。

写在最后

把 OpenCode 接上本地模型，本质上是把“模型服务”和“编程助手前端”拆开。前端负责理解项目、调度工具、呈现结果；后端负责推理。这种拆分让你可以自由选择信任的模型来源，而不必把整个工作流绑在某一家云上。

配置过程其实不复杂，真正花时间的是选模型和摸清自己机器的极限。第一次可能要试几个不同大小的模型，才能找到速度和效果的平衡点。一旦跑通，以后换模型或换运行时，大多只是改配置文件里的几行。

技术在变，工具也在变。能把关键环节留在自己可控的范围内，本身就是一种安全感。如果你也在意代码隐私，或者只是想少为账单操心，不妨抽半小时把本地链路搭起来试试。跑通之后，那种“助手就在自己电脑里”的感觉，和纯云端还是不太一样的。不必追求一次就完美，先让它动起来，再慢慢调到顺手，往往是更轻松的路径。

很多开发者在用了一段时间后会发现，本地模型最适合做“高频、低风险”的事：解释一段看不懂的代码、生成简单的测试用例、重命名和整理小范围逻辑。这些任务对模型能力要求没那么极端，却能实实在在省下查文档和手工修改的时间。等到需要大范围架构调整或跨模块推理时，再临时切回更强的云端模型，往往是更务实的组合。

另外，本地环境也方便做实验。你可以换不同量化级别、不同提示风格，观察 Agent 的行为变化，而不用担心每次试验都产生额外费用。这种低成本试错，对理解和调教工具很有帮助。