1. 三条免费路径的底层逻辑与选型思路OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型的代码生成能力塞进命令行让你不离开终端就能完成代码补全、重构、调试、写测试这些活。但真正让很多人卡住的不是怎么用而是怎么用上免费的模型。官方免费池有调用来源限制OpenRouter 有免费额度和充值门槛本地 Ollama 又涉及下载和配置。这三条路各有各的坑我前后折腾了好几轮把每条路径都跑通了这里把完整的实操过程拆开讲。先说清楚这三条路径分别适合谁。Zen 免费池是 OpenCode 官方提供的免费模型通道开箱即用不需要自己申请任何密钥但它的限制也很明确——只能在 OpenCode 客户端内部调用一旦你试图从外部或者非官方渠道去请求就会撞上opencodes free tier can only be used from within opencode这个报错。OpenRouter是一个模型聚合平台上面有大量带:free后缀的免费模型注册后拿到 API Key 就能用但免费额度有每日上限而且部分模型需要账户里有余额才能解锁。本地 Ollama是把模型下载到自己机器上跑完全离线、不依赖任何外部服务代价是吃硬件资源而且国内下载模型的速度是个大问题。我选择把三条路径都保留在配置里按场景切换。日常快速问答和轻量补全用 Zen 免费池需要特定模型能力时切 OpenRouter 的免费模型涉及敏感代码或者断网环境就切本地 Ollama。这种多路径并存的思路比死磕一条路要稳得多。1.1 为什么不能只依赖一条路径单条路径的问题在于可用性波动。Zen 免费池虽然方便但它的模型列表和额度是官方控制的遇到高峰期或者官方调整策略你可能突然就用不了。OpenRouter 的免费模型更是不稳定今天还在的:free模型明天可能就下架了而且免费额度的限制规则经常变。本地 Ollama 最稳定但前提是你的机器扛得住而且模型下载这一步就能劝退不少人。我自己的做法是在opencode.json里把三条路径的 provider 都配好用的时候通过命令或者配置切换。这样任何一条路出问题我都能在几秒内切到另一条不会因为某个服务挂了就完全没法干活。这个思路在后面每个章节里都会体现你可以根据自己的网络环境和硬件条件决定主用哪条、备用哪条。1.2 三条路径的核心差异对比在动手之前先把三条路径的关键指标摆出来方便你判断该从哪条开始。对比维度Zen 免费池OpenRouter 免费模型本地 Ollama是否需要密钥否是否是否依赖网络是是否调用来源限制仅限 OpenCode 内部无特殊限制无免费额度官方限定每日限额部分需余额无限吃硬件模型选择官方指定大量:free模型自行下载硬件要求无无较高配置复杂度最低中等较高稳定性中等较低最高这张表是我实际用下来总结的不是官方文档里的说法。比如 OpenRouter 的稳定性我标了“较低”是因为免费模型的可用性确实波动大有时候一个模型上午能用下午就报错。本地 Ollama 的稳定性最高但前提是你已经把模型下载好了下载这一步的坑我在后面会详细讲。2. Zen 免费池的接入与来源限制破解思路Zen 免费池是 OpenCode 最省事的免费方案没有之一。你装好 OpenCode 之后默认配置里其实就已经挂上了 Zen 的免费模型直接就能对话。但很多人会遇到那个经典的报错error from provider (console): opencodes free tier can only be used from within opencode。这个报错的含义是Zen 免费池校验了请求的来源只有从 OpenCode 客户端内部发起的调用才被允许。2.1 Zen 免费池的默认配置与验证先确认你的 OpenCode 版本。我用的过程中发现OpenCode v2 和早期版本在配置结构上有差异v2 的配置文件更规范推荐用 v2。安装完成后在终端执行opencode进入交互界面输入/models或者类似的模型列表命令你应该能看到 Zen 提供的免费模型选项。如果能看到并且能正常对话说明 Zen 免费池已经生效不需要额外配置。如果看不到模型或者对话时报来源限制的错先检查两件事。第一确认你是通过 OpenCode 客户端本身在调用而不是把 Zen 的接口地址抄出来用 curl 或者别的工具去请求。第二检查你的opencode.json里 provider 配置有没有被手动改过。默认情况下Zen 的 provider 配置是内置的你不需要自己填 base URL 和密钥。{ providers: { zen: { type: builtin, models: [zen-free-default] } } }上面这段是简化示意实际配置里 Zen 的字段可能更复杂但核心逻辑是不要手动去改 Zen 的 provider 配置。很多人出问题就是因为从网上抄了一份配置把 Zen 的 base URL 改成了别的地址结果来源校验直接失败。2.2 来源限制的常见触发场景与规避我踩过的坑里触发来源限制报错主要有这么几种情况。第一种是用脚本或者自动化工具去调 OpenCode 的接口而不是通过交互式终端。第二种是在容器或者远程环境里跑 OpenCode但网络出口的标识和官方预期的不一致。第三种是配置文件里混入了其他 provider 的字段导致 Zen 的请求被错误路由。规避的思路很简单让 OpenCode 自己管 Zen 的调用。你只需要在交互界面里正常使用不要试图绕过客户端去直接请求。如果你确实需要在脚本里调用那就不要用 Zen改用 OpenRouter 或者本地 Ollama这两条路没有来源限制。提示如果你在 Windows 环境下用 OpenCodeshell 工具的选择会影响体验。我实测下来Windows Terminal 配合 PowerShell 7 比默认的 cmd 要稳路径处理和字符编码问题少很多。2.3 Zen 免费池的额度与模型轮换Zen 免费池的额度是官方控制的具体数字会变我不在这里写死。但有一个经验免费池的模型会轮换。有时候你常用的那个模型突然从列表里消失了不是你的配置坏了是官方调整了。遇到这种情况去模型列表里换一个可用的就行不用折腾配置。另外Zen 免费池的响应速度在高峰期会明显变慢。我的做法是如果连续几次请求都超时就临时切到 OpenRouter 或者本地 Ollama等高峰期过了再切回来。这种灵活切换的习惯比死守一个通道要高效。3. OpenRouter 免费模型的申请、配置与充值避坑OpenRouter 是一个模型聚合平台上面聚合了大量厂商的模型其中不少带:free后缀的是完全免费的。它的优势是模型选择多从轻量的小模型到接近旗舰能力的大模型都有免费版本。劣势是免费额度有限制而且部分模型的免费通道需要账户里有余额才能解锁。3.1 OpenRouter 账号注册与 API Key 获取注册流程不复杂打开 OpenRouter 官方入口用邮箱或者第三方账号登录。登录之后进入 Keys 页面创建一个新的 API Key。这个 Key 就是你在 OpenCode 里配置时要填的东西。创建的时候注意Key 只在创建时显示一次复制下来存好关掉页面就看不到了。拿到 Key 之后先别急着往 OpenCode 里填用官方提供的测试接口验证一下 Key 是否有效。你可以用 curl 发一个最简单的请求确认返回正常。这一步能帮你排除掉 Key 本身的问题避免后面在 OpenCode 里排查半天发现是 Key 错了。curl https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer 你的API_KEY \ -H Content-Type: application/json \ -d { model: 某个:free模型, messages: [{role: user, content: hello}] }如果返回里有正常的回复内容说明 Key 没问题。如果返回 401检查 Key 有没有复制错如果返回 402 或者额度相关的错误说明这个模型需要余额或者你的免费额度用完了。3.2 OpenCode 中配置 OpenRouter 的完整写法在opencode.json里配置 OpenRouter核心是填对 provider 类型、base URL、API Key 和模型列表。下面是我实际在用的配置结构你可以直接参考。{ providers: { openrouter: { type: openai-compatible, baseURL: https://openrouter.ai/api/v1, apiKey: 你的_OPENROUTER_API_KEY, models: [ 模型A:free, 模型B:free ] } } }几个关键点说明一下。type填openai-compatible因为 OpenRouter 的接口是兼容 OpenAI 格式的。baseURL必须是https://openrouter.ai/api/v1少一个字符都不行。apiKey填你刚才创建的 Key。models列表里填你想用的免费模型注意要带:free后缀不带后缀的是付费通道。配置改完之后重启 OpenCode在模型列表里应该就能看到你配的 OpenRouter 模型了。如果看不到检查 JSON 格式有没有语法错误逗号、引号这些最容易出问题。3.3 OpenRouter 充值、支付宝与免费额度的关系这里要澄清一个很多人误解的点OpenRouter 的免费模型不等于完全不需要余额。部分:free模型确实可以零余额使用但有一些模型虽然标了免费实际上要求账户里至少有少量余额才解锁。这个规则 OpenRouter 没有统一说明是逐个模型不同的。关于充值OpenRouter 支持多种支付方式国内用户比较关心的是支付宝能不能用。我实测下来OpenRouter 的支付通道对国内用户是开放的具体支持的支付方式以你注册时看到的为准。充值金额没有硬性门槛充一点就能解锁那些需要余额的免费模型。但我的建议是先不要充值。先把零余额就能用的免费模型跑一遍确认 OpenRouter 这条路在你的网络环境下是通的再考虑要不要充值解锁更多模型。很多人一上来就充值结果发现网络不通或者模型不好用钱就白花了。注意OpenRouter 的免费额度是每日重置的具体额度数字会调整。如果你当天用完了等第二天重置即可不用反复重试重试也不会增加额度。3.4 免费模型的筛选与稳定性观察OpenRouter 上的免费模型很多但不是每个都好用。我筛选的标准有三个响应速度、代码能力、稳定性。响应速度太慢的写代码时等待时间过长体验很差。代码能力弱的生成的代码经常需要大改还不如自己写。稳定性差的用着用着就报错打断思路。我的做法是同时配三到四个免费模型在列表里用一段时间之后把经常出问题的删掉留下最稳的两个。这个过程需要几天时间观察不要指望一次就选对。另外OpenRouter 的模型列表是动态的定期去看看有没有新的免费模型上线有时候会有惊喜。4. 本地 Ollama 部署下载加速、模型选择与 OpenCode 对接本地 Ollama 是三条路径里最稳的因为模型跑在你自己的机器上不依赖任何外部服务。但它的门槛也最高主要是两个问题安装和模型下载。国内用户下载 Ollama 安装包和模型时速度慢是常态有时候直接卡住不动。4.1 Ollama 安装与国内镜像源加速Ollama 的安装包在官网可以下载但国内直连速度不理想。解决办法是用国内镜像源。具体来说Ollama 的安装脚本和模型仓库都有国内镜像可用你可以在安装时指定镜像地址或者手动下载安装包。Linux 环境下用官方脚本安装时可以通过环境变量指定镜像export OLLAMA_HOST镜像地址 curl -fsSL 安装脚本地址 | shWindows 和 macOS 用户建议直接下载安装包用下载工具加速。安装包本身不大但如果你从官网直连下载很慢可以找国内的镜像站。安装完成后验证一下ollama --version能正常输出版本号说明安装成功。4.2 模型下载太慢的解决思路模型下载是最大的坑。一个 7B 的模型动辄几个 GB国内直连下载经常只有几十 KB/s下一天都下不完。解决办法有几个。第一个是用国内镜像源下载模型。Ollama 支持通过环境变量指定模型仓库的镜像地址设置之后ollama pull会从镜像拉取速度能快很多。export OLLAMA_MODELS_MIRROR国内镜像地址 ollama pull qwen2.5:7b第二个是手动下载模型文件然后导入 Ollama。这种方式适合镜像源也没有的模型你从其他渠道拿到模型文件后用ollama create命令导入。第三个是选择小一点的模型比如 2B 或者 3B 的版本文件小下载快对硬件要求也低。我实测下来2B 到 7B 的模型在代码补全和简单问答上已经够用没必要一上来就追大模型。等下载和运行都跑通了再考虑换更大的。4.3 Ollama 模型选择与硬件匹配选模型要看你的硬件。纯 CPU 跑的话7B 模型勉强能跑但速度慢2B 到 3B 比较流畅。有独立显卡的话显存 8GB 以上可以跑 7B16GB 以上可以尝试更大的模型。代码场景下我推荐从 Qwen 系列的代码模型或者通用模型开始中文支持好代码能力也不错。下载之前先确认模型名称用ollama list看本地已有的模型用ollama pull 模型名下载新的。ollama pull qwen2.5-coder:7b ollama run qwen2.5-coder:7bollama run之后如果出现error: 500 internal server error: llama-server process这类报错通常是模型文件损坏或者显存不足。先检查模型有没有下载完整再检查硬件资源够不够。4.4 OpenCode 对接本地 Ollama 的配置Ollama 默认在本地的11434端口提供服务OpenCode 配置时把 base URL 指向这个地址就行。{ providers: { ollama: { type: openai-compatible, baseURL: http://localhost:11434/v1, apiKey: ollama, models: [ qwen2.5-coder:7b ] } } }apiKey填ollama就行本地服务不校验这个。models里填你ollama list里看到的模型名称要完全一致。配置完成后重启 OpenCode选择 Ollama 的模型应该就能正常对话了。如果连不上先确认 Ollama 服务在运行用curl http://localhost:11434/v1/models测试一下能不能返回模型列表。如果返回正常但 OpenCode 连不上检查 OpenCode 的配置文件路径对不对以及有没有其他配置覆盖了 Ollama 的设置。5. 多路径切换与 opencode.json 配置管理实战三条路径都配好之后怎么在它们之间切换是个实际问题。OpenCode 的模型选择可以在交互界面里做但如果你经常切换手动选模型比较麻烦。我的做法是在opencode.json里把三条路径都配好然后用不同的配置文件或者配置片段来快速切换。5.1 opencode.json 的完整配置结构下面是我实际在用的配置结构把三条路径都整合进去了。你可以直接参考这个结构把里面的密钥和模型名换成你自己的。{ providers: { zen: { type: builtin }, openrouter: { type: openai-compatible, baseURL: https://openrouter.ai/api/v1, apiKey: 你的_OPENROUTER_KEY, models: [模型A:free, 模型B:free] }, ollama: { type: openai-compatible, baseURL: http://localhost:11434/v1, apiKey: ollama, models: [qwen2.5-coder:7b] } }, defaultProvider: zen }defaultProvider设成你最常用的那条路径。我设的是zen因为日常轻量使用最方便。需要切换时改这个字段或者用命令行参数指定。5.2 配置文件的版本管理与备份opencode.json里含有 API Key直接提交到 Git 仓库有泄露风险。我的做法是把配置文件分成两部分一部分是不含密钥的模板提交到仓库另一部分是含密钥的实际配置放在本地并且加到.gitignore里。模板文件里用占位符代替密钥实际使用时用脚本或者手动替换。这样既能版本管理配置结构又不会泄露密钥。如果你只有一台机器用不涉及版本管理那至少也要定期备份配置文件避免重装系统或者误删之后重新配一遍。5.3 切换路径的实操流程与验证切换路径的流程很简单改defaultProvider或者用命令行参数指定 provider然后重启 OpenCode。重启后在模型列表里确认目标 provider 的模型出现了发一条测试消息确认能正常回复。我习惯在切换后做一个快速验证问一个简单的问题比如让它写一个 Hello World看响应是否正常。如果报错根据错误信息判断是哪条路径的问题。Zen 报来源限制就说明配置被改了OpenRouter 报额度错误就说明当天免费额度用完了Ollama 报连接错误就说明本地服务没起来。6. 常见报错排查与避坑经验速查这一节把我在三条路径上遇到过的典型报错和解决办法整理出来方便你遇到问题时快速定位。报错信息所属路径原因解决办法opencodes free tier can only be used from within opencodeZen调用来源不是 OpenCode 客户端不要绕过客户端直接请求检查配置有没有被改error from provider (console)Zenprovider 配置错误恢复 Zen 的默认配置不要手动改 base URL401 UnauthorizedOpenRouterAPI Key 错误或失效重新创建 Key确认复制完整402 或额度错误OpenRouter免费额度用完或模型需余额等次日重置或充值解锁模型列表为空OpenRouter模型名拼写错误或已下架检查:free后缀换可用模型llama-server process500 错误Ollama模型文件损坏或显存不足重新下载模型检查硬件资源连接被拒绝Ollama本地服务未启动启动 Ollama 服务确认端口模型下载卡住Ollama网络问题使用国内镜像源或手动导入模型6.1 排查思路的通用框架遇到报错时我的排查顺序是先看报错信息属于哪条路径然后检查该路径的配置再检查网络或服务状态最后检查模型本身。这个顺序能覆盖大部分问题。比如 OpenRouter 报 401先检查 Key再检查 base URL再检查模型名。Ollama 报连接错误先检查服务有没有起来再检查端口再检查防火墙。Zen 报来源限制先检查配置有没有被改再检查调用方式。6.2 几个容易忽略的细节第一个细节是配置文件的编码。Windows 下用记事本编辑 JSON 文件有时候会带上 BOM 头导致解析失败。用 VS Code 或者专门的编辑器保存时选 UTF-8 无 BOM。第二个细节是端口占用。Ollama 默认用 11434如果这个端口被别的程序占了Ollama 会启动失败或者换端口。用netstat检查端口占用情况。第三个细节是模型名称的大小写和标点。Ollama 的模型名是大小写敏感的qwen2.5-coder:7b和Qwen2.5-Coder:7B可能被当成两个不同的模型。配置时直接从ollama list的输出里复制不要手打。6.3 长期使用的维护建议三条路径配好之后不是一劳永逸的。OpenRouter 的免费模型会变需要定期更新模型列表。Ollama 的模型可以定期更新到新版本性能和能力可能有提升。Zen 的免费池策略也可能调整关注官方公告。我的习惯是每个月花十分钟检查一遍三条路径的可用性把失效的模型换掉把新的免费模型加进来。这个维护成本很低但能避免关键时刻掉链子。7. 进阶玩法OpenCode 与 Claude Code、STM32 开发等场景的结合OpenCode 的免费模型路径跑通之后可以往更多场景延伸。热词里提到的opencode go 接入 claude code、opencode stm32 代码开发、opencode skills这些都是可以探索的方向。7.1 OpenCode Go 套餐与 Claude Code 的接入思路OpenCode Go 是 OpenCode 的一个套餐版本具体权益以官方说明为准。接入 Claude Code 的思路本质上还是通过 provider 配置把 Claude 的模型接进来。如果你有 Claude 的 API 访问权限可以在opencode.json里加一个 provider指向 Claude 的接口。但要注意Claude 的接口不是 OpenAI 兼容格式需要 OpenCode 支持对应的 provider 类型或者通过中间层转换。7.2 OpenCode 在嵌入式开发中的使用STM32 代码开发这类场景OpenCode 可以帮你生成外设初始化代码、解析寄存器配置、写中断处理逻辑。用本地 Ollama 跑这类任务有个好处代码不出本机适合涉及硬件细节的项目。模型选择上代码能力强的模型效果更好Qwen 的代码模型在这个场景下表现不错。7.3 OpenCode Skills 的安装与使用OpenCode Skills 是扩展 OpenCode 能力的机制可以理解为给 OpenCode 装插件。安装和使用方法以官方文档为准核心思路是把 skill 文件放到指定目录然后在配置里启用。Skills 能扩展 OpenCode 在特定领域的表现比如特定框架的代码生成、特定格式的文件处理等。我在实际使用中的体会是免费模型路径跑通只是第一步真正提升效率的是把 OpenCode 融入日常开发流程。比如把它配成 Git 提交前的代码检查助手或者配成写测试的辅助工具。这些用法不需要多强的模型免费模型完全够用。最后再分享一个小技巧如果你经常在多个项目间切换可以为每个项目建一个独立的opencode.json放在项目根目录OpenCode 启动时会优先读取项目级的配置这样不同项目可以用不同的模型和 provider互不干扰。