1. 为什么模型配置是 OpenCode 落地的第一道坎刚接触 OpenCode 的人十有八九会卡在同一个地方装好了、界面也打开了结果一发起对话就弹出一行报错——error from provider (console): opencodes free tier can only be used from within opencode。这句话翻译成人话就是你正在用的免费额度只允许在官方指定的运行环境里调用一旦你换了终端、换了插件、换了调用方式它就不认了。这个报错背后其实藏着一个很关键的认知OpenCode 本身是一个壳真正干活的是它背后挂载的模型。壳负责交互、上下文管理、工具调用编排模型负责推理和生成。壳和模型之间靠一份配置文件对接这份文件通常就是opencode.json。你把这份文件配明白了OpenCode 才能接上第三方 API或者接上你本机跑的本地模型。所以这篇内容想解决的问题很具体怎么把 OpenCode 的模型配置改对让它既能走第三方 API也能走本地模型。适合两类人看——一类是手里有 API Key、想省点成本或者想用特定模型的开发者另一类是机器配置还行、想在自己电脑上跑本地模型、图个数据不出本机的人。不管你是哪种配置逻辑是相通的区别只在provider那一段怎么写。我先把结论摆前面OpenCode 的模型配置核心就三件事——声明 provider、填对 baseURL 和 apiKey、指定 model 名称。听起来简单但每一件都有坑尤其是本地模型那一块端口、模型名、上下文长度、思考模式任何一个对不上都会让你怀疑人生。下面我按实际操作的顺序一层层拆开讲。2. 先把 opencode.json 这份配置文件的骨架搞清楚2.1 配置文件到底放在哪、长什么样很多人第一步就找错地方。OpenCode 的配置一般有两层一层是全局配置放在用户目录下一层是项目级配置放在项目根目录。项目级会覆盖全局这个设计跟大多数现代工具是一致的方便你给不同项目挂不同模型。全局配置的典型路径以类 Unix 系统为例在用户主目录下的配置文件夹里Windows 则在对应的 AppData 目录。项目级就是项目根目录直接放一个opencode.json。我个人的习惯是全局只放一个默认的、稳定的模型项目级按需覆盖。这样你换项目的时候不会因为全局配置被改乱而到处出问题。一份最小可用的配置骨架大概长这样{ $schema: https://opencode.ai/config.json, provider: { my-provider: { npm: ai-sdk/openai-compatible, name: My Provider, options: { baseURL: https://api.example.com/v1, apiKey: sk-xxxxxxxx }, models: { my-model: { name: My Model } } } } }这里有几个字段必须理解到位不然改起来就是瞎蒙provider是一个对象key 是你自己起的名字随便叫但后面引用模型的时候要用到。npm指定用哪个适配器包。绝大多数第三方 API 只要兼容 OpenAI 的接口格式用ai-sdk/openai-compatible就够了。这是最省事的一条路。options.baseURL是接口地址注意结尾的/v1要不要带取决于服务商带错了就是 404。options.apiKey就是你的密钥。models里声明这个 provider 下你能用哪些模型key 是模型 IDname是显示名。提示$schema这一行强烈建议保留。它能让你的编辑器自动补全和校验字段少打错字。很多人配置报错就是因为少了个逗号或者括号有 schema 提示能省一半时间。2.2 provider、model、agent 三者的关系别搞混新手最容易混的就是这三个概念。我用一个类比说清楚provider 是供应商model 是具体商品agent 是下单的人。provider 决定你从哪家拿货比如某云厂商、某个聚合平台、或者你本机的 Ollama。model 是这家供应商提供的具体型号比如某个推理强的、某个速度快的。agent 则是 OpenCode 里真正发起请求的角色你可以给不同的 agent 配不同的 model——比如让负责写代码的 agent 用强模型让负责跑杂活的 agent 用便宜快的模型。这个分层设计的好处是你可以在一个配置里挂好几个 provider、十几个 model然后按场景自由组合。理解了这层关系后面配置本地模型和第三方 API 就是同一套逻辑换个baseURL而已。2.3 配置改完怎么验证有没有生效改完配置别急着开聊先做一次体检。OpenCode 一般提供了列出当前可用模型的命令跑一下看看你新加的 provider 和 model 有没有出现在列表里。如果没出现八成是 JSON 语法错了或者字段名拼错了。验证顺序我建议这样走先确认 JSON 能被解析编辑器不报红基本就没事。再确认 provider 出现在模型列表里。最后发一条最简单的消息看能不能正常返回。这三步能把问题范围快速缩小列表里没有就是配置问题列表里有但发消息报错就是网络或密钥问题能返回但答非所问就是模型名或参数问题。分步排查永远比一上来就盯着报错发呆高效。3. 接入第三方 API 的完整流程与选型逻辑3.1 为什么优先选 OpenAI 兼容接口第三方 API 五花八门但你会发现绝大多数服务商都提供OpenAI 兼容的接口。这不是巧合而是因为 OpenAI 的接口格式已经成了事实标准适配它成本最低。对 OpenCode 来说只要服务商兼容这个格式你就能用同一个适配器包接进去不用为每家单独写代码。所以选型的第一原则是优先找支持 OpenAI 兼容格式的服务商。这样你的配置几乎可以复制粘贴只改baseURL、apiKey和模型名。如果某家服务商只提供自己私有的接口格式那你就得看 OpenCode 有没有对应的适配器没有的话就只能放弃或者自己写适配层成本高很多。我踩过的一个坑是有些服务商的baseURL文档写的是根地址但实际调用要带/v1有些则相反。最稳的办法是拿 curl 先手动打一次接口确认地址拼对了再写进配置。这一步花两分钟能省你半小时的排查。3.2 baseURL 和 apiKey 的填写细节baseURL的坑主要集中在结尾斜杠和版本路径上。举几个常见情况服务商文档写法实际应填说明https://api.xxx.comhttps://api.xxx.com/v1多数需要补版本路径https://api.xxx.com/v1/https://api.xxx.com/v1结尾斜杠有时会导致路径拼接异常https://api.xxx.com/v1/chat/completionshttps://api.xxx.com/v1只填到版本层不要带具体端点apiKey这块我强烈建议不要直接写死在配置文件里。原因很简单配置文件很容易被提交到代码仓库密钥一旦泄露就是真金白银的损失。更好的做法是用环境变量配置里引用变量名。OpenCode 的配置一般支持这种引用方式具体写法看版本但思路是通用的——密钥和配置分离。{ provider: { my-provider: { npm: ai-sdk/openai-compatible, name: My Provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_API_KEY} }, models: { my-model: { name: My Model } } } } }这样你只要在系统里设好MY_API_KEY这个环境变量配置本身就可以安全地分享和提交。3.3 模型名称必须和服务商文档完全一致这是另一个高频翻车点。模型名不是随便起的必须和服务商 API 文档里写的 ID 一模一样大小写、连字符、版本号都不能错。比如文档写的是deepseek-chat你写成DeepSeek-Chat或者deepseek_chat接口就会返回模型不存在。我的做法是配置前先把服务商的模型列表接口打一遍把返回的模型 ID 原样复制过来。这样绝对不会错。有些服务商还会区分对话模型和推理模型推理模型可能需要在请求里额外传参数开启思考模式这个后面本地模型那节会细说逻辑是相通的。3.4 多模型并存时的配置组织方式当你手里有好几个模型——比如一个强推理的、一个快响应的、一个便宜的——怎么组织配置才不乱我的建议是按 provider 分组按用途命名。比如你从同一家服务商拿了三个模型就放在同一个 provider 下的models里用清晰的 key 区分。如果是从不同服务商拿的就开多个 provider。然后在 agent 层面按用途引用。这样结构清晰改起来也不会牵一发动全身。有个实用技巧给模型 key 起名时带上用途前缀比如fast-xxx、strong-xxx、cheap-xxx。时间一长你根本记不住哪个模型是干嘛的命名清晰能救命。4. 本地模型接入从 Ollama 到 LM Studio 的实操路径4.1 本地模型为什么值得折腾先说清楚本地模型的价值不然你没动力折腾。三个核心好处数据不出本机、不消耗 API 额度、断网也能用。对于处理敏感代码、隐私文档的场景本地模型几乎是唯一选择。而且现在消费级显卡跑个 7B 到 14B 的模型已经很流畅了日常问答、代码补全完全够用。代价也很明显能力上限比云端大模型低配置门槛高。所以我的建议是——本地模型当日常轻量助手云端 API 当攻坚主力两者配合用。OpenCode 的多 provider 设计正好支持这种混合模式。4.2 Ollama 的接入配置Ollama 是目前本地部署最省心的方案之一装完就能拉模型跑。它默认监听本机的11434端口并且提供了 OpenAI 兼容的接口。所以接入 OpenCode 的配置和接第三方 API 几乎一样只是baseURL换成本机地址。{ provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama (local), options: { baseURL: http://localhost:11434/v1, apiKey: ollama }, models: { qwen2.5-coder:7b: { name: Qwen2.5 Coder 7B }, llama3.1:8b: { name: Llama 3.1 8B } } } } }几个关键点apiKey本地模型其实不需要但很多适配器要求这个字段非空随便填个占位符就行比如ollama。模型名必须和你ollama list里显示的完全一致包括那个:7b的标签。baseURL用localhost或127.0.0.1都行但如果你在容器里跑 OpenCode就得换成宿主机的实际地址。注意本地模型的上下文窗口通常比云端小。如果你发现长对话到一半模型开始失忆多半是上下文超了。这时候要么换更大上下文的模型要么在配置里调小上下文限制让 OpenCode 提前做截断。4.3 LM Studio 的接入差异LM Studio 是另一个流行的本地方案优势是有图形界面、模型管理方便。它默认的本地服务端口是1234接口路径同样是 OpenAI 兼容的/v1。配置思路和 Ollama 一模一样只改端口。{ provider: { lmstudio: { npm: ai-sdk/openai-compatible, name: LM Studio (local), options: { baseURL: http://localhost:1234/v1, apiKey: lmstudio }, models: { local-model: { name: Local Model } } } } }LM Studio 有个细节要注意你必须在它的界面里先手动加载模型服务才会真正可用。很多人配置写对了却连不上就是因为忘了在 LM Studio 里点加载。模型名也要和 LM Studio 里显示的标识一致有时候它显示的是文件路径有时候是模型 ID以实际加载后界面显示的为准。4.4 本地模型选型哪个模型适合你本地部署哪个模型最好这个问题没有标准答案取决于你的硬件和用途。我按经验给个参考硬件条件推荐规模适用场景8G 显存7B 量化版日常问答、简单代码补全12-16G 显存14B 量化版代码生成、文档总结24G 显存及以上32B 量化版复杂推理、长文档处理纯 CPU3B-7B 量化版轻量任务速度较慢代码场景优先选带 coder 后缀的模型这类模型在代码任务上经过专门优化效果明显好于通用模型。中文场景则优先选国产模型系列中文理解和表达更自然。别盲目追大跑得动、响应快才是日常可用的前提。4.5 思考模式的开启与关闭现在不少模型支持思考模式也叫推理模式会在正式回答前先输出一段推理过程。这个功能对复杂问题有帮助但会显著增加响应时间和 token 消耗。在 OpenCode 里控制思考模式通常有两种方式一种是在模型配置里加参数另一种是在请求时传特定字段。具体字段名因模型而异有的用reasoning相关参数有的用thinking开关。最靠谱的做法是查你所用模型的官方文档看它支持哪种开启方式。我的经验是日常对话关掉思考模式复杂任务再开。一直开着会让简单问题也变得很慢体验反而差。而且有些本地模型开思考模式后容易想太多输出一堆无关推理反而干扰结果。5. 配置报错的高频原因与排查链路5.1 那个 free tier 报错到底怎么回事回到开头那个报错opencodes free tier can only be used from within opencode。它的本质是免费额度和运行环境绑定了。官方给的免费额度只允许在官方认可的环境里用你一旦通过其他方式调用就会被拦。解决办法有两条路一是老老实实在官方环境里用免费额度二是配置自己的 provider用第三方 API 或本地模型彻底绕开免费额度的限制。后者才是长久之计因为免费额度总有各种限制自己配的 provider 才是完全可控的。理解了这一点你就明白为什么配置模型这件事这么重要——它决定了你是被额度牵着走还是自己掌握主动权。5.2 连接本地模型失败的排查顺序本地模型连不上是最常见的问题我总结了一套排查顺序按这个走基本能定位确认服务在跑浏览器或 curl 直接访问http://localhost:端口/v1/models能返回模型列表说明服务正常。确认端口对Ollama 是 11434LM Studio 是 1234别记混。确认模型已加载LM Studio 必须手动加载Ollama 要确认模型已 pull 下来。确认模型名一致配置里的模型名和服务里显示的必须完全一样。确认 baseURL 路径结尾的/v1别漏。这五步走完还连不上那基本就是 OpenCode 版本或适配器包的问题了可以试试更新版本或者换个适配器。5.3 第三方 API 报错的典型表现第三方 API 的报错通常更直白看错误信息就能猜个八九不离十报错关键词大概率原因处理方式401 / Unauthorized密钥错或没传检查 apiKey 和环境变量404 / Not FoundbaseURL 或模型名错核对地址和模型 ID429 / Rate limit触发限流降低频率或换套餐model not found模型名拼错从文档原样复制timeout网络不通检查网络和地址可达性我遇到最多的是 404基本都是baseURL少写或多写了路径段。拿 curl 手动打一次接口比对着配置猜快得多。5.4 配置改了不生效怎么办有时候你明明改了配置OpenCode 却像没看见一样。这种情况通常是缓存或没重启导致的。OpenCode 一般在启动时读取配置运行中改文件不会自动重载。所以改完配置记得重启一下。另外要确认你改的是当前生效的那份配置。前面说过有全局和项目级两层项目级会覆盖全局。如果你改了全局但项目里有自己的配置那当然不生效。排查时先确认当前项目用的是哪份配置。6. 多模型协同与进阶配置思路6.1 给不同 agent 分配不同模型OpenCode 的 agent 机制允许你按角色分配模型这是它比很多同类工具灵活的地方。我的实践是分三档主力 agent挂最强的模型负责复杂推理、架构设计、难题攻坚。日常 agent挂快而便宜的模型负责代码补全、简单问答、格式转换。本地 agent挂本地模型负责处理敏感内容、离线场景。这样配置的好处是成本和体验平衡得最好。强模型只在真正需要的时候调用日常琐事用便宜或本地模型扛整体开销能降不少。6.2 用 cc switch 类工具管理多套配置如果你经常在不同模型配置之间切换——比如工作时用公司配的 API个人项目用本地模型——手动改配置文件会很烦。这时候可以借助配置切换工具把多套配置存成不同文件一键切换。这类工具的核心逻辑就是替换配置文件。你把每套配置存好切换时它帮你把对应的那份覆盖到生效位置。省去了手动改来改去的麻烦也降低了改错的风险。配置多了之后这种工具几乎是刚需。6.3 数据安全角度的配置取舍从数据安全角度看配置选择其实是一道权衡题全云端能力最强但数据要出本机敏感场景慎用。全本地数据不出本机但能力受限硬件要求高。混合模式敏感任务走本地普通任务走云端兼顾安全和能力。我个人的选择是混合模式。涉及隐私和核心代码的任务强制走本地模型一般的问答和公开内容处理走云端 API。OpenCode 的多 provider 配置正好能实现这种分流这也是我推荐大家把配置学明白的核心原因——配置自由度直接决定了你的数据安全边界。6.4 配置的版本管理与备份最后说个容易被忽视的点配置文件要纳入版本管理。你辛苦调好的配置换台机器或者重装系统就没了重配一遍很痛苦。建议把配置去掉密钥提交到自己的私有仓库换机器时直接拉下来用。密钥部分用环境变量配置里只留引用。这样既安全又方便迁移。我还会在配置里加注释说明每个 provider 的用途时间长了回头看也能快速想起来当初为什么这么配。配置这件事说到底就是把壳和模型之间的那根线接对。接第三方 API 和接本地模型本质是同一套逻辑换个地址。把opencode.json的骨架吃透把 provider、model、agent 的关系理顺剩下的就是按文档填参数、按报错排查。我踩过的坑基本都写在上面了你照着走能少绕不少弯路。真正上手之后你会发现配置自由带来的那种完全掌控的感觉比用现成额度爽多了。