1. 三条免费路径的底层逻辑与选型思路OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型能力塞进命令行让你不离开终端就能完成代码补全、重构建议、bug 排查这些事。但真正让很多人卡住的不是怎么用而是怎么用上免费模型。官方免费池有调用来源限制OpenRouter 有免费额度但需要配置本地 Ollama 则完全靠自己机器扛。这三条路各有各的脾气选错了就是反复报错、反复折腾。我自己前前后后把三条路径都跑了一遍踩了不少坑也总结出一些门道。这篇文章就把这三条路径的实操细节、配置方法、常见报错和排查思路完整拆开讲。不管你是刚接触 OpenCode 的新手还是已经在用但想换免费方案的开发者都能找到可以直接抄的配置。先说清楚这三条路径的本质区别。Zen 免费池是 OpenCode 官方提供的免费模型通道优点是零配置、开箱即用缺点是只能在 OpenCode 环境内调用换个终端或者脚本调用就会报opencodes free tier can only be used from within opencode这个经典错误。OpenRouter 免费模型是通过第三方聚合平台调用带:free后缀的模型优点是模型选择多、有免费额度缺点是需要注册获取 API Key而且免费额度有每日限制。本地 Ollama是把模型下载到自己机器上跑优点是完全离线、无调用限制、数据不出本地缺点是对硬件有要求下载模型慢配置不当还会遇到llama-server process相关的 500 错误。选哪条路取决于你的核心诉求。追求省事就用 Zen 免费池想要模型多样性就用 OpenRouter注重隐私和长期稳定就用 Ollama。下面逐条展开。2. Zen 免费池零配置上手与来源限制破解2.1 Zen 免费池到底是什么Zen 是 OpenCode 内置的模型服务层你可以把它理解成官方帮你搭好的一个模型中转站。它里面有一个免费池包含若干可用的模型不需要你填任何 API Key装好 OpenCode 就能直接调用。这对刚接触的人来说非常友好因为省去了注册账号、获取密钥、配置环境变量这一整套流程。但免费池有一个硬性限制只能在 OpenCode 自身的运行环境内调用。这句话的意思是如果你在 OpenCode 的交互界面里让它写代码没问题但如果你想用 curl 或者自己写的脚本去调这个免费池的接口就会直接被拒绝报错信息就是那句经典的opencodes free tier can only be used from within opencode。这个限制的设计意图也很明显防止有人把免费额度拿去薅羊毛做批量调用。2.2 安装与首次配置OpenCode 的安装方式根据系统不同有差异。在 macOS 和 Linux 上通常用包管理器或者官方提供的安装脚本Windows 环境下建议用 WSL因为原生 Windows 的 shell 兼容性会带来一些奇怪的问题。安装完成后第一次运行opencode命令它会引导你做一些基础配置。配置文件默认是opencode.json放在用户目录下的.config/opencode/或者项目根目录。这个文件决定了你用哪个模型、走哪条通道。如果你什么都不配默认就会走 Zen 免费池。这也是为什么很多人装完直接就能用因为默认路径就是免费的。{ model: zen-default, provider: zen }上面这个是最简配置。实际使用中你可能需要根据 OpenCode 的版本调整字段名因为 v2 版本之后配置结构有过变化。建议装完之后先跑一次opencode --version确认版本再对照官方文档看配置格式。2.3 免费池的模型能力边界免费池里的模型不是最强的但日常的代码补全、简单重构、解释代码片段这些任务完全够用。我实测下来写个 Python 脚本、改个 JavaScript 函数、解释一段 SQL响应速度和结果质量都在可接受范围内。但如果你要它做复杂的架构设计或者跨文件的大规模重构免费池的模型可能会力不从心回答会比较浅。这里有个实操心得免费池适合做“轻量级副驾驶”不适合做“重型架构师”。你把它当成一个随时能问的编程搭子就好别指望它帮你从零搭一个完整项目。2.4 来源限制的应对思路那个can only be used from within opencode的报错本质上是 OpenCode 在请求头里带了一个标识服务端校验这个标识来决定是否放行。所以你想绕过这个限制去外部调用基本走不通也不建议走。正确的做法是在 OpenCode 环境内用免费池在环境外用 OpenRouter 或者 Ollama。这三条路径本来就是互补的没必要死磕一条。如果你确实需要在脚本里调用模型那就直接看后面的 OpenRouter 和 Ollama 部分那两条路没有这个来源限制。3. OpenRouter 免费模型注册、密钥与配置全流程3.1 OpenRouter 的定位与免费额度机制OpenRouter 是一个模型聚合平台你可以把它理解成“模型超市”。它把各家厂商的模型集中到一个接口下你用一个 API Key 就能调用不同厂商的模型。对开发者来说最大的好处是不用分别去每家注册账号、分别管理密钥。OpenRouter 上有一批带:free后缀的模型这些就是免费模型。比如deepseek/deepseek-chat:free、meta-llama/llama-3-8b-instruct:free这类。免费模型的额度机制是按天限制请求次数具体次数会根据模型和平台政策调整。对于个人开发者日常使用这个额度通常是够的。需要注意的是免费模型和付费模型走的是同一套 API区别只在于模型名称后缀和额度限制。如果你某天免费额度用完了要么等第二天重置要么给账户充值继续用付费模型。OpenRouter 支持多种充值方式国内用户常用的支付渠道基本都能走通。3.2 获取 API Key 的完整步骤第一步访问 OpenRouter 官方入口注册账号。注册流程很标准邮箱加密码就行。第二步登录后在账户设置里找到 API Keys 页面点创建新密钥。创建的时候给它起个名字比如opencode-dev方便以后管理。第三步复制生成的密钥这个密钥只显示一次关掉页面就看不到了所以一定要先存好。密钥的格式通常是一串以sk-or-开头的字符串。拿到之后不要直接写在代码里也不要在聊天群里发因为任何人拿到这个密钥都能用你的额度。正确的做法是放到环境变量或者配置文件里。export OPENROUTER_API_KEYsk-or-你的密钥在 Windows 上可以用系统环境变量设置或者写进.env文件然后用工具加载。我个人的习惯是写进 shell 的配置文件里比如.zshrc或者.bashrc这样每次开终端自动加载。3.3 在 opencode.json 中接入 OpenRouter拿到密钥之后就要把它配置到 OpenCode 里。核心是修改opencode.json指定 provider 为 openrouter并填入对应的模型名称。{ provider: openrouter, model: deepseek/deepseek-chat:free, apiKey: ${OPENROUTER_API_KEY} }这里用${OPENROUTER_API_KEY}的方式引用环境变量而不是把密钥硬编码进去。这样做的好处是配置文件可以安全地分享或者提交到版本库密钥本身留在本地环境里。配置完成后重启 OpenCode然后随便问一个问题测试连通性。如果返回正常说明配置成功。如果报 401 错误说明密钥无效或者没加载到如果报 429 错误说明免费额度用完了等重置或者换模型。3.4 免费模型的选择策略OpenRouter 上的免费模型不少但质量参差不齐。我的选择策略是代码任务优先选代码能力强的模型通用问答选响应快的模型。比如做代码补全DeepSeek 系列的免费模型表现比较稳做文档解释或者简单问答Llama 系列的小参数模型响应更快。还有一个技巧是配置多个模型做 fallback。OpenCode 支持在配置里指定备用模型当主模型额度用完或者不可用时自动切换。这样能避免因为单个模型额度耗尽而中断工作。{ provider: openrouter, model: deepseek/deepseek-chat:free, fallbackModels: [ meta-llama/llama-3-8b-instruct:free ] }这个 fallback 机制在实际使用中很实用尤其是你连续工作几个小时、免费额度可能中途耗尽的时候。4. 本地 Ollama离线部署与模型管理4.1 为什么选择本地部署本地 Ollama 的核心价值是数据不出本地和无调用限制。你下载的模型跑在自己机器上所有请求都在本地完成不经过任何外部服务器。对于处理敏感代码或者不想受额度限制的人来说这是最优解。但代价也很明显吃硬件。模型参数越大对内存和显存的要求越高。一个 7B 参数的模型量化后大概需要 4 到 8 GB 内存13B 的模型需要 8 到 16 GB再往上就得看显卡了。所以选本地部署之前先确认自己的机器扛得住。4.2 安装与国内下载加速Ollama 的安装本身不复杂官网有各平台的安装包。但国内用户普遍会遇到一个痛点下载模型太慢。因为模型文件动辄几个 GB从官方源拉取速度可能只有几十 KB 每秒一个模型下半天。解决办法是配置国内镜像源。Ollama 支持通过环境变量指定镜像地址把下载源换成国内的加速节点速度能提升一个数量级。export OLLAMA_HOST127.0.0.1:11434 export OLLAMA_MODELS/path/to/models镜像源的配置方式根据 Ollama 版本有所不同有些版本通过OLLAMA_MODEL_MIRROR环境变量指定有些需要在配置文件里改。建议先查一下自己装的版本对应的文档。另外如果实在下载太慢也可以找离线安装包手动把模型文件放到模型目录里。4.3 模型选择与拉取Ollama 的模型库很丰富从 1B 到 70B 参数的模型都有。对于 OpenCode 的代码任务我推荐从这几个方向选模型参数量适用场景内存需求qwen2.5-coder:7b7B代码补全、重构约 6GBdeepseek-coder:6.7b6.7B代码生成、解释约 6GBllama3.1:8b8B通用问答、文档约 8GBqwen2.5:3b3B轻量问答、快速响应约 3GB拉取模型的命令很简单ollama pull qwen2.5-coder:7b拉取完成后用ollama list确认模型已经在本地。然后可以用ollama run qwen2.5-coder:7b直接测试看模型能不能正常响应。4.4 接入 OpenCode 的配置Ollama 默认在本地 11434 端口提供服务OpenCode 接入的时候provider 设为 ollama模型名填你拉取的模型。{ provider: ollama, model: qwen2.5-coder:7b, baseUrl: http://127.0.0.1:11434 }配置好之后重启 OpenCode测试一下连通性。如果报连接错误先确认 Ollama 服务在跑如果报模型不存在确认模型名拼写和ollama list的输出一致。4.5 那个 500 错误是怎么回事很多人会遇到ollama run qwen3.5:2b error: 500 internal server error: llama-server process这个报错。这个错误的根源通常是模型加载失败可能的原因有几个模型文件损坏、内存不足、Ollama 版本和模型不兼容。排查顺序是这样的先看 Ollama 的日志日志里会写清楚是加载哪一步失败的然后确认内存够不够用free -h或者任务管理器看再确认 Ollama 版本是不是太旧旧版本可能不支持新模型格式。如果都正常尝试删掉模型重新拉取。提示遇到 500 错误不要急着重装 Ollama先看日志。大部分情况下是模型文件或者内存的问题重装解决不了。5. 三条路径的对比与组合使用策略5.1 核心维度对比把三条路径放在一起对比能更清楚地看出各自的适用场景。维度Zen 免费池OpenRouter 免费模型本地 Ollama配置难度零配置需注册获取密钥需安装下载模型调用限制仅限 OpenCode 内每日额度限制无限制模型质量中等可选高质量模型取决于本地硬件数据隐私经过官方服务器经过第三方服务器完全本地硬件要求无无较高网络要求需要需要下载后离线可用适合场景快速上手模型多样性隐私敏感长期使用5.2 组合使用的最佳实践这三条路不是互斥的完全可以组合使用。我的建议是日常轻量任务走 Zen 免费池需要特定模型时切 OpenRouter处理敏感代码或者断网环境用 Ollama。在opencode.json里可以配置多个 provider然后通过命令或者快捷键切换。这样你就不用每次改配置文件直接在 OpenCode 里切换就行。{ providers: { zen: { type: zen }, openrouter: { type: openrouter, apiKey: ${OPENROUTER_API_KEY}, model: deepseek/deepseek-chat:free }, ollama: { type: ollama, baseUrl: http://127.0.0.1:11434, model: qwen2.5-coder:7b } }, defaultProvider: zen }这种多 provider 配置的好处是灵活。比如你在外面用笔记本网络一般就走 Zen回到工位有台式机切 Ollama 跑本地模型需要某个特定能力的时候切 OpenRouter。5.3 成本与效率的平衡从成本角度看Zen 免费池和 OpenRouter 免费模型都是零成本Ollama 的成本是电费和硬件折旧。从效率角度看Zen 最省事OpenRouter 需要管理密钥和额度Ollama 需要等模型下载和加载。我的实际体验是刚开始用 OpenCode 的时候直接用 Zen 免费池别折腾。等你用顺了发现某些任务免费池搞不定再去配 OpenRouter 或者 Ollama。不要一上来就三条路全配那样只会把自己绕晕。6. 常见报错与排查速查6.1 报错速查表报错信息可能原因解决方法free tier can only be used from within opencode在 OpenCode 环境外调用免费池改用 OpenRouter 或 Ollama401 UnauthorizedAPI Key 无效或未加载检查环境变量和密钥拼写429 Too Many Requests免费额度用完等重置或切换模型500 internal server error: llama-server process模型加载失败查日志、确认内存、重拉模型connection refusedOllama 服务未启动启动 Ollama 服务model not found模型名拼写错误对照ollama list确认opencode只思考不回答模型响应被截断或配置问题检查 maxTokens 配置换模型测试6.2 排查思路的通用框架遇到报错的时候不要盲目改配置。我的排查框架是先定位是哪一层的问题再针对性解决。第一层是网络层确认能不能连到服务端。用curl或者ping测试一下。第二层是认证层确认密钥或者 token 有没有问题。第三层是模型层确认模型名、模型文件、模型加载状态。第四层是应用层确认 OpenCode 的配置格式对不对。大部分报错都能通过这个框架快速定位。比如401是认证层500是模型层connection refused是网络层。6.3 几个容易忽略的细节第一个细节是配置文件的加载顺序。OpenCode 会先读全局配置再读项目配置项目配置会覆盖全局配置。所以如果你在项目里改了配置但没生效检查一下是不是被全局配置覆盖了。第二个细节是环境变量的作用域。你在终端里export的变量只对当前终端会话有效。换个终端窗口就没了。要持久化就写进 shell 配置文件。第三个细节是模型名称的大小写和分隔符。OpenRouter 的模型名用斜杠分隔Ollama 的模型名用冒号分隔写错了就会报模型不存在。这个看起来是小事但实际排查的时候很容易忽略。7. 实操心得与避坑经验7.1 关于 OpenCode 安装的几个坑Windows 环境下建议用 WSL原生 Windows 的 shell 工具兼容性确实一般。我在 Windows 上直接跑的时候遇到过路径解析错误和权限问题换到 WSL 之后就顺了。如果你非要在原生 Windows 上用建议用 PowerShell 7 而不是老版本的 cmd。安装完成后第一件事是确认版本因为不同版本的配置格式有差异。v2 之后配置结构变过网上有些老教程的配置格式已经不能用了。以官方文档为准别照搬博客里的老配置。7.2 关于免费额度的管理OpenRouter 的免费额度是按天重置的但具体重置时间点不是零点而是按你账户的创建时间算的。所以如果你某天额度用完了不一定是等到第二天零点而是等到你账户创建时间的那个时刻。这个细节官方文档里写得不太明显但实际用的时候会影响你的预期。另外免费模型的额度是按模型单独计算的不是所有免费模型共享一个池子。所以一个模型额度用完了可以换另一个免费模型继续用。这也是为什么我建议配置 fallback 模型列表。7.3 关于 Ollama 的性能调优Ollama 默认的并发数和上下文长度可能不适合你的机器。如果发现响应特别慢可以调整OLLAMA_NUM_PARALLEL和OLLAMA_CONTEXT_LENGTH这两个环境变量。并发数调低一点上下文长度按需设置能明显改善响应速度。还有一个技巧是用 GPU 加速。如果你的机器有独立显卡Ollama 会自动检测并使用。但有些情况下需要手动指定比如OLLAMA_GPU_LAYERS参数。GPU 加速之后推理速度能提升好几倍。7.4 关于模型选择的经验不要盲目追求大参数模型。7B 的代码模型在代码任务上的表现往往比 13B 的通用模型更好。因为代码任务需要的是代码语料的训练而不是通用知识的广度。选模型的时候看它的训练数据侧重比看参数量更有用。另外量化版本的选择也有讲究。Q4 量化在质量和体积之间平衡得比较好Q8 质量更高但体积翻倍Q2 体积小但质量下降明显。对于代码任务我建议至少用 Q4 以上的量化。7.5 一个实用的调试技巧当你怀疑是配置问题的时候先用最简单的配置测试。把opencode.json精简到只剩 provider 和 model 两个字段其他都删掉看能不能跑通。跑通了再逐步加回其他配置这样能快速定位是哪个配置项出的问题。这个“最小化复现”的思路在排查任何配置问题时都适用。不要在一堆配置里猜哪个有问题直接砍到最小然后逐个加回来。8. 不同场景下的路径选择建议8.1 新手入门场景刚接触 OpenCode什么都不想配直接用 Zen 免费池。装完就能用不需要注册任何账号不需要填任何密钥。先用起来感受一下 OpenCode 的工作方式再考虑要不要换其他路径。这个阶段的目标是建立使用习惯而不是追求模型质量。免费池的模型足够你完成日常的代码问答和简单补全。8.2 日常开发场景用了一段时间之后你会发现免费池在某些任务上不够用。这时候配 OpenRouter选一两个代码能力强的免费模型作为主力。配置好 fallback避免额度耗尽中断工作。这个阶段的目标是提升任务完成质量。OpenRouter 上的免费模型选择多能找到更适合代码任务的模型。8.3 隐私敏感场景如果你处理的代码涉及商业机密或者个人隐私不要走任何云端模型。直接上 Ollama把模型下载到本地所有推理都在本地完成。虽然硬件要求高一点但数据安全是无价的。这个阶段的目标是数据不出本地。Ollama 是唯一能满足这个要求的路径。8.4 离线环境场景有些开发环境是断网的比如内网服务器或者保密项目。这种情况下只能用 Ollama而且需要提前把模型文件下载好通过离线安装包的方式部署。这个阶段的目标是在无网络环境下使用 AI 能力。Ollama 的离线部署能力是其他两条路径不具备的。8.5 多环境切换场景如果你同时有多个使用环境比如公司电脑、个人笔记本、家里的台式机可以三条路径都配好根据环境切换。公司电脑走 Zen 或者 OpenRouter个人设备走 Ollama。这个阶段的目标是灵活适配不同环境。多 provider 配置能让你在不同环境下都有可用的模型通道。9. 配置文件的进阶玩法9.1 项目级配置与全局配置的配合OpenCode 支持项目级配置就是在项目根目录放一个opencode.json。这个配置会覆盖全局配置。利用这个机制你可以给不同项目配不同的模型。比如前端项目用一个模型后端项目用另一个模型。{ provider: openrouter, model: qwen/qwen-2.5-coder-32b-instruct:free, projectContext: frontend }这种项目级配置的好处是你切换到不同项目的时候OpenCode 自动用对应的模型不需要手动切换。9.2 用环境变量做多环境隔离如果你在多个环境用同一个配置文件可以用环境变量做隔离。比如在配置里引用${OPENCODE_MODEL}然后在不同环境设置不同的值。{ provider: openrouter, model: ${OPENCODE_MODEL} }在开发环境设置OPENCODE_MODELdeepseek/deepseek-chat:free在测试环境设置另一个模型。这样一份配置文件就能适配多个环境。9.3 配置的版本管理opencode.json建议提交到版本库但密钥不要提交。用环境变量引用密钥配置文件本身可以安全地分享。这样团队里每个人用同一份配置但各自的密钥独立。如果团队里有人不想配环境变量也可以用一个.env文件然后把它加到.gitignore里。OpenCode 支持从.env加载环境变量。10. 一些零散但有用的经验关于 OpenCode 的 skill 功能它允许你定义一些自定义的命令或者提示词模板。这个功能在重复性任务上很有用比如你经常需要让模型按照某个格式输出代码审查意见就可以定义一个 skill 来固化这个提示词。关于 OpenCode 在 STM32 代码开发上的使用嵌入式开发的代码补全和普通应用开发不太一样因为涉及很多寄存器操作和硬件相关的宏定义。这种情况下本地 Ollama 配合一个在嵌入式代码上训练过的模型效果会比通用模型好。关于 OpenRouter 的充值如果你免费额度用完了想充值支持多种支付方式。充值之后可以用付费模型付费模型的质量和稳定性都比免费模型好不少。如果长期使用充值其实比折腾免费额度更省时间。关于 Ollama 的 WebUI如果你不想在终端里跟模型交互可以装一个 WebUI 前端。这样能在浏览器里跟本地模型对话体验更接近 ChatGPT 那种界面。有些 WebUI 还支持中文界面和便携版部署起来很方便。最后说一个我自己的习惯我会在opencode.json里保留三条路径的配置但只启用其中一条。这样切换的时候只需要改一个字段不用重新写配置。而且当某条路径出问题的时候能快速切到另一条不耽误工作。