1. 先想明白一件事本地模型跑opencode到底图什么如果你已经在用 opencode或者刚听说过这个名字——一个跑在终端里的 AI 编程助手能读项目、改代码、执行命令——那迟早会面对一个问题模型从哪来直接接云端模型 key 确实最快响应质量也最高但用久了总会遇到几件让人想换条路的事公司代码不能出内网、随手一个小改动也要走 token 计费、出差路上断网、或者单纯想研究一下本地推理的完整链路。于是“opencode 配置本地模型”就成了很多人搜的第一个关键词。先说结论免得你配置完产生落差本地模型不会吊打云端旗舰模型。尤其在多步骤工具调用、长上下文推理、跨文件大规模重构这些环节差距是客观存在的。但本地路线的优势也同样直接——代码不出本机、不用为每次试探性提问付钱、断网照常干活、模型想换就换。这篇文章就按我实际配置的顺序来写装好 opencode 和本地推理服务、写好配置文件、选对模型、跑一个真实任务、最后把常见坑一次性列清楚。不管你是 8G 内存的老笔记本还是有多卡服务器都能拿到一份可以直接照着做的方案。顺便说一句opencode 不是那种“在终端里聊天”的花架子。它的核心玩法是让模型直接操作项目文件、调用命令行工具、在真实环境里完成修改。所以它对本地模型的要求比“本地聊天机器人”要高不少。这也是为什么很多人在第一步就摔跟头本地模型能聊天不代表它能被 opencode 正常调度。下面我一个个环节拆开讲。2. 底座先打好装opencode、起一个本地推理服务、验证连通2.1 安装 opencode 本身opencode 的安装门槛很低。它本质上是跑在 Node.js 环境里的命令行工具所以第一步是确认机器上有 Node.js 20 以上的版本。装好了之后用 npm 全局安装就可以npm install -g opencode-ai如果你不喜欢 npm 全局包也可以直接在终端执行官方脚本安装macOS 和 Linux 都支持。装完以后在任意目录敲opencode --help能看到子命令和参数说明就说明装好了。这里我给个建议装完别急着配模型先跑一次opencode看看交互界面能不能正常起来。因为后面所有排查都会依赖你对“正常状态”的判断。2.2 选一个本地推理服务我推荐 Ollama本地模型推理方案目前主流有三类我放在一起对比一下方案安装复杂度默认端口接口风格适合谁Ollama低11434/v1/chat/completions绝大多数个人开发者CPU/GPU/统一内存都能跑图形界面类工具低1234/v1/chat/completions喜欢手动加载、可视化查看模型的人vLLM高8000/v1/chat/completions多卡服务器、高并发、要极致吞吐的场景我个人首选 Ollama。原因很务实它开箱即有 OpenAI 兼容接口opencode 不需要额外适配模型量化托管得好拉下来就能跑内存管理比很多自折腾方案省心。你用图形界面类工具也行核心思路完全一样——只要它暴露了一个 HTTP 接口且格式是标准的 /v1 风格opencode 这边配置逻辑就不会变。装 Ollama 也简单# macOS / Linux curl -fsSL https://ollama.com/install.sh | sh # Windows 用户直接去官网下安装包装完以后拉一个模型下来。我建议第一课先用 qwen2.5-coder:7b尺寸适中、工具调用能力强、对新手最友好ollama pull qwen2.5-coder:7b ollama run qwen2.5-coder:7b能正常对话说明推理服务本身没问题。这一步千万别跳过。很多人后面配置文件写好了opencode 却提示连不上结果回头一查Ollama 压根没在跑。2.3 在正式接 opencode 之前先用 curl 验证接口这是我最想强调的一步。Ollama 自己跑得好和它的 HTTP 接口能被外部访问是两件事。强烈建议先用 curl 打一下接口curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-coder:7b, messages: [{role: user, content: 用一句话介绍你自己}], stream: false }如果返回了一段 JSON里面带着choices字段那恭喜你底座的最后一块砖也铺好了。这里有个细节地址里我写的是127.0.0.1不是localhost。因为在某些机器上localhost会优先解析成 IPv6 的::1而 Ollama 默认只监听 IPv4 的127.0.0.1一不留神就出现“明明服务开着可就是连不上”的诡异问题。这个习惯后面写配置文件也一样。3. 关键一步opencode配置文件怎么“认识”本地模型3.1 配置文件放哪里opencode 的配置文件名是opencode.json常见位置有两个用户级全局配置在~/.config/opencode/opencode.json项目级配置可以放在项目目录下。不同版本对位置的识别略有差异最稳的办法是敲opencode --help看当前版本提示或者直接用用户级配置路径因为它是全局生效的调试起来最简单。我刚开始配置时犯过一个低级错误把 JSON 文件放在了项目目录结果发现换一个项目就不生效。后来统一放用户级再在项目里用 AGENTS.md后面会讲做差异化控制思路就清爽了。3.2 用 OpenAI 兼容协议把 Ollama 接进来opencode 内置了一套模型注册机制云端常见的模型它天然认识。但本地模型不在内置列表里需要我们自己定义 provider。核心就是用ai-sdk/openai-compatible这个包把 Ollama 包装成一个“长得很像云端模型服务”的接口。下面是我实际在用的最小配置{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama, options: { baseURL: http://127.0.0.1:11434/v1, apiKey: ollama }, models: { qwen2.5-coder:7b: { name: Qwen2.5 Coder 7B }, qwen2.5-coder:14b: { name: Qwen2.5 Coder 14B } } } } }逐个解释一下字段。provider下面那个ollama是我们自定义的名字你可以改成local、mybox都行但注意后面/models里显示的前缀会跟着变。npm指向的是 opencode 用来发请求的适配包ai-sdk/openai-compatible就是专门对接这种兼容接口的。baseURL必须带/v1因为 opencode 走的是标准 /v1 路径apiKey其实 Ollama 不校验但很多库要求这个字段不能为空随便填个占位符就行这里填了ollama。models下面的 key必须和 Ollama 里ollama list显示的模型 ID 完全一致。这也是最容易写错的地方模型 tag 差一个冒号、少一个后缀opencode 报错时往往不会提醒你“模型名不对”而是给一个含糊的请求失败。所以写完配置第一件事是ollama list对照一遍。3.3 怎么确认 opencode 真的认出了本地模型配置写好后进入项目目录跑opencode。进入交互界面后输入/models就能看到所有可用模型。如果配置正常你会看到一个带前缀的条目比如ollama/qwen2.5-coder:7b。选中它当前会话就会切换到这个模型。如果你更喜欢命令行参数也可以这样opencode --provider ollama --model qwen2.5-coder:7b不同版本的参数名可能略有差异拿不准就回到交互界面用/models选择。这里我多说一句opencode 的交互界面里模型切换是会话级的也就是说你这次选了 7B下次打开默认不一定还是 7B。所以初学阶段别急着研究“怎么设置默认模型”先用/models手动切等思路顺了再折腾默认值。4. 模型不能只看显存量化、上下文窗口与任务匹配4.1 先算一笔账模型量化体积只是“入场券”很多人选本地模型的时候只盯着“这个模型多少 GB我的内存够不够”。这只是一个起步条件。真正决定你能不能流畅用的是两个隐藏项量化方式和上下文窗口。现在的开源模型普遍用 4bit 量化部署最常用的是 Q4_K_M体积和效果平衡得比较好。量化体积大约可以这样估算模型 ID参数量量化后体积约推荐运行内存工具调用能力qwen2.5-coder:7b7.6B4.7GB8GB 起步好qwen2.5-coder:14b14.8B9GB16GB 起步好qwen2.5-coder:32b32.8B20GB32GB 起步较好llama3.1:8b8B4.9GB8GB 起步一般glm4:9b9B约6.3GB12GB 起步较好中文友好注意上表只是权重体积。模型跑起来之后上下文长度还会额外吃内存。KV cache 的开销和模型架构、上下文长度直接相关。简单感受一下在 7B 模型上把上下文从 4K 拉到 32K可能额外多占用 1~2GB 内存在 32B 模型上拉 32K 上下文额外占用可以达到 8GB 以上。所以“32G 内存跑 32B 模型”听着很行实际一开大上下文照样可能内存溢出。4.2 分梯队选模型别一上来就上最大号我的建议是分梯队第一梯队用来跑通链路qwen2.5-coder:7b。它体积小、工具调用格式遵循得比较好单次请求速度快。你拿它验证 opencode 的读文件、改代码、跑命令整条链路是最划算的。第二梯队日常主力qwen2.5-coder:14b。它的代码理解和多步骤执行比 7B 明显强一截对 16G 内存的机器来说是性价比很高的选择。第三梯队复杂重构qwen2.5-coder:32b。适合那种“一个改动影响七八个文件”的任务但速度慢、内存开销大要耐心等。如果你主攻中文项目glm4:9b 也值得试中文表达更自然工具调用能力也够用。但如果你是做代码任务我还是首推 Qwen2.5-Coder 系列因为它在代码生成、代码理解、工具调用这几个维度的综合表现明显更适合 opencode 这种“要干活”的场景。4.3 上下文到底开多大取决于任务而不是虚荣心Ollama 的老版本默认上下文窗口很小只有 2048 token。这个长度在 opencode 里几乎寸步难行——模型读两个文件就把前面的对话忘了。现在的版本默认值有所提升但你最好还是显式设置一下。我的经验日常小改动16K 上下文足够处理跨文件任务尽量给 32K不是特别必要别上 64K/128K因为上下文翻倍内存占用和首次响应延迟都会肉眼可见地变差。设置方法很简单Linux 上通过 systemd 配置 Ollama 服务sudo systemctl edit ollama在这个文件里加[Service] EnvironmentOLLAMA_CONTEXT_LENGTH16384 EnvironmentOLLAMA_KEEP_ALIVE30m EnvironmentOLLAMA_NUM_PARALLEL2然后sudo systemctl daemon-reload sudo systemctl restart ollamamacOS 上则用launchctl设置环境变量后重启 Ollama 应用launchctl setenv OLLAMA_CONTEXT_LENGTH 16384 launchctl setenv OLLAMA_KEEP_ALIVE 30m launchctl setenv OLLAMA_NUM_PARALLEL 2讲一下这几个变量的意思。OLLAMA_CONTEXT_LENGTH是上下文上限我建议按你实际内存来。OLLAMA_KEEP_ALIVE是模型在内存里常驻的时间设成30m可以避免每次请求都要重新加载模型——如果不设每次对话间隔一长就要冷启动opencode 那边看起来就是“怎么半天没反应”。OLLAMA_NUM_PARALLEL是并行处理的请求数opencode 有时会同时发起几个模型请求设成 2 体验更顺但注意不要设太大否则内存会叠加。5. 从“能聊天”到“会干活”一次完整的本地模型实测5.1 用一个小项目跑通全链路配置完成后别急着拿生产项目试水。先找个干净的小项目我的做法是本地建一个只有两三个文件的 Python 小项目故意写了一个parse_config函数里面没有空值校验。然后给 opencode 下指令读取 src/utils.py 里的 parse_config补上空值校验让传入空路径时返回默认配置然后运行 python -m pytest你会看到 opencode 的完整工作链路先调用 read 工具读文件然后对修改方案做说明再调用写文件的工具做修改最后在终端里跑测试。整个流程里模型不再只是“输出代码给你看”而是真的动手改项目。这一步跑通说明你的本地模型配置在功能上是完整的。但这里我要泼一盆冷水即使链路通了7B 模型在多步骤任务里依旧会犯“说空话”的毛病。它可能给出思路却不实际调用任何工具也可能嘴上说“已修改”实际文件根本没变。这不是配置错了而是小模型的工具调用稳定性就这样。遇到这种情况咬咬牙换个 14B 模型或者把任务拆小一点指令里明确说“请直接修改文件不要只给出建议”效果会立竿见影。5.2 工具调用能力才是本地模型的天花板opencode 对模型的要求本质上是“结构化输出”能力——模型不仅要生成自然语言还要能按固定格式输出工具调用。这恰恰是很多本地模型最弱的地方。Qwen2.5-Coder 系列在工具调用上做得比较好而一些老一代代码模型聊天还行一进入工具调用环节就乱套。我实测下来的体感是同样一个“读文件-改代码-跑测试”的任务14B 模型能稳定地一步一步走完7B 模型偶尔会跳步或者重复执行。所以你在配本地模型时一定要先确认模型支持工具调用再决定要不要把它当作主力。判断方法很简单用 opencode 跑上面那个小任务反复做三次如果三次里有一次工具调用是干干净净、没废话、没错误格式的那这模型就值得长留。5.3 用 ollama ps 观察运行时状态在模型跑任务的过程中你可以另开一个终端窗口敲ollama ps这个命令会显示当前正在运行的模型、它占用的内存、以及请求是否在并发处理。这是个非常实用的体检工具。如果模型没有出现在列表里说明它根本没被加载那 opencode 这边的请求多半是打到空处了。6. 常见故障排查不是模型不行是链路某处断了6.1 连不上服务先分清是“没启动”还是“地址不对”opencode 报连接失败最常见的两个原因一是 Ollama 没在跑二是 baseURL 写错。排查顺序不要乱# 1. Ollama 在不在跑 ollama list # 2. 接口通不通 curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-coder:7b,messages:[{role:user,content:hi}],stream:false} # 3. 配置里的 baseURL 是不是 127.0.0.1 而不是 localhost我遇到过最隐蔽的问题是opencode 所在终端里设置了某个指向外部网络的环境变量结果本地 11434 的请求也被它接管导致连接变慢甚至失败。排查这种问题可以把那个外部网络环境变量临时清空再试一次往往立刻就好了。6.2 响应超慢先看模型体积再看上下文本地模型响应慢九成是硬件和配置问题不是 opencode 的锅。第一件事确认你选的模型和机器配置匹配7B 模型在 8G 内存机器上是能用的但你硬上 32B慢是必然的。第二件事看看上下文窗口是不是开太大了32K 上下文在 7B 模型上的首字延迟和 4K 完全不是一个量级。第三件事看看是否有大文件被塞进了上下文——opencode 会读取项目文件如果你的项目里有node_modules、构建产物、日志文件建议通过忽略规则把它们排除掉别让模型对着几千行压缩后的代码发呆。还有一个小技巧如果你发现 opencode 每次对话隔一会儿就要等半天多半是模型被卸载了重新加载要花十几秒。这时去确认OLLAMA_KEEP_ALIVE有没有设置没有就按上文的方法设成30m。6.3 上下文越聊越乱把上下文窗口当“显式资源”管很多新手的直观反应是“把上下文开大点模型不就记得住了吗”。方向没错但代价很大。在 opencode 这种工具型场景里上下文不仅包括你们聊的天还包括它读取的每个文件、每次工具执行的输出。一个 7B 模型在 16K 上下文里可能还应付得来一旦 32K、64K模型不仅变慢还容易“抓住旧信息不放”忽略你最新的指令。所以我的习惯是上下文够用就好一般设 16K 或 32K同时把任务拆小尽量让 opencode 的单次会话只解决一个小目标。如果任务实在太大我会在 AGENTS.md 里写“每步只处理一个模块改完确认再继续”让模型形成节奏感。6.4 模型只会说不会做多半是工具调用格式崩了这是本地模型最普遍的翻车方式。模型回了很长一段“我会这样改”就是不动手。原因通常是模型不支持工具调用或者输出格式不稳定。处理手段排序如下第一换模型。优先选明确支持工具调用的 instruct 版本Qwen2.5-Coder 系列、glm4 系列都可以。第二降低量化等级。q4 量化在某些模型上会明显影响结构化输出如果条件允许试试 q5_K_M 或者 q6_K稳定性能好不少。第三把指令写得更“实”。在提示词里明确“使用 read 工具读取文件后用 write 工具直接修改”比笼统地说“帮我改一下”有效得多。6.5 日志是最后的救命稻草如果上面所有手段都试了还是不行打开 opencode 的调试日志看看请求到底发送了什么、模型返回了什么。以你自己安装版本的--help输出为准通常会有--debug之类参数。日志里最值得关注的是模型原始返回内容——如果它返回了一段看起来很正常的文本但没有符合工具调用格式的结构那问题就锁定在模型层的工具调用能力上不是你的配置问题。7. 把本地模型用顺手值得长期投入的进阶配置7.1 AGENTS.md本地模型最听话的“说明书”opencode 原生支持项目级规则文件 AGENTS.md。这个文件会被当作系统提示词的一部分每当模型开始工作时它都会先读到这些规则。对本地小模型来说这个文件的价值比云端大模型更高因为它能弥补模型“听不懂隐含要求”的短板。我在实际项目里会放这样一份 AGENTS.md# 项目规则 - 先阅读相关文件确认改动影响范围再动手修改。 - 保持现有代码风格缩进使用 4 空格。 - 函数和变量命名使用英文注释可以用中文。 - 改完代码后运行 pytest确认全部通过。 - 如果某个操作有风险例如删除文件先向用户确认。你会发现规则写得越具体本地模型跑得越靠谱。尤其是“先读文件再改”“改完跑测试”这两条能显著减少模型瞎改、改完不验证的问题。7.2 多模型分流本地干小事云端干大事配置本地模型不等于要把云端 key 丢掉。我的长期方案是两套并存本地 Ollama 负责日常小改动、快速问答、离线工作云端大模型负责跨文件大规模重构、复杂架构讨论。在 opencode 的配置里本地 provider 已经写好了云端可以直接沿用内置注册的 provider也可以像我这样定义一个自定义兼容接口{ provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama, options: { baseURL: http://127.0.0.1:11434/v1, apiKey: ollama }, models: { qwen2.5-coder:7b: {} } }, cloud: { npm: ai-sdk/openai-compatible, name: 云端兼容服务, options: { baseURL: https://your-endpoint.example.com/v1, apiKey: 填入你的密钥 }, models: { some-large-model: {} } } } }实际使用时通过/models切换即可。我给自己的约定是单文件改动、生成单元测试、解释报错一律走本地 7B 或 14B重构涉及多个文件、需要全局设计判断才切到云端。这样做的好处是你那几个本地模型始终在常驻内存里不会因为偶尔用一次云端就把本地链路冷落了。7.3 Ollama 的常驻策略让模型“随叫随到”如果你使用频率高建议把OLLAMA_KEEP_ALIVE调大一点比如2h甚至24h。模型常驻内存会持续占用几个 GB换来的是每次请求都秒回。如果你的内存比较紧张那就回到我前面的建议同时只加载一个 7B 小模型7B 留给日常14B 等需要时再拉。另外在 Ollama 服务端可以通过OLLAMA_MAX_LOADED_MODELS限制同时加载的模型数量设成 1 可以避免几个模型挤爆内存。这不是 opencode 的配置但对本地模型体验的影响非常大值得花两分钟设好。7.4 后续扩展本地检索增强早晚用得上当本地模型逐渐成为你的主力工具后下一个瓶颈往往是“模型不知道你项目里写过什么”。你可以考虑在本地加一个 embedding 模型把项目代码向量化让 opencode 先生成检索结果再让模型作答。这个思路能弥补小模型上下文有限的短板但对个人项目来说优先级不算高。我个人的建议是先把基础链路跑稳把 AGENTS.md 写好把日常小任务迁移到本地等技术积累够了再考虑检索增强。最后分享一点个人体会。本地模型这件事最忌讳的就是“一步到位”。如果你只有 16G 内存的机器我的建议特别简单先拉 qwen2.5-coder:7b用它跑完三到五个真实的小任务确认 opencode 的读文件、改代码、跑命令整条链路都通了再考虑上 14B 还是 32B。链路不通之前上再大的模型也只会让你在“慢”和“乱”之间反复横跳。等链路通了你会发现本地模型虽然不如云端旗舰那么聪明但它那种“随叫随到、说改就改”的踏实感是云端服务给不了的。
