1. 三条免费路径的底层逻辑与选型思路OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型的代码能力塞进命令行让你不离开终端就能完成读代码、改文件、跑命令这一整套流程。但真正让很多人卡住的不是怎么用而是怎么让它跑起来还不烧钱。官方自带的免费额度有使用范围限制一旦触发那条opencodes free tier can only be used from within opencode的报错很多人就懵了。这篇就围绕三条能长期白嫖或者低成本跑通的路径展开Zen 免费池、OpenRouter 免费模型、本地 Ollama。先说清楚这三条路各自的定位不然选错了会走很多弯路。Zen 免费池是 OpenCode 官方生态里的一条通道优点是零配置、开箱即用缺点是额度有限、有环境校验适合刚上手尝鲜。OpenRouter是一个模型聚合平台上面挂着大量带:free后缀的模型注册拿 key 就能用优点是模型选择多、切换灵活缺点是免费模型有速率限制、部分模型需要充值才能解锁更高配额。本地 Ollama是把模型跑在自己机器上优点是彻底离线、数据不出本机、没有额度焦虑缺点是对硬件有要求、首次下载模型可能很慢。我自己的建议是这样排优先级如果你只是想快速体验 OpenCode 的工作流先走 Zen 免费池如果你已经确定要长期用、且需要更强的模型能力走 OpenRouter如果你对数据隐私敏感、或者经常在没网的环境下写代码那本地 Ollama 是唯一解。三条路并不互斥实际用下来最舒服的方案是组合使用——日常轻量任务走免费池重任务切 OpenRouter敏感项目切本地。这里要解释一个很多人忽略的点OpenCode 的模型接入是通过配置文件opencode.json来管理的它本质上是一个 provider 路由层。你配置几个 provider它就能在几个之间切换。理解这一点很关键因为后面所有的配置改动最终都落到这个文件上。它的结构大致是provider字段下挂不同的服务商每个服务商下面配npm包、options比如 apiKey、baseURL和models列表。搞懂这个结构你就能自己往里加任何兼容 OpenAI 接口的服务。提示动手改配置前先把原来的opencode.json备份一份。这个文件一旦写坏OpenCode 可能直接起不来回滚比重写快得多。选型的时候还有一个隐性成本要考虑网络可达性。OpenRouter 的接口在国内访问的稳定性因网络环境而异本地 Ollama 则完全不受影响。所以如果你的网络环境不太稳定别一上来就死磕 OpenRouter先把本地这条路跑通心里会踏实很多。下面逐个拆解。2. Zen 免费池零配置上手与报错排查2.1 Zen 免费池到底是什么Zen 是 OpenCode 官方提供的一个模型接入层你可以把它理解成官方帮你托管好的一个模型网关。它内置了一批可用模型其中有一部分是免费额度。你不需要自己去申请第三方 key装好 OpenCode 之后登录一下就能直接调用。对新手来说这是门槛最低的一条路因为它把「申请 key、填配置、选模型」这几步全砍掉了。它的免费池有个重要特征只能在 OpenCode 内部使用。这就是那条报错的来源。系统会校验请求是不是从 OpenCode 客户端发出来的如果你试图把这个额度拿到别的地方用或者配置方式不对导致校验失败就会看到opencodes free tier can only be used from within opencode。这不是 bug是设计如此。2.2 从安装到跑通第一条命令安装 OpenCode 的方式取决于你的系统。macOS 和 Linux 下通常用包管理器或者官方脚本Windows 下建议用 WSL因为 OpenCode 在 Windows 原生环境下的 shell 兼容性一直是个坑热词里opencode在windows环境下什么shell工具好用这个问题问的人很多实测下来 WSL 里的 bash 或者 zsh 是最省心的PowerShell 偶尔会有路径和转义的问题。装完之后第一步是登录。OpenCode 会引导你完成认证认证通过后免费池就自动挂上了。这时候你可以直接问它一个简单问题比如让它读一下当前目录的某个文件看它能不能正常响应。如果能响应说明免费池通了。配置层面免费池对应的 provider 通常不需要你手动写apiKeyOpenCode 会自己管理凭证。你要做的只是确认默认模型指向的是免费池里的模型。可以在opencode.json里检查provider段看有没有指向 zen 的配置。如果没有手动加一段把options里的认证交给 OpenCode 自己处理。2.3 那条报错到底怎么解opencodes free tier can only be used from within opencode这条报错我踩过两次原因不一样。第一次是我把配置里的 baseURL 改成了别的东西导致请求没走 OpenCode 自己的通道校验自然过不了。第二次是我在另一个终端工具里复用了同一份配置同样触发校验。解决办法很直接确保你是通过 OpenCode 客户端本身发起的请求且配置里的 provider 指向官方通道不要手动改 baseURL。还有一种情况是版本问题。热词里出现了opencode v2说明版本迭代比较快。老版本的配置格式和新版本可能不兼容如果你是从旧版升上来的建议把opencode.json里的 provider 段对照新版文档重新写一遍别直接沿用。我遇到过升级后免费池突然不可用折腾半天发现是配置字段名变了。注意免费池的额度是有限的别拿它跑大批量的代码分析任务。我试过让它一次性读一个几千行的目录结果额度很快见底后面几个小时都用不了。轻量问答和单文件修改是它的舒适区。2.4 免费池适合干什么、不适合干什么适合的场景快速问一个语法问题、让它解释一段看不懂的代码、生成一个小的工具函数、改一个明显的 bug。这些任务 token 消耗小响应快免费额度完全够用。不适合的场景全项目重构、大规模代码审查、需要长上下文记忆的连续对话。这些任务要么 token 消耗巨大要么需要更强的模型免费池扛不住。真要做这些往下看 OpenRouter 和本地 Ollama。3. OpenRouter 免费模型注册、密钥与配置实操3.1 OpenRouter 是什么为什么值得用OpenRouter 是一个模型聚合平台把市面上大量模型统一到一个接口下。你注册一个账号拿一个 key就能调用它上面挂着的各种模型包括不少带:free后缀的免费模型。对 OpenCode 用户来说它的价值在于模型选择极其丰富——今天想用这个明天想试那个改一行配置就行不用去每个厂商单独注册。热词里openrouter是什么、openrouter api key怎么获得、openrouter密钥获取这几个问题高频出现说明很多人卡在入门这一步。其实流程不复杂难的是网络可达性和充值方式。下面一步步来。3.2 拿到 API Key 的完整流程第一步是访问 OpenRouter 官方入口注册账号。注册用邮箱就行过程很标准。注册完进到控制台找到 API Keys 页面点创建新 key。创建的时候给它起个名字方便以后管理比如opencode-main。创建完立刻把 key 复制下来因为它只显示一次关掉页面就看不到了只能重新建。这里有个细节OpenRouter 的免费模型和付费模型共用同一个 key但免费模型有独立的速率限制。如果你只用免费模型理论上不充值也能跑但速率限制会比较紧高峰期可能排队或者被拒。热词里openrouter充值、openrouter怎么充值、openrouter 支付宝这些问题说明不少人想充值解锁更高配额。充值方式支持信用卡部分地区也支持其他支付渠道具体以平台当前提供的为准。我的建议是先用免费额度跑一段时间确认这个平台适合你再考虑充值。3.3 写进 opencode.json 的正确姿势拿到 key 之后就要把它配到opencode.json里。OpenRouter 兼容 OpenAI 的接口格式所以配置思路和配一个 OpenAI 兼容服务是一样的。核心是这几项provider 名字、npm 包通常是 OpenAI 兼容的 SDK、options里的apiKey和baseURL、以及models列表。baseURL要指向 OpenRouter 的接口地址apiKey填你刚拿到的 key。models列表里填你想用的免费模型注意模型名要带:free后缀才是免费的。填完之后保存重启 OpenCode然后测试一下能不能正常调用。我建议第一次配置时只填一个模型跑通了再加第二个。一次性填一堆模型出问题的时候你分不清是配置格式错了还是某个模型名写错了。等一个跑通复制粘贴改模型名效率反而更高。3.4 免费模型的速率限制与应对OpenRouter 的免费模型有速率限制这是绕不开的。具体限制随平台策略调整但核心逻辑是免费额度优先给付费用户让路高峰期免费请求可能变慢甚至被拒。应对办法有几个一是错峰使用避开大家集中用模型的时间段二是准备多个免费模型做备份一个被限流就切另一个三是把重任务拆小减少单次请求的 token 量。热词里openrouter密钥大全这种词我理解是想找现成的 key 白嫖。这条路我不建议走一是别人的 key 随时可能失效或者被限二是安全性没法保证你的请求内容会经过别人的账号。自己注册一个几分钟的事踏实。提示OpenRouter 的模型名区分大小写也区分:free后缀。写错一个字符就会报模型不存在。配置完先用一个最简单的请求验证别急着上复杂任务。3.5 和 OpenCode 配合的实战技巧OpenCode 支持在会话里切换模型所以你可以把 OpenRouter 的免费模型和 Zen 免费池都配上根据任务类型手动切。轻量任务用 Zen需要更强推理的时候切 OpenRouter 上的免费大模型。这种组合用下来基本能覆盖大部分日常开发场景而且成本压到最低。还有一个技巧是给不同的 provider 起清晰的名字。比如zen-free、openrouter-free、ollama-local这样在切换的时候一眼就知道自己在用哪条路不会搞混。配置文件里名字乱起后期维护会很痛苦。4. 本地 Ollama离线部署与模型管理4.1 为什么值得折腾本地部署本地 Ollama 的核心价值是数据不出本机和没有额度焦虑。你写的代码、问的问题全部在本地模型里处理不经过任何外部服务。对于处理敏感项目、或者单纯不想被限流的人来说这是最舒服的方案。代价是硬件要求——模型越大对显存和内存的要求越高。热词里ollama本地部署、ollama部署私有大模型、ollama使用教程这些词热度很高说明本地部署是很多人的刚需。下面把安装、下载、配置、接入 OpenCode 这条链路讲透。4.2 安装 Ollama 与国内下载加速Ollama 的安装本身很简单官网下载对应系统的安装包双击或者命令行安装即可。真正让人头疼的是下载模型太慢。热词里ollama下载慢、ollama下载太慢了、ollama下载模型国内镜像、国内镜像源下载ollama这些问题集中出现说明这是最大的痛点。解决办法是配置镜像源。Ollama 支持通过环境变量指定模型下载的镜像地址。设置好之后下载速度会有明显提升。具体做法是找到 Ollama 的配置方式把镜像地址配进去然后重新拉取模型。不同系统的环境变量设置方式不一样Linux 和 macOS 下在 shell 配置里加Windows 下在系统环境变量里加。如果镜像源也不稳定还有一个办法是离线安装包。热词里ollama离线安装包就是这个思路——在有网的地方把模型文件下好拷贝到目标机器上导入。适合完全离线或者网络极差的环境。4.3 选哪个模型参数规模与硬件匹配模型不是越大越好要跟你的硬件匹配。经验值是8GB 显存能比较舒服地跑 7B 到 8B 参数的模型16GB 显存可以上到 14B 左右32GB 以上可以考虑更大的模型。内存也要留够模型加载和推理都吃内存。热词里出现了ollama run qwen3.5:2b2B 这种小参数模型对硬件要求很低普通笔记本就能跑适合做轻量的代码补全和问答。如果你机器配置一般从小模型起步跑顺了再往上加。别一上来就拉一个几十 B 的模型下载慢、跑不动、体验差容易劝退。选模型的时候还要看它的定位。有些模型偏通用对话有些专门针对代码优化。做编程助手优先选代码能力强的模型。可以在模型库里看描述或者先拉一个小尺寸的试跑感受一下它的代码理解能力再决定要不要上大尺寸。4.4 把 Ollama 接进 OpenCodeOllama 启动后会在本地起一个服务默认监听本地端口提供 OpenAI 兼容的接口。这意味着你可以像配 OpenRouter 一样把它配到opencode.json里。baseURL指向本地服务地址apiKey随便填一个占位符本地服务通常不校验models列表里填你本地已经拉取的模型名。配置完测试的时候如果报连接错误先确认 Ollama 服务是不是在跑。可以在浏览器或者用命令行请求一下本地接口看有没有响应。服务没起来配置写得再对也没用。注意本地模型的响应速度取决于你的硬件。同一个模型在带独显的机器上和在纯 CPU 的机器上体验差距巨大。纯 CPU 跑大模型会非常慢做好心理准备或者从小模型开始。4.5 本地部署的常见坑第一个坑是模型加载失败报llama-server process相关的错误。热词里ollama run qwen3.5:2b error: 500 internal server error: llama-server process就是这个。这类错误通常是模型文件损坏、显存不足、或者版本不兼容导致的。解决办法是重新拉取模型、检查显存占用、升级 Ollama 到最新版。第二个坑是端口冲突。如果你本机已经有别的服务占了 Ollama 默认的端口它可能起不来。改一下 Ollama 的监听端口或者把占用端口的服务停掉。第三个坑是模型名对不上。你在 OpenCode 配置里写的模型名必须和ollama list里显示的完全一致。差一个字符都调不通。配置完先用ollama list核对一遍。5. 三条路径的对比与组合策略5.1 一张表看清差异维度Zen 免费池OpenRouter 免费模型本地 Ollama配置难度最低登录即用中等需注册拿 key中等偏高需装服务拉模型成本免费额度有限免费模型免费有速率限制电费无额度限制网络依赖需要需要稳定性因环境而异完全不需要数据隐私经过官方通道经过第三方平台完全本地模型能力中等可选范围大有强模型取决于本地硬件适合场景尝鲜、轻量任务长期使用、需要强模型敏感项目、离线环境这张表不是让你三选一而是帮你判断当前该用哪条。实际用下来我大部分时间是三条都配着按任务切。5.2 组合使用的配置思路在opencode.json里把三个 provider 都配上各自起清晰的名字。日常问答走 Zen需要强推理的时候切 OpenRouter 的免费大模型处理敏感代码或者断网的时候切本地 Ollama。切换成本就是改一下当前使用的模型几秒钟的事。这种组合的好处是永远有一条路能用。Zen 额度用完了切 OpenRouterOpenRouter 被限流了切本地本地模型太慢切回 Zen。不会因为某一条路出问题就完全停工。5.3 什么情况下该升级到付费免费方案有天花板到了某个点你会想付费。判断标准很简单如果免费模型的速率限制已经影响到你的正常工作节奏或者你需要的能力免费模型给不了那就是该付费的时候了。OpenRouter 充值可以解锁更高配额和更多模型OpenCode 的付费套餐热词里的opencode go套餐、opencode go也能提供更稳定的服务。付费之前先算一笔账你每天大概用多少次、每次消耗多少 token、免费额度差多少。算清楚了再决定充多少别一冲动充一大堆用不完。6. 实操中踩过的坑与排查速查6.1 配置类问题速查现象可能原因排查方向免费池报只能在 OpenCode 内使用请求没走官方通道检查 baseURL 是否被改确认通过客户端发起OpenRouter 报模型不存在模型名写错或漏了:free核对模型名大小写和后缀Ollama 连接失败本地服务没起或端口不对确认服务在跑核对 baseURL 端口配置改完不生效没重启或配置格式错重启 OpenCode检查 JSON 语法升级后突然不可用配置字段名变了对照新版文档重写 provider 段6.2 几个容易被忽略的细节第一个细节是JSON 语法。opencode.json是严格的 JSON多一个逗号、少一个引号都会导致解析失败。改完用编辑器的 JSON 校验功能过一遍或者找个在线校验工具贴进去检查。我因为一个多余的逗号排查了半小时教训深刻。第二个细节是key 的存放。别把 API key 直接明文写在会提交到版本库的文件里。如果opencode.json在 git 仓库里把 key 放到环境变量里配置文件里引用环境变量。这样既安全换机器的时候也方便。第三个细节是模型切换的上下文。OpenCode 在切换模型的时候之前的对话上下文不一定能完整带过去。如果你在一个长对话中途切模型可能会丢失部分上下文。重要任务尽量在一个模型上跑完别中途乱切。6.3 性能与体验优化本地 Ollama 的体验优化空间最大。一是选对模型尺寸别硬上大模型二是确保用的是 GPU 推理而不是 CPU速度差好几倍三是给模型留够内存内存不足会频繁换页慢到没法用。OpenRouter 的优化主要是错峰和备份模型。准备两三个免费模型一个不行切另一个。Zen 免费池的优化就是控制任务规模别拿它干重活。提示不管走哪条路第一次配置完都先用一个最简单的请求验证。比如让它回答「11 等于几」。这个请求消耗极小能快速确认链路通不通。链路通了再上真实任务排查成本低很多。6.4 关于 OpenCode 本身的一些经验OpenCode 的 skill 机制热词里的opencode skills、opencode skill安装使用值得花时间研究。它允许你定义一些可复用的操作把常用流程固化下来。配置好 skill 之后很多重复性的操作可以一键完成效率提升明显。另外热词里opencode只思考不回答这个现象我遇到过。通常是模型返回被截断或者配置的模型不支持某种输出格式导致的。换个模型试试或者检查一下是不是 token 上限设得太低。Windows 用户再强调一遍用 WSL。原生 Windows 下的 shell 兼容问题会消耗你大量时间WSL 里一切顺畅。这不是 OpenCode 独有的问题是这类终端工具的通病。7. 我个人的组合方案与日常习惯折腾了这几条路之后我现在的固定配置是这样的opencode.json里同时挂着 Zen、OpenRouter 和本地 Ollama 三个 provider。默认走 Zen 免费池因为响应快、零维护。遇到需要长上下文或者强推理的任务手动切到 OpenRouter 上的免费大模型。处理公司项目或者涉及敏感信息的代码时切到本地 Ollama数据不出机器。日常习惯上我会定期检查各个 provider 的可用性。Zen 的额度、OpenRouter 的限流状态、本地模型的服务状态花一分钟确认一下避免关键时刻掉链子。本地模型我会保持一两个常用的拉取好不频繁换换来换去下载时间成本太高。最后分享一个我觉得最实用的小技巧把三条路的配置写在一个文件里用注释标清楚每段是干什么的。JSON 本身不支持注释但你可以用一个单独的说明文档记录或者用清晰的命名代替注释。等过几个月你回头看这个配置能一眼看懂省下重新研究的时间。这套组合用下来我基本没再为模型调用花过钱该有的能力也都有算是把免费方案榨得比较干净了。