1. 三条免费路径的底层逻辑与选型思路OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型能力塞进你的命令行工作流让你不离开终端就能完成代码补全、重构、解释、生成测试这些事。但真正让很多人卡住的不是怎么用而是怎么用上免费模型。官方免费池有调用来源限制OpenRouter 有免费额度和充值门槛本地 Ollama 又要处理下载和部署问题。这三条路各有各的坑我前后折腾了好几轮把每条路径都跑通了这里把完整的实操过程拆开讲。先说清楚这三条路径分别适合谁。Zen 免费池是 OpenCode 自带的免费通道开箱即用但有一条硬性限制——只能在 OpenCode 客户端内部调用脱离客户端就会报opencodes free tier can only be used from within opencode这个错误。OpenRouter是一个模型聚合平台提供一批带:free后缀的免费模型注册后拿到 API Key 就能用缺点是免费模型有速率限制高峰期可能排队或报错。本地 Ollama是把模型下载到自己机器上跑完全离线、不限次数代价是吃硬件资源而且国内下载模型经常慢到让人想砸键盘。我选择这三条路径并行验证核心考量是可用性和成本的平衡。Zen 池适合快速上手验证 OpenCode 本身好不好用OpenRouter 适合想要更多模型选择、又不想本地跑大模型的场景Ollama 适合对数据隐私有要求、或者想长期稳定使用不想被速率限制卡脖子的情况。三条路不是互斥的你完全可以同时配置在opencode.json里切换。提示三条路径的配置都集中在opencode.json这个文件里理解它的结构比记住具体命令更重要。后面每个路径我都会给出对应的配置片段。选型的时候还有一个容易被忽略的点模型能力和任务匹配度。免费模型里有些擅长代码生成有些擅长长文本理解有些在工具调用tool use上表现好。OpenCode 的很多功能依赖模型返回结构化的工具调用指令如果模型不支持或者支持得不好就会出现只思考不回答的情况——模型在那边输出一堆推理过程但就是不给你最终结果。这个后面在常见问题里会专门讲。2. Zen 免费池开箱即用的第一步2.1 Zen 免费池到底是什么Zen 是 OpenCode 内置的模型服务通道你可以把它理解成官方给你准备的一个体验装。不需要自己申请 API Key不需要配置第三方服务装好 OpenCode 之后直接就能调用一批免费模型。对于第一次接触 OpenCode 的人来说这是验证工具本身是否合你胃口的最快方式。但它的限制也很明确。那个报错信息opencodes free tier can only be used from within opencode说的就是免费池的调用必须经过 OpenCode 客户端本身你不能把这个通道的凭证拿出来给别的工具用。这个设计其实合理——官方补贴免费额度自然希望流量留在自己的产品里。所以如果你看到有人问怎么把 Zen 的免费额度接到别的编辑器里答案是做不到也别在这上面浪费时间。2.2 配置与验证步骤Zen 池的配置最简单基本不需要你手动写什么。安装完 OpenCode 后首次运行会引导你选择模型来源选 Zen 就行。如果你想手动确认配置打开opencode.json应该能看到类似这样的结构{ provider: zen, model: zen-default }具体字段名可能随版本变化但核心就是provider指向 zen。配置好之后在终端里跑一个简单任务验证比如让它解释一段代码opencode 解释这段 Python 代码的作用 test.py如果模型正常返回结果说明 Zen 池通了。如果报free tier can only be used from within opencode检查一下你是不是在 OpenCode 客户端之外调用了它——比如通过某个第三方插件或者脚本直接打接口那肯定会失败。2.3 使用心得与限制应对Zen 池的免费额度不是无限的具体限额官方没有公开一个固定数字但实测下来日常轻度使用够用。我的建议是把 Zen 池当作验证和轻量任务通道重活累活交给另外两条路。比如快速问个语法问题、生成个正则表达式、解释一段报错这些用 Zen 池很顺手。但如果你要让它读一个几千行的文件做重构可能几次就把额度耗完了。还有一个细节Zen 池的模型选择相对固定你不能像 OpenRouter 那样自由切换几十个模型。如果你对某个特定模型有偏好比如就想用某个版本的 Qwen 或者 DeepSeek那 Zen 池满足不了得走 OpenRouter 或 Ollama。注意Zen 池的可用模型列表会更新不同时间点看到的选项可能不一样。如果你发现之前能用的模型不见了先去官方文档确认当前支持的列表别急着怀疑自己配置错了。3. OpenRouter 免费模型选择多但有门槛3.1 OpenRouter 是什么以及免费模型的真相OpenRouter 是一个模型聚合服务把市面上主流的闭源和开源模型都接进来你用一套 API 就能调用。它上面有一批模型带:free后缀比如deepseek/deepseek-chat:free、qwen/qwen-2.5-coder:free这类这些就是免费模型。但免费这个词要拆开看。OpenRouter 的免费模型通常有速率限制比如每分钟请求数、每天请求数都有上限。而且免费模型的优先级低于付费模型高峰期可能响应慢甚至超时。另外部分免费模型需要你先充值一定金额才能解锁——这就是为什么热词里会出现openrouter充值openrouter怎么充值openrouter 支付宝这些搜索。OpenRouter 支持支付宝充值对国内用户算友好最低充值额度不高充一次就能解锁不少免费模型的调用权限。3.2 获取 API Key 与配置第一步是注册 OpenRouter 账号在官方入口找到 API Keys 页面创建一个新的 Key。这个 Key 就是你的凭证格式类似sk-or-v1-xxxxxxxx。拿到之后在opencode.json里配置{ provider: openrouter, apiKey: sk-or-v1-你的密钥, model: deepseek/deepseek-chat:free }如果你不想把 Key 明文写在配置文件里推荐这样做尤其是配置文件可能被同步或分享可以用环境变量export OPENROUTER_API_KEYsk-or-v1-你的密钥然后在opencode.json里引用环境变量。OpenCode 支持从环境变量读取凭证这样配置文件本身就不含敏感信息了。3.3 模型选择与速率限制应对OpenRouter 上的免费模型不少但适合编程任务的其实就那几个。我实测下来代码相关任务优先选带coder字样的模型比如 Qwen 的 coder 系列。通用对话和解释类任务DeepSeek 的免费版本表现不错。速率限制是最大的痛点。免费模型通常限制在每分钟若干次请求如果你让 OpenCode 连续处理多个文件很容易触发限制报错。应对办法有几个一是把任务合并别一个文件一个文件地调尽量一次性把相关上下文喂进去二是错峰使用避开国内晚上的高峰期三是配置备用模型OpenCode 支持配置多个 provider主通道被限流时切到 Ollama 本地模型顶上。提示OpenRouter 的免费模型列表和限制策略会变配置前先去它的模型页面确认当前哪些是免费的、限制是多少。别照着半年前的教程抄很可能已经失效了。3.4 充值相关的实际问题关于充值热词里问得很多。OpenRouter 的充值流程不复杂支持信用卡和支付宝。充值的目的主要是两个一是解锁部分需要余额才能用的免费模型二是当免费额度用完时能无缝切到付费模型继续干活。我的建议是先不充值把纯免费模型跑一遍确认 OpenCode 的工作流你满意了再考虑充值。毕竟充值之后如果发现工具不合用那钱就白花了。4. 本地 Ollama离线稳定但下载是道坎4.1 Ollama 的定位与适用场景Ollama 是把大模型跑在你自己机器上的工具。下载安装后一条ollama run命令就能拉起一个模型开始对话。对 OpenCode 来说Ollama 提供了一个完全本地、不限次数、不依赖网络的模型通道。如果你对代码隐私敏感或者想长期稳定使用不想被速率限制和额度卡住Ollama 是最靠谱的选择。代价是硬件。模型越大对内存和显存的要求越高。7B 参数的模型大概需要 8GB 左右内存能跑起来13B 需要 16GB再往上就得看显卡了。如果你的机器配置一般建议从 2B 到 7B 的小模型开始试比如 Qwen 的小参数版本跑起来压力小响应也快。4.2 安装与国内下载加速Ollama 的安装本身不难官网下载安装包一路下一步就行。真正的坎在下载模型。国内直接拉模型经常慢到怀疑人生热词里ollama下载慢ollama下载太慢了ollama下载模型国内镜像这些搜索就是真实写照。解决办法是配置国内镜像源。Ollama 支持通过环境变量指定模型仓库地址把它指向国内的镜像export OLLAMA_HOST127.0.0.1:11434 export OLLAMA_MODELS/your/models/path镜像源的配置方式随版本和镜像提供方不同而有差异核心思路是把默认的海外仓库地址替换成国内可访问的地址。配置好之后重新拉模型速度会有明显提升。如果还是慢可以考虑用离线安装包的方式——先在其他地方下载好模型文件再导入到 Ollama 的模型目录。4.3 在 OpenCode 中接入 OllamaOllama 默认在本地11434端口提供服务。在opencode.json里配置{ provider: ollama, baseUrl: http://127.0.0.1:11434, model: qwen2.5-coder:7b }配置好之后OpenCode 就会把请求发到本地 Ollama。验证方法是先在终端里直接跑ollama run qwen2.5-coder:7b确认模型能正常对话然后再通过 OpenCode 调用。如果 Ollama 本身报500 internal server error: llama-server process这类错误说明模型加载出了问题通常是内存不够或者模型文件损坏先解决 Ollama 层面的问题再排查 OpenCode 配置。4.4 模型选择与性能调优本地跑模型选型要看你的硬件和任务类型。代码任务优先选 coder 系列通用任务选 chat 系列。参数规模上7B 是性能和资源的一个平衡点再大对普通开发机就不友好了。性能调优有几个方向一是量化版本同样参数的模型4-bit 量化版本占用资源少很多速度也快精度损失在可接受范围内二是调整上下文长度OpenCode 处理大文件时会喂很长的上下文如果模型上下文窗口小要么截断要么报错配置时注意模型的上下文限制三是关闭不必要的后台程序本地跑模型吃内存机器上其他重负载程序会拖慢响应。注意本地模型的响应速度取决于你的硬件别拿它和云端 API 比速度。它的优势是稳定、免费、隐私不是快。5. 三条路径的对比与组合策略5.1 关键维度对比把三条路径放在一起看差异很明显维度Zen 免费池OpenRouter 免费模型本地 Ollama上手难度最低开箱即用中等需注册和配置 Key较高需安装和下载模型费用免费但有额度免费模型有限制可充值解锁完全免费吃硬件网络依赖需要需要不需要模型选择固定几个较多取决于你下载什么速率限制有额度限制免费模型限制较严无限制隐私性请求走云端请求走云端完全本地适用场景快速验证、轻量任务多模型切换、中等任务长期稳定、隐私敏感5.2 组合使用的最佳实践我的实际用法是三条路都配按任务切换。日常快速问答用 Zen 池省事需要特定模型或者 Zen 额度用完时切 OpenRouter处理敏感代码或者网络不稳定时切 Ollama。OpenCode 支持在配置里定义多个 provider切换成本很低。具体配置上可以在opencode.json里把三个 provider 都写上用的时候改一下默认 provider 字段就行。这样不用每次重新配切换就是改一行的事。5.3 常见报错速查折腾过程中遇到的报错不少整理成速查表报错信息原因解决办法free tier can only be used from within opencode在 OpenCode 客户端外调用 Zen 池确保通过 OpenCode 本身调用error from provider (console)provider 配置错误或凭证失效检查opencode.json里的 provider 和 Key500 internal server error: llama-server processOllama 模型加载失败检查内存、模型文件完整性模型只思考不回答模型不支持工具调用或返回格式不对换支持 tool use 的模型请求超时网络问题或免费模型限流切换 provider 或错峰使用6. 实操中踩过的坑与经验总结第一个坑是配置文件格式。opencode.json对格式要求严格多一个逗号少一个引号都会导致解析失败但报错信息不一定直接指向格式问题可能表现为 provider 加载失败。我的习惯是改完配置先用 JSON 校验工具过一遍确认格式没问题再运行。第二个坑是模型和任务的匹配。前面提到的只思考不回答根源就是模型不支持 OpenCode 需要的工具调用格式。免费模型里不是所有都支持 tool use选模型时要注意这一点。判断方法很简单如果模型在别的支持工具调用的客户端里能正常干活那在 OpenCode 里大概率也行。第三个坑是Ollama 的模型路径。默认模型存在用户目录下如果你系统盘空间紧张最好一开始就通过OLLAMA_MODELS环境变量把模型目录指到大容量磁盘。等模型下载了一堆再迁移麻烦得多。第四个坑是环境变量和配置文件的优先级。OpenCode 读取凭证时环境变量和配置文件里的值谁优先不同版本行为可能不一样。我的做法是只用一种方式要么全放环境变量要么全放配置文件避免两者冲突时搞不清哪个生效。最后分享一个实用技巧给每个 provider 配一个简单的验证命令。比如配好 OpenRouter 后先用 curl 直接打它的接口确认 Key 有效再配到 OpenCode 里。这样出问题时能快速定位是 Key 的问题还是 OpenCode 配置的问题省去来回排查的时间。本地 Ollama 同理先用ollama run确认模型能跑再接入 OpenCode。分层验证比一上来就全链路调试高效得多。