1. 三条免费路径的选型逻辑与适用场景OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型能力塞进命令行让你在写代码、读代码、改 bug 的时候不用切窗口直接在终端里对话。但真正让很多人卡住的不是安装而是“怎么用上免费模型”。官方自带的免费额度有使用限制一旦触发就会看到那句让人头大的报错error from provider (console): opencodes free tier can only be used from within opencode。这句话的意思是免费池只能在 OpenCode 自己的客户端里调用不能拿到别的地方去用而且额度有限、并发有限。所以实际使用中大家会自然分化出三条路第一条是继续用官方 Zen 免费池适合刚上手、想零配置体验的人第二条是接 OpenRouter 的免费模型适合想要更多模型选择、愿意折腾 API Key 的人第三条是本地跑 Ollama适合对隐私敏感、网络环境不稳定、或者想离线使用的人。这三条路不是互斥的很多人是组合着用——日常轻量任务走 Zen复杂任务切 OpenRouter敏感代码丢给本地 Ollama。我自己的使用习惯是Zen 当“默认档”OpenRouter 当“备用档”Ollama 当“离线档”。下面把三条路径的配置、踩坑点和实操细节全部拆开讲尽量让不同基础的读者都能照着做下来。1.1 为什么免费模型值得认真配置很多人觉得“免费的就是凑合用”但在 OpenCode 这个场景里免费模型的价值被低估了。原因有三个第一编程助手的日常任务大部分是解释代码、补全片段、写注释、生成测试用例这些任务对模型能力的要求没有想象中那么高一个 7B 到 14B 的模型就能干得不错第二免费模型可以让你在没有心理负担的情况下大量试错比如让模型反复重构同一段代码不用担心 token 账单第三本地模型跑起来之后你的代码不出本机这对处理公司内部项目或者有保密要求的代码来说是刚需。提示免费不等于无限制。Zen 免费池有调用频率和上下文长度限制OpenRouter 免费模型有每日请求数上限Ollama 本地模型受限于你的显存和内存。配置之前先想清楚自己的主要使用场景再决定主用哪条路。1.2 三条路径的核心差异对比维度Zen 免费池OpenRouter 免费模型本地 Ollama配置难度极低开箱即用中等需要注册和配置 Key中等偏高需要下载模型网络要求需要能访问官方服务需要能访问 OpenRouter完全离线可用模型选择固定几个较多含多个免费模型取决于你下载了什么隐私性代码会发送到远端代码会发送到远端代码不出本机速度取决于网络取决于网络和模型负载取决于本地硬件适合场景快速体验、轻量任务多模型对比、中等任务敏感代码、离线环境这张表不是让你二选一而是帮你判断“主力用哪个、备用用哪个”。我见过不少人一上来就折腾本地部署结果显卡不够、模型跑得比蜗牛还慢最后放弃了。也见过有人死磕 OpenRouter 免费额度结果一天用超了被限流。合理的做法是先跑通一条再逐步加。2. Zen 免费池零配置上手的正确姿势Zen 是 OpenCode 官方提供的模型服务入口免费池的存在意义就是降低上手门槛。你装完 OpenCode第一次运行的时候它会引导你选择 provider选 Zen 就能直接用不需要填任何 API Key。这也是为什么很多人说“OpenCode 开箱即用”——指的就是这条路径。但免费池的限制也很明确。那句opencodes free tier can only be used from within opencode的报错通常出现在两种情况下一是你试图把 Zen 的接口地址和密钥拿到别的工具里用二是你的 OpenCode 版本或者配置有问题导致它认为你不在“官方客户端环境”里。前者是设计如此后者需要排查。2.1 Zen 免费池的配置与验证安装 OpenCode 之后配置文件通常位于用户目录下的.config/opencode/opencode.jsonLinux/macOS或者%APPDATA%\opencode\opencode.jsonWindows。如果你走 Zen 路径这个文件里其实不需要写太多东西核心就是确认 provider 指向 Zen。一个典型的 Zen 配置片段长这样{ provider: zen, model: zen-default }具体字段名可能随版本变化建议用opencode config或者查看官方文档确认当前版本的写法。配置完之后运行opencode进入交互界面随便问一句“解释一下这段代码”如果能正常返回说明 Zen 路径通了。注意如果你在公司网络或者某些网络环境下Zen 服务可能连不上。这时候不要反复重试直接切到 Ollama 本地路径省时间。2.2 免费池报错的排查思路遇到free tier can only be used from within opencode这个报错按下面顺序排查确认你是在 OpenCode 客户端里调用而不是把配置复制到了别的工具。检查 OpenCode 版本老版本可能有兼容问题升级到最新版再试。检查opencode.json里有没有多余的 provider 配置有时候多个 provider 冲突会导致它误判。如果以上都没问题可能是免费额度用完了等一段时间或者换路径。我自己的经验是这个报错九成以上是因为“把 Zen 的配置拿去别的地方用了”。Zen 免费池的设计就是绑定客户端的想通这一点就不会在这上面浪费时间。2.3 Zen 免费池的实操心得Zen 最大的优势是省事最大的劣势是“不可控”——你不知道它什么时候限流、什么时候模型会换。所以我的建议是把 Zen 当成“快速验证”工具而不是“主力生产”工具。比如你想试试 OpenCode 的某个功能或者临时问一个简单问题用 Zen 没问题。但如果你要连续处理多个文件、做大规模重构还是切到 OpenRouter 或者本地模型更稳。另外Zen 免费池的模型能力是固定的你没法选。有时候它给的回答质量波动比较大这不是你的问题是服务端的负载和模型调度导致的。遇到这种情况换个时间段再试或者直接切路径。3. OpenRouter 免费模型多模型选择的性价比之选OpenRouter 是一个模型聚合平台它把很多家的模型放在一个接口后面你用一个 API Key 就能调用不同厂商的模型。对 OpenCode 用户来说OpenRouter 的价值在于它有一些完全免费的模型而且模型选择比 Zen 丰富得多。但 OpenRouter 的免费模型有几个坑第一免费模型的列表是动态变化的今天免费的明天可能就收费了第二免费模型通常有每日请求数限制比如一天 50 次或者 100 次第三部分免费模型对上下文长度有限制长代码文件可能塞不进去。3.1 获取 OpenRouter API Key 的完整流程第一步访问 OpenRouter 官方入口注册账号。注册过程不复杂邮箱加密码就行。第二步登录之后进入 Keys 页面创建一个新的 API Key。创建的时候给它起个名字比如 “opencode-free”方便以后管理。第三步复制这个 Key注意它只显示一次关掉页面就看不到了所以先粘贴到安全的地方。注意OpenRouter 的 API Key 是敏感信息不要提交到 Git 仓库也不要写在会公开的配置文件里。建议用环境变量的方式注入。第四步在 OpenCode 的配置文件里填入 OpenRouter 的 provider 信息。一个参考配置如下{ provider: openrouter, apiKey: 你的_OPENROUTER_KEY, model: 模型ID }模型 ID 需要去 OpenRouter 的模型列表页面找筛选 “Free” 标签挑一个适合编程的。常见的免费编程模型包括一些开源模型的托管版本具体哪个好用需要自己试。3.2 免费模型的筛选与实测建议OpenRouter 上的免费模型质量参差不齐不是所有标着 “Free” 的都适合编程。我的筛选标准是三条第一看上下文长度至少要有 32K不然读不了一个中等大小的文件第二看模型参数量太小的模型在代码理解上容易出错第三看社区反馈OpenRouter 的模型页面有使用量统计用的人多的通常不会太差。实测下来免费模型在以下任务上表现还可以解释单段代码、生成简单函数、写注释、转换代码风格。但在以下任务上容易翻车跨文件重构、复杂 bug 定位、需要长上下文推理的任务。所以用 OpenRouter 免费模型的时候尽量把任务拆小一次只问一个明确的问题。3.3 OpenRouter 充值与否的取舍OpenRouter 有充值选项充值之后可以用付费模型也可以提高免费模型的调用限额。但如果你只是想用免费模型不充值也能用只是要接受限额。充值方式支持多种支付渠道具体以平台当前支持的为准。我的建议是先不充值把免费额度用一段时间看看自己实际需要多少调用量。如果发现经常被限流再考虑充值。不要一上来就充值因为免费模型和付费模型的差距没有你想象中那么大很多日常任务免费模型完全够用。3.4 OpenRouter 配置的常见问题一个常见问题是 API Key 填对了但调用失败。这时候先检查 Key 有没有多余的空格再检查 OpenRouter 账号有没有完成验证。有些免费模型要求账号绑定支付方式才能用即使不扣费。另外OpenRouter 的接口地址不要写错配置里通常只需要填 provider 和 Key地址是内置的。另一个问题是模型 ID 写错。OpenRouter 的模型 ID 格式通常是厂商/模型名比如meta-llama/llama-3-8b这种。写错一个字符就会报 “model not found”。建议直接从模型页面复制 ID不要手打。4. 本地 Ollama离线与隐私的终极方案Ollama 是一个本地大模型运行工具它把模型下载、加载、推理这些步骤封装得很简单一条命令就能跑起来。对 OpenCode 用户来说Ollama 的意义在于你的代码完全不出本机而且不依赖网络。代价是你需要有一定的硬件资源尤其是显存。4.1 Ollama 安装与国内镜像源处理Ollama 支持 Windows、macOS、Linux。安装包可以从官方渠道下载但国内用户经常会遇到下载慢的问题。这时候可以用国内镜像源具体镜像地址会变化建议搜索“ollama 国内镜像源”找当前可用的。下载安装包之后正常安装即可。安装完成后运行ollama --version确认安装成功。然后需要下载模型这一步是最容易卡住的因为模型文件通常有几个 GB。国内下载模型慢的话可以配置镜像源或者用离线安装包的方式先在其他地方下载好模型文件再导入。提示Ollama 的模型存储路径默认在用户目录下如果系统盘空间不够可以在安装前设置环境变量把模型目录指向其他盘。4.2 模型选择与硬件匹配Ollama 支持的模型很多从 1B 到 70B 都有。选模型的核心原则是模型大小要和你的显存匹配。一个粗略的估算方法是模型参数量乘以 0.5 到 0.7得到大概的显存需求单位 GB。比如 7B 模型大概需要 4 到 5 GB 显存14B 需要 8 到 10 GB32B 需要 20 GB 以上。如果你的显存不够模型会回退到 CPU 推理速度会慢很多。所以选模型之前先看自己的显卡。以下是常见配置的参考显存推荐模型规模体验4-6 GB3B-7B可用速度一般8-12 GB7B-14B比较流畅16-24 GB14B-32B流畅质量较好24 GB 以上32B-70B接近商用体验编程任务建议至少 7B有条件上 14B。3B 以下的模型在代码理解上经常出错不太适合正经用。4.3 OpenCode 接入 Ollama 的配置Ollama 默认在本地的 11434 端口提供服务。OpenCode 接入 Ollama 的配置大概是这样的{ provider: ollama, baseUrl: http://localhost:11434, model: qwen2.5-coder:7b }模型名要和你ollama list里显示的一致。配置完之后先在终端里用ollama run 模型名测试一下模型能不能正常对话确认没问题再让 OpenCode 调用。一个常见报错是500 internal server error: llama-server process这通常是模型加载失败或者显存不足导致的。排查方法是先看 Ollama 的日志再确认模型文件有没有损坏最后检查显存占用。4.4 本地模型的性能调优本地模型跑起来之后如果觉得慢可以调几个参数。一是num_ctx控制上下文长度调小可以省显存二是num_gpu控制有多少层跑在 GPU 上显存够就调大三是num_thread控制 CPU 线程数CPU 推理时有用。这些参数可以在 OpenCode 的配置里传也可以在 Ollama 的 Modelfile 里设。我的经验是先把num_ctx设成 4096 或 8192够用就行不要一上来就设很大。上下文越长显存占用越高速度越慢。5. 三条路径的组合使用与切换策略单独用一条路径都有各自的局限真正高效的做法是组合使用。我的日常配置是这样的OpenCode 里配多个 provider根据任务类型手动切换。轻量问答走 Zen中等任务走 OpenRouter 免费模型敏感代码或者断网环境走 Ollama。5.1 多 provider 配置的写法OpenCode 的配置文件支持多个 provider你可以把它们都写进去用的时候指定。一个多 provider 的配置示例{ providers: { zen: { type: zen }, openrouter: { type: openrouter, apiKey: 你的_KEY }, ollama: { type: ollama, baseUrl: http://localhost:11434 } }, defaultProvider: zen }具体字段名以当前版本为准。配置好之后在 OpenCode 里应该有切换 provider 的命令或者通过启动参数指定。5.2 什么任务走哪条路我总结了一个简单的判断规则任务简单、不涉及敏感代码、网络正常走 Zen省事。任务中等、需要更好的模型、网络正常走 OpenRouter 免费模型。任务涉及公司代码、隐私要求高、或者网络不稳定走 Ollama。任务复杂、免费模型搞不定考虑 OpenRouter 付费模型或者本地跑更大的模型。这个规则不是死的你可以根据自己的实际情况调整。关键是不要死磕一条路哪条通走哪条。5.3 切换时的注意事项切换 provider 的时候注意上下文会不会丢失。有些 OpenCode 版本在切换 provider 后会清空当前会话所以切换前先把重要内容记下来。另外不同 provider 的模型能力不同同一个问题在不同模型上得到的回答质量可能差很多切换后如果回答不理想可以换个问法再试。6. 常见问题速查与避坑经验这一节把我在配置和使用过程中遇到的高频问题整理成速查表方便你快速定位。问题现象可能原因解决方法free tier can only be used from within opencode把 Zen 配置用到了别处或版本问题确认在 OpenCode 内使用升级版本OpenRouter 调用失败Key 错误、模型 ID 错误、账号未验证检查 Key 和模型 ID完成账号验证Ollama 下载模型慢网络问题用国内镜像源或离线安装包500 internal server error: llama-server process显存不足、模型损坏检查显存重新下载模型OpenCode 只思考不回答模型输出被截断或配置问题检查上下文长度设置换模型试本地模型速度慢显存不足回退 CPU换小模型或调低 num_ctx6.1 几个容易忽略的细节第一个细节是配置文件的位置。不同系统、不同版本的 OpenCode配置文件路径可能不一样。找不到的时候用opencode config命令或者看官方文档不要凭感觉猜。第二个细节是环境变量的优先级。有些配置项既可以在配置文件里写也可以用环境变量设环境变量通常优先级更高。如果你改了配置文件没生效检查一下有没有环境变量覆盖了。第三个细节是模型名称的大小写和分隔符。Ollama 的模型名用冒号分隔OpenRouter 的模型 ID 用斜杠分隔写错就报错。复制粘贴比手打靠谱。6.2 我踩过的几个坑第一个坑是 OpenRouter 免费模型的限额。我以为免费就是随便用结果一天用超了被限流第二天才恢复。后来我养成了习惯把重任务集中处理轻任务分散开避免短时间内大量调用。第二个坑是 Ollama 模型选太大。我一开始下了个 32B 的模型结果显存不够回退到 CPU 跑一个回答等了好几分钟。后来换成 7B速度快了很多质量也够用。选模型不要贪大合适最重要。第三个坑是配置文件格式错误。JSON 对格式要求严格多一个逗号、少一个引号都会导致解析失败。改完配置之后用工具校验一下 JSON 格式能省很多排查时间。6.3 关于 OpenCode 版本与兼容性OpenCode 更新比较频繁不同版本的配置格式可能有变化。如果你照着旧教程配置不成功先确认版本。另外OpenCode 有一些周边工具和插件比如 skills 机制可以扩展功能但这些不是必须的先把基础的三条路径跑通再说。提示遇到问题的时候先看 OpenCode 的日志输出大部分错误信息都在里面。日志通常比报错信息更详细能帮你快速定位问题。7. 从免费模型到稳定工作流的演进建议三条路径跑通之后下一步是把它变成稳定的工作流。我的做法是固定一套配置写一个启动脚本把常用的 provider 和模型预设好。这样每次打开 OpenCode 不用重新配直接进入工作状态。另外建议定期检查 OpenRouter 的免费模型列表因为它是动态变化的。有时候会新上一些不错的免费模型有时候旧的会下架。保持关注及时调整配置。本地 Ollama 这边建议把常用的模型提前下载好避免用的时候临时下载。如果硬盘空间够可以存两三个不同规模的模型根据任务切换。最后说一个实际体会免费模型和付费模型的差距在简单任务上几乎感觉不到在复杂任务上才明显。所以如果你的日常任务以简单为主三条免费路径完全够用没必要纠结。把省下来的精力放在怎么把问题描述清楚、怎么拆解任务上收益比换模型大得多。