1. 三条免费路径的底层逻辑与选型思路OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型能力塞进命令行让你在写代码、读代码、改 bug 的时候不用来回切窗口。但真正让很多人卡住的不是它好不好用而是怎么在不花钱或者少花钱的前提下把它跑起来。我自己前前后后折腾了好几轮从最早的 Zen 免费池到 OpenRouter 的免费额度再到本地 Ollama 部署三条路都踩过一遍这里把完整的实操过程和踩坑记录整理出来。先说清楚这三条路径分别适合什么人。Zen 免费池是 OpenCode 官方自带的免费通道开箱即用不需要自己申请任何密钥适合刚接触 OpenCode、想先跑通流程的新手。OpenRouter 免费模型是通过第三方聚合平台调用标注为 free 的模型模型选择面广适合已经有一定配置经验、想要更多模型选项的人。本地 Ollama是把模型下载到自己机器上跑完全不依赖外部服务适合对数据隐私敏感、或者网络环境不稳定、又或者想长期零成本使用的开发者。这三条路不是互斥的你完全可以在opencode.json里同时配置多个 provider根据任务类型切换。比如日常补全用 Zen 免费池复杂重构用 OpenRouter 上的免费大模型涉及敏感代码的时候切到本地 Ollama。下面逐个拆解。在正式动手之前有一个概念需要先建立起来OpenCode 的所有模型接入都是通过配置文件opencode.json来管理的。这个文件通常放在用户目录下的.config/opencode/目录里Windows 下则是%USERPROFILE%\.config\opencode\。你所有的 provider、模型、密钥、参数都在这里定义。理解了这个文件的组织结构后面三条路径的配置就是往里面填不同的内容而已。提示OpenCode 的配置文件支持热加载改完opencode.json保存后一般不需要重启但如果你发现配置没生效手动重启一次是最稳妥的做法。2. Zen 免费池零配置上手的第一条路2.1 Zen 免费池到底是什么Zen 是 OpenCode 官方提供的一个模型接入层你可以把它理解成官方帮你搭好的一个中转站。它里面有一个免费池free tier提供若干标注为免费的模型你不需要自己去申请 API Key只要在 OpenCode 里登录或者用匿名方式就能调用。这对刚上手的人来说非常友好因为省掉了注册、充值、配置密钥这一整套流程。但这里有一个很多人会遇到的问题就是热词里出现的那个报错error from provider (console): opencodes free tier can only be used from within opencode。这个报错的意思是Zen 的免费池被限制只能在 OpenCode 客户端内部调用你不能拿它的接口去别的工具里用。所以如果你看到这个错误先确认你是不是在 OpenCode 之外的地方调用了 Zen 的接口。正常情况下只要你在 OpenCode 里面正常使用是不会触发这个限制的。2.2 配置步骤与实操Zen 免费池的配置是最简单的基本不需要你手动写太多东西。打开 OpenCode 后它会引导你完成初始设置。如果你选择使用 Zen 作为 providerOpenCode 会自动帮你把相关配置写进opencode.json。一个典型的 Zen 配置片段大概长这样{ providers: { zen: { type: zen, models: { default: zen-free-model } } } }实际字段名可能会随版本变化但结构逻辑是一样的声明一个 provider指定类型为 zen然后选一个默认模型。你不需要填 API Key因为免费池的鉴权是 OpenCode 内部处理的。配置完成后在 OpenCode 里输入一个简单的测试指令比如让它解释一段代码看看能不能正常返回。如果返回正常说明 Zen 免费池已经跑通了。2.3 使用心得与限制Zen 免费池最大的优势是省事但它的限制也很明显。第一免费池的模型能力通常不是最强的适合做日常的代码解释、简单补全、格式转换这类任务遇到复杂的架构设计或者长上下文推理可能会力不从心。第二免费池有调用频率限制如果你短时间内大量请求可能会被限流。第三就像前面说的它只能在 OpenCode 内部使用不能导出到其他工具。我个人的用法是把 Zen 免费池当作一个随手可用的兜底选项。比如我在终端里快速看一下某个函数的逻辑或者让 AI 帮我写个正则表达式这种轻量任务用 Zen 就够了没必要动用更重的方案。但如果是需要深度思考的任务我会切到下面要讲的另外两条路。注意如果你在 OpenCode 里配置了多个 provider记得在调用时明确指定用哪个否则可能会默认走 Zen导致你以为在用别的模型实际上一直在用免费池。3. OpenRouter 免费模型模型选择面最广的一条路3.1 OpenRouter 是什么为什么要用它OpenRouter 是一个模型聚合平台它把市面上大量的模型包括很多商业模型和开源模型统一到一个接口下。你只需要一个 OpenRouter 的 API Key就能调用它上面列出的各种模型。它上面有一部分模型标注为:free也就是免费使用这就是我们这条路径的核心。用 OpenRouter 的好处是模型选择极其丰富。你想用某个开源大模型或者想对比不同模型在同一个任务上的表现OpenRouter 都能满足。而且它的接口是标准的配置一次就能在 OpenCode 里长期使用。3.2 获取 API Key 与充值说明首先你需要去 OpenRouter 的官方入口注册一个账号。注册流程很标准邮箱加密码就行。注册完成后在账号设置里找到 API Keys 页面创建一个新的 Key。这个 Key 就是你后面要填进opencode.json的东西。关于充值这里要说明一下OpenRouter 上的免费模型确实不需要付费就能用但你的账号最好还是绑定一下支付方式或者充一点点余额。原因是有时候免费模型会有速率限制账号有余额的话优先级会高一些。热词里很多人问openrouter 怎么充值openrouter 支付宝实际上 OpenRouter 支持多种支付方式具体以你注册时看到的选项为准。如果你只是想用免费模型不充值也能跑只是可能遇到限流。拿到 API Key 之后妥善保存因为它只显示一次。如果你不小心弄丢了只能重新创建一个。3.3 在 opencode.json 中配置 OpenRouter配置 OpenRouter 的核心就是把 API Key 和你想用的免费模型填进去。一个典型的配置如下{ providers: { openrouter: { type: openrouter, apiKey: sk-or-v1-你的密钥, models: { default: 某个模型:free } } } }这里的关键点是模型名称后面要带:free后缀这样才会走免费通道。如果你写了一个不带:free的模型名那就会走付费通道可能会产生费用。这一点一定要确认清楚。配置好之后在 OpenCode 里切换到这个 provider发一个测试请求。如果返回正常说明配置成功。如果报鉴权错误检查 API Key 有没有复制完整如果报模型不存在检查模型名拼写和后缀。3.4 免费模型的挑选与使用技巧OpenRouter 上的免费模型更新比较快今天免费的明天可能就收费了所以你需要定期关注一下。挑选的时候我一般看几个维度上下文长度、是否支持代码任务、响应速度。上下文长度决定了它能一次处理多少代码做代码审查或者大文件分析的时候上下文短的模型会截断内容。支持代码任务的模型通常在代码补全和 bug 定位上表现更好。使用技巧方面我建议不要把所有任务都压给一个模型。OpenCode 支持配置多个模型你可以给不同任务配不同的默认模型。比如快速补全用一个响应快的免费模型深度分析用一个能力强的免费模型。这样既省额度又保证效果。提示OpenRouter 的免费模型有时候会因为负载高而响应慢或者超时遇到这种情况不要急着怀疑配置先换个时间段再试或者换一个免费模型。4. 本地 Ollama数据不出本机的终极方案4.1 为什么选择本地部署本地 Ollama 这条路的逻辑和前面两条完全不同。前面两条都是调用远程服务你的代码内容会发送到对方的服务器上。而 Ollama 是把模型下载到你自己的电脑上运行所有的推理都在本地完成代码和数据不会离开你的机器。对于处理公司内部代码、敏感项目、或者单纯不想让代码上云的人来说这是唯一的选择。另外本地部署一旦跑通就是完全零成本的。没有调用次数限制没有额度焦虑想怎么用就怎么用。代价是你需要一台配置还过得去的机器以及第一次下载模型的时间。4.2 安装 Ollama 与国内镜像源Ollama 的安装本身不复杂官网下载安装包双击安装就行。但热词里大量出现ollama 下载慢ollama 下载太慢了国内镜像源下载 ollama说明下载速度是很多人的痛点。如果你直接从官方源下载安装包或者模型速度可能很慢甚至中断。解决办法是使用国内镜像源。Ollama 的模型下载支持通过环境变量指定镜像地址。你可以在启动 Ollama 之前设置OLLAMA_HOST或者相关的镜像环境变量让它从国内镜像拉取模型。具体的镜像地址会随时间变化你可以在社区里找到当前可用的镜像源。安装包本身也可以找国内的开源镜像站下载速度会快很多。安装完成后在终端里运行ollama --version确认安装成功。然后运行ollama serve启动服务有些安装方式会自动作为后台服务启动。4.3 下载模型与常见报错处理模型下载是本地部署里最耗时的一步。你可以用ollama pull 模型名来下载。模型的选择上如果你机器配置一般建议从较小的模型开始比如 2B 到 7B 参数量的模型。参数量越大对显存和内存的要求越高推理速度也越慢。热词里有一个报错值得单独说ollama run qwen3.5:2b error: 500 internal server error: llama-server process。这个错误通常是底层推理进程启动失败导致的。常见原因有几个一是模型文件下载不完整重新 pull 一次二是内存或显存不足换一个更小的模型试试三是 Ollama 版本和模型不兼容升级 Ollama 到最新版。排查的时候先看 Ollama 的日志输出里面通常会有更具体的错误信息。还有一个常见问题是模型下载到一半断了。Ollama 支持断点续传重新执行 pull 命令会从断点继续不用从头再来。4.4 在 OpenCode 中接入 OllamaOllama 默认在本地的11434端口提供接口。在opencode.json里配置 Ollama 的典型写法如下{ providers: { ollama: { type: ollama, baseUrl: http://localhost:11434, models: { default: 你下载的模型名 } } } }配置好之后确保 Ollama 服务正在运行然后在 OpenCode 里切换到这个 provider 测试。如果连接失败先确认 Ollama 服务有没有启动再确认端口有没有被占用。本地模型的响应速度取决于你的硬件。同样的模型在有独立显卡的机器上跑和在纯 CPU 上跑速度差距可能有好几倍。如果你发现响应特别慢可以考虑换更小的模型或者检查一下是不是显存不够导致回退到了 CPU 推理。注意本地模型的能力和参数量强相关。2B 的模型做简单补全还行但复杂的代码推理可能会给出不太靠谱的结果。如果你的机器能带动 7B 或更大的模型体验会好很多。5. 三条路径的对比与组合使用策略5.1 横向对比把三条路径放在一起对比能更清楚地看出各自的适用场景。维度Zen 免费池OpenRouter 免费模型本地 Ollama配置难度最低开箱即用中等需要申请密钥较高需要安装和下载模型模型选择有限非常丰富取决于你下载了什么数据隐私代码会上传代码会上传完全本地不出机器使用成本免费免费模型免费有额度限制电费零调用成本响应速度取决于网络取决于网络和模型负载取决于本地硬件适用场景轻量任务、快速上手多样化任务、模型对比敏感代码、长期使用从表里能看出来这三条路其实是互补的。Zen 适合入门和轻量任务OpenRouter 适合需要模型多样性的场景Ollama 适合对隐私和成本有要求的长期使用。5.2 组合配置的实操建议在opencode.json里同时配置三个 provider 是完全可行的。我的建议是给每个 provider 起一个清晰的名字然后在日常使用中根据任务类型切换。比如快速问答、格式转换走 Zen代码审查、复杂重构走 OpenRouter 上的强模型处理敏感项目、离线环境走 Ollama切换的方式取决于 OpenCode 的具体版本有的版本支持在对话中用命令切换模型有的版本需要改配置文件。你可以查一下当前版本的文档或者直接在 OpenCode 里输入帮助命令看看支持哪些操作。5.3 常见问题速查把三条路径的常见问题整理成一张表方便排查。问题现象可能原因解决方向Zen 报 free tier 限制在 OpenCode 外部调用了接口确认只在 OpenCode 内使用OpenRouter 报鉴权失败API Key 错误或未生效重新复制密钥确认没有多余空格OpenRouter 报模型不存在模型名拼写错误或已下架核对模型名确认 :free 后缀Ollama 下载慢未使用国内镜像源配置镜像环境变量后重试Ollama 报 500 错误模型文件损坏或资源不足重新 pull或换更小模型Ollama 连接失败服务未启动或端口占用启动服务检查 11434 端口配置改了不生效热加载未触发重启 OpenCode这张表基本覆盖了我自己遇到过的绝大部分问题。实际排查的时候先看报错信息再对照这张表定位方向通常几分钟就能解决。6. 实操中的经验与避坑要点6.1 配置文件管理的几个细节opencode.json这个文件是三条路径的共同核心管理好它能省很多事。第一建议把配置文件纳入版本管理比如用 git 管理起来这样你换机器或者配置改乱了可以快速回滚。第二API Key 不要直接明文写在配置文件里然后提交到公开仓库可以用环境变量引用的方式把密钥放在环境变量里配置文件里只写变量名。第三改配置之前先备份一份尤其是你同时配了多个 provider 的时候改错一个字段可能导致整个配置失效。6.2 模型选择的实战心得模型不是越大越好也不是越新越好关键是匹配任务。我自己的经验是日常的代码补全和简单问答小模型完全够用响应还快代码审查和重构建议需要上下文长、推理能力强的模型涉及具体框架和库的问题选那些在代码数据上训练充分的模型。你可以准备两三个不同定位的模型根据任务切换而不是指望一个模型打天下。另外免费模型的可用性是动态变化的。今天能用的免费模型过段时间可能就收费了或者被下架了。所以定期检查一下你的配置里引用的模型是否还有效是很有必要的。我一般每个月会花几分钟确认一下。6.3 网络与硬件环境的准备如果你主要走 OpenRouter 这条路网络稳定性很重要。免费模型在高峰期可能会响应慢这时候不要反复重试容易触发限流。可以错峰使用或者配置一个备用模型。如果你走 Ollama 这条路硬件是瓶颈。显存决定了你能跑多大的模型内存决定了模型加载和切换的速度。如果条件允许给机器加一块显存大一点的显卡体验提升非常明显。如果只能用 CPU 跑那就选小模型并且接受相对慢的响应速度。6.4 关于 OpenCode 本身的使用OpenCode 作为一个终端工具它的优势在于和你的开发环境无缝集成。你可以在项目目录里直接启动它让它读取当前项目的代码上下文。热词里有人问opencode 在 windows 环境下什么 shell 工具好用这个取决于你的习惯PowerShell、Git Bash、WSL 都可以关键是确保 OpenCode 能正确调用到你环境里的命令。还有人提到opencode 只思考不回答这种情况通常是模型返回被截断或者配置的模型不支持某些输出格式导致的。换一个模型试试或者检查一下配置里的输出参数。三条路径我都跑通了现在日常用得最多的是 OpenRouter 加本地 Ollama 的组合。OpenRouter 负责需要强模型的任务Ollama 负责敏感代码和离线场景Zen 作为随手可用的兜底。这套组合跑下来基本没有遇到过因为额度或者网络问题而中断工作的情况。如果你刚开始折腾建议先从 Zen 跑通流程再逐步加上 OpenRouter 和 Ollama一步一步来比一上来就全配要稳得多。