1. 三条免费路径的底层逻辑与选型思路OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型能力塞进命令行让你在写代码、读代码、改 bug 的时候不用切窗口直接在终端里对话。但真正让很多人卡住的不是安装而是“怎么用上免费模型”。官方自带的免费额度有使用范围限制一旦触发error from provider (console): opencodes free tier can only be used from within opencode这类报错很多人就懵了。我自己把三条路径都跑了一遍Zen 免费池、OpenRouter 免费模型、本地 Ollama。这三条路各有各的适用场景不是简单的“哪个好用选哪个”而是要看你的网络环境、机器配置、以及对隐私和稳定性的要求。下面先把选型逻辑讲清楚再逐条拆实操。1.1 为什么是这三条路径先说 Zen 免费池。这是 OpenCode 官方内置的一条通道配置最简单基本装完就能用。它的优势是零门槛不需要你去注册第三方账号、不需要 API Key、不需要本地跑模型。但它的限制也很明显免费额度有调用频率和上下文长度的约束而且从热词里那个报错信息能看出来官方对免费池的使用场景做了绑定某些情况下会拒绝服务。所以 Zen 适合“先跑通、先体验”的阶段。OpenRouter 是第二条路。它本质上是一个模型聚合平台把市面上大量模型包括不少免费模型统一成一个 API 接口。你注册一个账号、拿一个 API Key就能在 OpenCode 里调用它支持的免费模型。这条路的好处是模型选择多、切换灵活缺点是免费模型通常有速率限制而且注册和充值流程对国内用户来说需要一点耐心。Ollama 是第三条路也是唯一一条完全离线的路。你在本地把模型跑起来OpenCode 通过本地接口调用。它的最大优势是隐私完全可控、不依赖网络、没有调用次数限制。代价是对机器配置有要求而且模型下载和首次加载会比较慢热词里“ollama下载太慢了”“ollama下载模型国内镜像”这些搜索词就反映了这个痛点。1.2 三条路径的对比与选择建议维度Zen 免费池OpenRouter 免费模型本地 Ollama配置难度极低中等中等偏高是否需要联网是是否是否需要 API Key否是否模型选择固定丰富取决于本地下载调用限制有频率/场景限制有速率限制无隐私性一般一般完全可控硬件要求无无较高适合场景快速体验多模型对比隐私敏感/离线我的建议是这样如果你刚装好 OpenCode先用 Zen 免费池跑通流程确认工具链没问题然后注册 OpenRouter拿免费模型做日常轻量任务如果你有隐私要求或者网络不稳定再上 Ollama 本地部署。三条路可以共存在opencode.json里配置多个 provider按需切换。提示不要一上来就折腾 Ollama。模型下载动辄几个 GB如果机器配置不够或者网络环境不好很容易在第一步就劝退。先用 Zen 把 OpenCode 的基本操作摸熟再考虑本地部署。2. Zen 免费池的配置与使用要点Zen 免费池是 OpenCode 官方提供的一条内置通道也是三条路里配置成本最低的。它的核心价值在于“开箱即用”——你不需要去任何第三方平台注册账号不需要申请 API Key装好 OpenCode 之后基本就能直接对话。2.1 Zen 免费池是什么能做什么Zen 免费池本质上是 OpenCode 官方托管的一组模型资源用户通过 OpenCode 客户端直接调用。它解决的是“我想先试试这个工具到底好不好用”这个需求。你可以在终端里让它帮你解释代码、生成函数、排查报错甚至做一些简单的重构建议。但要注意免费池不是无限量供应的。官方对免费池做了使用范围绑定热词里那条opencodes free tier can only be used from within opencode的报错意思就是免费额度只能在 OpenCode 客户端内部使用不能通过其他方式去调用。这其实是一种防滥用机制保证免费资源真正服务于 OpenCode 用户。2.2 配置步骤与实操Zen 免费池的配置非常简单基本不需要手动改配置文件。安装完 OpenCode 后首次启动会引导你选择 provider选 Zen 即可。如果你已经有opencode.json确认里面没有把默认 provider 指向别的地方。一个典型的opencode.json配置结构是这样的{ provider: zen, model: default, temperature: 0.7 }这里provider字段指定使用 Zen 通道model用默认值就行temperature控制输出的随机性写代码场景建议 0.3 到 0.7 之间太低会死板太高会跑偏。如果你在 Windows 环境下使用热词里有人问“opencode在windows环境下什么shell工具好用”我的经验是 PowerShell 7 比自带的 cmd 和旧版 PowerShell 体验好很多路径处理和管道操作都更顺。安装 OpenCode 的时候确保 Node.js 版本在 18 以上否则可能遇到兼容性问题。2.3 常见报错与排查Zen 免费池最常见的报错就是前面提到的使用范围限制。如果你看到opencodes free tier can only be used from within opencode先确认你是通过 OpenCode 客户端发起的请求而不是在别的工具里配置了 Zen 的接口。其次检查你的 OpenCode 版本热词里出现了opencode v2说明版本迭代比较快旧版本可能不支持最新的免费池策略。另一个常见问题是“opencode只思考不回答”。这个通常不是模型本身的问题而是你的提示词太模糊或者上下文太长导致模型在推理阶段就耗尽了输出预算。解决办法是把问题拆小一次只问一个具体的事比如不要问“帮我优化这个项目”而是问“这个函数的时间复杂度能不能降到 O(n)”。注意Zen 免费池的额度是有限的不要拿它跑大批量任务。如果你需要频繁调用老老实实走 OpenRouter 或者本地 Ollama。3. OpenRouter 免费模型的接入与避坑OpenRouter 是三条路里模型选择最丰富的一条。它把大量模型聚合到一个 API 下其中不少是免费模型。对于想对比不同模型效果、又不想一个个去注册账号的开发者来说这条路很实用。3.1 OpenRouter 是什么免费模型怎么找OpenRouter 的定位是“模型路由层”。你拿一个 API Key就能调用它支持的众多模型包括一些厂商提供的免费额度。它的免费模型通常会在模型名称里标注:free后缀或者在模型列表里单独分类。注册流程不复杂进 OpenRouter 官方入口用邮箱注册然后在控制台生成 API Key。热词里“openrouter api key怎么获得”“openrouter密钥获取”问的就是这一步。生成之后把 Key 复制下来注意不要泄露它等同于你的调用凭证。关于充值热词里“openrouter充值”“openrouter怎么充值”“openrouter 支付宝”这些搜索说明国内用户对支付方式比较关心。OpenRouter 支持信用卡部分场景下也有其他支付渠道。如果你只用免费模型其实不需要充值但免费模型有速率限制充值后额度会宽松一些。3.2 在 opencode.json 里配置 OpenRouter配置 OpenRouter 的核心是在opencode.json里加一个 provider 条目。结构大概是这样{ providers: { openrouter: { apiKey: 你的_API_KEY, baseUrl: https://openrouter.ai/api/v1, model: 模型名称:free } }, defaultProvider: openrouter }这里有几个关键点。apiKey填你生成的 KeybaseUrl是 OpenRouter 的接口地址model填你想用的免费模型名称注意带:free后缀的才是免费版本。defaultProvider指定默认走哪条通道方便你在多个 provider 之间切换。模型名称不要凭记忆写去 OpenRouter 的模型列表页面复制准确的 ID。写错了会直接报模型不存在的错误排查起来很浪费时间。3.3 免费模型的速率限制与应对OpenRouter 的免费模型普遍有速率限制通常是每分钟请求数或者每天请求数的上限。触发限制后会返回 429 状态码。应对办法有几个一是把请求合并减少调用次数二是在代码里加退避重试逻辑三是准备一个备用模型主模型限流时切过去。我自己的做法是在opencode.json里配两个 OpenRouter 条目一个主用一个备用主用限流时手动切。虽然不够自动化但胜在简单可靠不需要写额外的调度代码。提示OpenRouter 上标:free的模型不同时间段可用性可能不一样。有些免费模型是限时活动过一段时间就收费了。用之前先确认当前状态。4. 本地 Ollama 部署与 OpenCode 对接Ollama 是三条路里唯一完全离线的方案。它的价值在于隐私可控、无调用限制、不依赖外部网络。代价是对硬件有要求而且模型下载和加载需要时间。4.1 Ollama 安装与国内镜像源处理Ollama 的安装本身不复杂官网下载安装包一路下一步就行。热词里“ollama安装”“ollama安装包”“ollama离线安装包”说明很多人卡在下载环节。如果你网络环境不好下载安装包和模型都会很慢。对于模型下载慢的问题可以配置国内镜像源。Ollama 支持通过环境变量指定镜像地址具体做法是在启动 Ollama 服务前设置对应的环境变量。热词里“ollama国内镜像源”“ollama下载模型国内镜像”就是冲着这个来的。配置好镜像源之后ollama pull的速度会有明显提升。安装完成后用ollama --version确认版本然后ollama serve启动服务。默认监听在127.0.0.1:11434这是后面 OpenCode 对接的地址。4.2 模型选择与下载策略Ollama 支持大量开源模型从 2B 到 70B 参数不等。选模型的核心原则是“匹配你的硬件”。显存和内存决定了你能跑多大的模型。一个粗略的参考7B 模型量化后大约需要 4 到 6 GB 显存13B 需要 8 到 10 GB再往上就得看具体量化方式和硬件条件了。热词里出现了ollama run qwen3.5:2b以及error: 500 internal server error: llama-server process这个报错。2B 这种小模型对硬件要求很低但报 500 错误通常不是硬件问题而是模型文件损坏或者服务进程异常。解决办法是先ollama rm删掉模型重新 pull再检查 Ollama 服务日志。下载模型的时候建议一次只下一个下完确认能用再下下一个。同时下多个会抢带宽而且容易因为磁盘 IO 问题导致文件损坏。4.3 OpenCode 对接 Ollama 的配置在opencode.json里配置 Ollama 的 provider结构如下{ providers: { ollama: { baseUrl: http://127.0.0.1:11434/v1, model: qwen2.5-coder:7b } }, defaultProvider: ollama }注意baseUrl要带/v1后缀因为 OpenCode 走的是 OpenAI 兼容接口。model填你本地已经 pull 下来的模型名称用ollama list可以查看。配置好之后在 OpenCode 里发一条测试消息看能不能正常返回。如果报连接错误先确认 Ollama 服务在跑如果报模型不存在用ollama list核对名称。4.4 本地部署的性能调优本地跑模型性能调优主要看几个参数。一是上下文长度Ollama 默认的上下文窗口可能比较小可以在 Modelfile 里调大但调大会吃更多显存。二是并发数本地服务一般不需要高并发保持默认就行。三是量化等级Q4 量化在质量和资源占用之间比较平衡Q8 质量更好但更吃资源。如果你的机器有独立显卡确保 Ollama 能识别到 GPU。用ollama ps可以看到模型加载在哪个设备上。如果跑在 CPU 上速度会慢很多这时候要么换小模型要么考虑升级硬件。注意本地模型的输出质量和云端大模型有差距尤其是复杂推理和长上下文任务。Ollama 适合做代码补全、简单问答、隐私敏感场景不要指望它替代云端旗舰模型。5. 三条路径的切换与组合使用实际使用中三条路径不是互斥的而是可以组合的。OpenCode 支持在opencode.json里配置多个 provider你可以根据任务类型手动切换。5.1 多 provider 配置结构一个同时包含三条路径的配置大概长这样{ providers: { zen: { model: default }, openrouter: { apiKey: 你的_KEY, baseUrl: https://openrouter.ai/api/v1, model: 某个免费模型:free }, ollama: { baseUrl: http://127.0.0.1:11434/v1, model: qwen2.5-coder:7b } }, defaultProvider: zen }这样配置之后默认走 Zen需要切换时改defaultProvider就行。有些版本的 OpenCode 支持在会话里用命令切换 provider具体看你的版本。5.2 按任务类型选择路径我的使用习惯是这样快速问答和代码解释走 Zen因为响应快、零配置需要对比不同模型效果或者做稍复杂的生成任务走 OpenRouter因为模型选择多涉及私有代码或者网络不通的时候走 Ollama保证可用性。这种组合方式的好处是不把鸡蛋放在一个篮子里。某条路径出问题的时候立刻切到另一条不耽误事。5.3 配置文件的版本管理opencode.json里会存 API Key所以这个文件不要提交到公开仓库。建议把它加到.gitignore里或者用环境变量代替明文 Key。OpenCode 支持从环境变量读取 Key具体写法是在配置里用${ENV_VAR}的形式引用。另外OpenCode 版本更新比较快热词里opencode v2、opencode go、opencode go套餐这些说明产品线在扩展。升级版本之后回头检查一下配置文件格式有没有变化避免因为字段改名导致配置失效。6. 常见问题速查与实操心得这一节把我踩过的坑和常见问题整理成速查表方便你遇到问题时快速定位。6.1 常见报错与解决对照表报错信息可能原因解决办法free tier can only be used from within opencode免费池使用范围限制确认通过 OpenCode 客户端调用检查版本error from provider (console)provider 配置错误核对opencode.json里的字段和 Key500 internal server error: llama-server processOllama 模型文件损坏删除模型重新 pull检查服务日志模型不存在模型名称写错用ollama list或 OpenRouter 列表核对429 状态码免费模型速率限制降低调用频率或切换备用模型连接超时网络问题或服务未启动检查 Ollama 服务状态确认网络连通只思考不回答提示词模糊或上下文过长拆小问题减少单次上下文长度6.2 实操心得第一条心得先把一条路跑通再折腾第二条。我见过太多人一上来就三条路同时配结果哪条都没跑通最后怀疑是工具的问题。实际上大部分问题都是配置细节没对上。第二条心得API Key 和配置文件要管好。OpenRouter 的 Key 泄露了别人可以拿去用你的额度Ollama 虽然本地不需要 Key但服务端口如果暴露到公网也有风险。默认监听127.0.0.1是安全的不要随便改成0.0.0.0。第三条心得模型名称一定要复制不要手打。OpenRouter 和 Ollama 的模型名称都有特定格式手打很容易错一个字符然后排查半天。第四条心得关注 OpenCode 的版本更新。热词里opencode skills、opencode skill安装使用、opencode go cc switch、opencode go接入claude code这些说明生态在快速扩展。新版本可能带来新的免费额度策略或者新的 provider 支持及时升级能省不少事。6.3 关于 OpenCode 的其他使用场景热词里还出现了opencode stm32代码开发说明有人拿它做嵌入式开发。这种场景下本地 Ollama 的优势比较明显因为嵌入式代码往往涉及私有硬件细节走云端模型有隐私顾虑。另外anythingllm与ollama这个组合也值得关注AnythingLLM 可以作为 Ollama 的前端界面配合 OpenCode 使用能覆盖更多场景。opencode桌面版和ollama webui 中文便携版下载 开源镜像这些搜索说明大家对方便的图形界面有需求。如果你不习惯纯终端操作可以关注这些配套工具但核心的模型接入逻辑和本文讲的三条路径是一样的。最后分享一个小技巧如果你在 OpenRouter 上找到了好用的免费模型但担心它哪天收费可以先把模型 ID 记下来同时在本地的 Ollama 里 pull 一个同级别的开源模型作为备份。这样即使云端免费额度没了本地还能顶上工作流不会断。