OpenCode 这个工具最近在开发者圈子里讨论度很高但真正让大多数人卡住的不是它本身怎么用而是怎么不花钱把它跑起来。我前前后后折腾了三种方案——Zen 免费池、OpenRouter 免费模型、本地 Ollama 部署中间踩了不少坑也总结了一些文档里不会写的经验。这篇文章就把这三条路径的完整实操过程拆开讲清楚包括配置文件的写法、常见报错的根因、以及不同场景下该怎么选。不管你是刚听说 OpenCode 想试试水还是已经装好了但卡在模型接入这一步下面这些内容应该都能帮你省下不少时间。1. 先搞清楚 OpenCode 的模型接入逻辑1.1 OpenCode 不是模型它是一个调度层很多人第一次接触 OpenCode 会有一个误解以为它自带模型能力。实际上 OpenCode 本身只是一个命令行交互层它负责把你的自然语言指令整理成请求然后转发给背后的模型提供方再把返回结果渲染出来。真正干活的是背后的模型OpenCode 做的是中间人的角色。这个定位决定了它的配置核心只有一个告诉它去哪里找模型。所有的配置文件、环境变量、命令行参数本质上都在解决同一个问题——请求发给谁、用什么密钥、走什么协议。理解了这一点后面三条路径的差异就很好理解了它们只是模型来源不同而已。OpenCode 支持的模型接入方式大致分两类。一类是走远程 API比如 Zen 免费池和 OpenRouter你的请求会发到对方的服务器上由对方的算力完成推理。另一类是走本地服务比如 Ollama模型跑在你自己机器上请求发到本地的端口。这两类在配置写法上有明显区别后面会分别展开。1.2 配置文件 opencode.json 的结构OpenCode 的核心配置文件是opencode.json一般放在项目根目录或者用户主目录下。它的结构不复杂但字段的层级关系容易搞混。一个典型的配置长这样{ provider: { openrouter: { npm: openrouter/ai-sdk-provider, options: { apiKey: sk-or-xxxxxxxx } } }, model: openrouter/anthropic/claude-3.5-sonnet }这里有几个关键点需要说清楚。provider下面定义的是提供方每个提供方有自己的 npm 包和配置项。model字段指定当前默认用哪个模型格式是提供方/模型名。这个斜杠分隔的写法是 OpenCode 的约定写错了就会报找不到模型的错。还有一个容易忽略的点opencode.json支持项目级和全局级两层配置。项目级的放在项目根目录只对当前项目生效全局级的放在用户主目录下的.config/opencode/目录里对所有项目生效。如果你在多个项目里用不同的模型这个分层机制就很有用。我一般把常用的提供方配置放在全局把项目特定的模型选择放在项目级。1.3 三条路径的适用场景对比在动手之前先想清楚你适合哪条路。这三条路径不是互斥的你可以同时配置多个提供方用的时候切换就行。但初次上手建议先跑通一条再说。路径算力来源是否需要密钥网络要求适合场景Zen 免费池远程需要登录能访问 Zen 服务快速体验、轻量任务OpenRouter 免费模型远程需要 API Key能访问 OpenRouter需要多种模型切换本地 Ollama本机不需要无隐私敏感、离线使用Zen 免费池的优势是开箱即用登录后就能用缺点是免费额度有限制而且有使用环境的约束。OpenRouter 的优势是模型选择多免费模型虽然有限速但够日常用缺点是需要注册和获取密钥。Ollama 的优势是完全本地、数据不出机器、没有额度限制缺点是对硬件有要求而且首次下载模型可能比较慢。我个人的建议是先用 Zen 免费池跑通流程确认 OpenCode 本身没问题然后配一个 OpenRouter 作为日常主力如果对隐私有要求或者经常断网再折腾 Ollama。2. Zen 免费池最省事的起步方式2.1 Zen 免费池到底是什么Zen 是 OpenCode 官方提供的一个模型接入服务里面有一个免费池登录后可以直接调用一些基础模型。它的定位很像新手体验包——不需要你注册第三方账号不需要自己搞密钥登录一下就能用。但这里有个关键限制也是很多人踩坑的地方免费池只能在 OpenCode 环境内部使用。也就是说你不能把 Zen 免费池的密钥拿出来放到别的工具里去调用。这个限制是服务端做的校验不是配置文件能绕过的。网上有些帖子说提取密钥就能到处用实测下来是不行的会直接报错。这个限制的存在其实合理。免费池的算力是官方补贴的如果允许外部调用很容易被滥用。理解这一点之后你就不会在为什么我的密钥在别处用不了这个问题上浪费时间了。2.2 登录与初始化的完整流程Zen 免费池的使用流程比想象中简单但有几个步骤的顺序不能乱。第一步是安装 OpenCode。不同系统的安装方式不一样常见的是通过包管理器或者直接下载二进制。安装完成后在终端里输入opencode能看到交互界面说明安装成功。第二步是登录。在 OpenCode 的交互界面里一般会有登录相关的命令或者菜单项。执行登录后它会引导你完成认证流程。这个过程会打开浏览器或者给出一个链接你需要在浏览器里完成授权。第三步是确认免费池可用。登录成功后OpenCode 会自动把 Zen 作为可用的提供方之一。你可以在模型选择列表里看到免费池里的模型。如果看不到检查一下是不是登录状态失效了重新登录一次通常能解决。注意登录状态是有有效期的。如果你隔了很长时间没用可能会发现免费池突然不可用了这时候先别急着改配置重新登录一下往往就好了。2.3 免费池的额度限制与报错处理免费池虽然免费但不是无限用的。它一般有每日额度或者并发限制。用超了之后请求会被拒绝返回一个额度相关的错误。最常见的报错是提示免费层只能在特定环境内使用。这个报错通常出现在两种情况下一是你试图在 OpenCode 之外调用二是你的 OpenCode 版本太旧服务端识别不了。前者无解后者升级一下版本就行。还有一种情况是请求频率太高被限流。免费池的并发能力有限如果你短时间内发大量请求会被暂时限制。这时候等几分钟再试或者降低请求频率一般就能恢复。我的经验是把 OpenCode 的请求间隔调大一点或者把大任务拆成小任务分批做能有效避免触发限流。如果遇到报错先看错误信息里的关键词。如果是free tier相关的基本就是环境限制或者额度问题如果是timeout或者connection相关的那是网络问题跟免费池本身没关系。分清楚这两类排查方向就不会错。3. OpenRouter 免费模型灵活度最高的方案3.1 OpenRouter 的定位和免费模型机制OpenRouter 是一个模型聚合平台它把很多不同厂商的模型统一到一个接口下。你只需要一个 API Key就能调用平台上各种模型包括一些免费的。这个模式的好处是省去了分别注册各家账号的麻烦一个密钥走天下。OpenRouter 上的免费模型通常带一个:free后缀比如某些开源模型的免费版本。这些免费模型的特点是不收费但有限速而且可能有每日调用次数上限。对于日常的代码问答、简单重构这类任务免费模型完全够用。需要说明的是免费模型的可用性是动态变化的。平台会根据算力情况调整哪些模型免费、免费额度多少。所以你今天能用的免费模型过段时间可能就变了。这不是你配置的问题是平台策略调整遇到这种情况换个免费模型就行。3.2 获取 API Key 与充值注意事项获取 OpenRouter 的 API Key 流程不复杂注册账号进入控制台创建一个新的 Key。创建的时候可以设置额度上限这个功能建议用上避免意外超支。关于充值这里要提醒一句OpenRouter 的付费和免费是两套体系。你充值了不代表免费模型就变成无限用了免费模型依然受限速约束。充值的意义在于解锁付费模型以及提高整体的请求优先级。如果你只用免费模型其实不充值也能跑。支付方式上OpenRouter 支持多种渠道。如果你要用付费模型建议先小额充值测试一下支付流程是否顺畅确认没问题再充大额。我见过有人一次性充了不少结果发现某个支付渠道有问题退款流程又比较麻烦。API Key 的管理有个细节不要把所有权限都开给一个 Key。OpenRouter 支持给 Key 设置细粒度的权限和额度建议按用途分开创建。比如一个 Key 专门给 OpenCode 用设置一个合理的额度上限这样即使 Key 泄露损失也可控。3.3 在 opencode.json 里配置 OpenRouter配置 OpenRouter 的关键是写对 provider 和 model 两个字段。一个可用的配置示例{ provider: { openrouter: { npm: openrouter/ai-sdk-provider, options: { apiKey: sk-or-v1-你的密钥 } } }, model: openrouter/deepseek/deepseek-chat-v3-0324:free }几个容易出错的地方。第一npm字段的值必须是正确的包名写错了 OpenCode 找不到对应的适配器。第二apiKey要填完整的密钥不要有多余的空格。第三model字段里的模型名要跟 OpenRouter 平台上的一致包括:free后缀不能漏。如果你想让密钥不写在配置文件里可以用环境变量的方式。OpenCode 支持从环境变量读取密钥配置里写变量名就行。这样做的好处是配置文件可以提交到版本控制而密钥留在本地环境里不会泄露。配置完成后重启 OpenCode在模型列表里应该能看到你配置的 OpenRouter 模型。如果看不到检查一下 JSON 格式有没有语法错误——JSON 对逗号和引号很敏感多一个少一个都会导致解析失败。3.4 免费模型的限速应对与模型切换免费模型的限速是绕不开的。常见的表现是连续请求几次之后开始返回限流错误需要等一段时间才能恢复。应对限速有几个思路。一是降低请求频率把任务拆细中间加一点间隔。二是准备多个免费模型作为备选一个被限了就换另一个。三是把不紧急的任务放到低峰时段做比如深夜这时候平台负载低限速触发得少。在 OpenCode 里切换模型很方便改一下model字段就行。我一般会准备两三个免费模型的配置注释掉不用的需要时切换。这样比每次重新查模型名要快。还有一个小技巧把常用的模型配置写成多个 provider 条目每个条目用不同的名字然后在model里引用。这样切换的时候只需要改一个字段不用动 provider 部分。4. 本地 Ollama数据不出机器的方案4.1 为什么选 Ollama 而不是其他本地方案本地跑模型的选择不少Ollama 的优势在于它把模型下载、加载、服务化这几件事打包得很顺。你不需要关心模型格式转换、推理引擎配置这些底层细节装好之后一条命令就能跑起来。对于 OpenCode 来说Ollama 提供的是标准的本地 HTTP 接口OpenCode 通过这个接口把请求发过去。这意味着只要 Ollama 在跑OpenCode 就能用不依赖任何外部网络。这对隐私敏感的场景很重要——你的代码和问题不会离开你的机器。另一个优势是模型选择灵活。Ollama 的模型库里有各种尺寸的模型从几 GB 的小模型到几十 GB 的大模型都有。你可以根据自己机器的配置选合适的。显存小就选小模型显存大就选大模型这个自由度是远程服务给不了的。4.2 安装 Ollama 与国内下载加速Ollama 的安装本身不复杂官网有各系统的安装包。但国内用户普遍会遇到一个问题下载模型太慢。模型动辄几个 GB从官方源拉取经常龟速甚至断连。解决办法是配置国内镜像源。Ollama 支持通过环境变量指定模型下载的源。设置好镜像源之后下载速度会有明显提升。具体的镜像地址会变化建议用之前先搜一下当前可用的源。除了镜像源还有一个办法是手动下载模型文件然后导入。Ollama 支持从本地文件加载模型如果你能从别的渠道拿到模型文件可以跳过在线下载这一步。这个方式适合网络条件特别差的情况。安装完成后用ollama --version确认一下版本。然后跑一个最小的模型测试比如ollama run加一个小参数量的模型看看能不能正常对话。这一步能跑通说明 Ollama 本身没问题接下来就是跟 OpenCode 对接的事。提示首次运行某个模型时Ollama 会先下载模型文件这个过程可能比较久。建议在开始之前确认磁盘空间充足模型文件通常放在用户目录下的隐藏文件夹里。4.3 模型选择参数量、显存与速度的平衡选本地模型的核心矛盾是参数量越大效果越好但占的显存越多、跑得越慢。你需要根据自己的硬件找一个平衡点。一个粗略的参考7B 级别的模型量化后大概需要 4-6 GB 显存13B 级别需要 8-10 GB30B 以上基本要 20 GB 往上了。如果你的显存不够模型会退化到用内存跑速度会慢很多。对于代码任务我的经验是 7B 到 14B 之间的模型性价比最高。再小的模型代码能力明显不足再大的模型对硬件要求太高。具体选哪个建议多试几个用同一段代码问题对比效果。还有一个容易被忽略的点是量化等级。同一个模型有不同的量化版本量化等级越高模型越小、越快但效果损失也越大。一般 Q4 量化是效果和体积的较好平衡点Q5、Q6 效果更好但更占空间。如果你的显存紧张优先降量化等级而不是降参数量因为参数量对能力的影响更大。4.4 把 Ollama 接入 OpenCode 的配置写法Ollama 的接入配置跟远程服务不太一样因为它是本地服务不需要密钥但需要指定本地地址。一个典型的配置{ provider: { ollama: { npm: ai-sdk/openai-compatible, options: { baseURL: http://localhost:11434/v1 }, models: { qwen2.5-coder:7b: {} } } }, model: ollama/qwen2.5-coder:7b }这里的关键是baseURL指向 Ollama 的本地接口默认端口是 11434。models字段里列出你要用的模型名这个名字要跟ollama list命令显示的一致。配置好之后确保 Ollama 服务在运行。Ollama 安装后一般会作为后台服务常驻如果没有手动启动一下。然后在 OpenCode 里选择对应的模型发一个测试请求看能不能正常返回。如果报连接错误先确认 Ollama 服务是不是在跑用浏览器或者 curl 访问一下http://localhost:11434看有没有响应。如果服务正常但 OpenCode 连不上检查一下配置里的地址和端口有没有写错。5. 三条路径的实测对比与选择建议5.1 响应速度与稳定性对比我把三条路径在同样的任务上跑了一遍记录了大致的体验差异。需要说明的是这些数据受网络环境、机器配置、平台负载影响很大仅供参考。维度Zen 免费池OpenRouter 免费本地 Ollama首次响应快中等取决于模型加载连续对话稳定偶有限流稳定长文本处理一般较好取决于模型断网可用否否是数据隐私请求外发请求外发完全本地Zen 免费池的响应速度在免费方案里算不错的但额度限制比较明显适合轻量使用。OpenRouter 的免费模型在非高峰时段体验很好但高峰期限流会比较频繁。本地 Ollama 的响应速度完全取决于你的硬件配置够的话体验最稳定配置不够就会很慢。5.2 成本与隐私的权衡成本这块三条路径的免费方案都是零直接支出但隐性成本不同。Zen 免费池的隐性成本是额度限制带来的时间成本OpenRouter 免费模型的隐性成本是限流导致的等待本地 Ollama 的隐性成本是硬件投入和电费。隐私这块本地 Ollama 是唯一数据不出机器的方案。如果你处理的是公司内部代码或者敏感信息这一点很关键。远程方案无论怎么配置请求都要经过对方的服务器这是架构决定的不是配置能改变的。我的建议是分场景用日常学习、开源项目用远程免费方案省事涉及敏感代码或者需要离线工作时切到本地 Ollama。OpenCode 支持多提供方配置切换成本很低没必要只认一条路。5.3 常见报错的排查思路把三条路径常见的报错整理一下方便对照排查。报错关键词可能原因处理方向free tier / 环境限制免费池环境校验失败确认在 OpenCode 内使用升级版本401 / unauthorized密钥错误或过期检查密钥重新生成429 / rate limit请求频率过高降低频率切换模型connection refused本地服务未启动启动 Ollama检查端口model not found模型名写错核对模型名注意后缀JSON parse error配置文件语法错误检查逗号、引号、括号排查的核心思路是先定位问题在哪一层是配置层、网络层还是服务层。配置层的错误通常是格式问题看报错信息里的行号就能定位。网络层的错误表现为超时或连接失败检查网络连通性。服务层的错误是对方返回的业务错误看错误码和描述。6. 几个文档里不会写的实操经验6.1 配置文件的多环境管理如果你在多个机器上工作配置文件的管理会是个问题。我的做法是把配置拆成两部分不含密钥的模板提交到版本控制含密钥的部分用环境变量注入。这样换机器的时候拉下模板设置好环境变量就能直接用。OpenCode 支持从环境变量读取配置项具体写法是在配置里用变量引用语法。不同版本的语法可能略有差异用之前查一下当前版本的文档。这个机制的好处是密钥不落盘安全性更好。6.2 模型切换的自动化频繁切换模型很烦尤其是要在几个免费模型之间轮换避开限流的时候。我写了一个简单的小脚本检测到限流错误就自动切换到下一个模型。这个脚本不复杂核心就是解析错误信息然后改配置文件里的 model 字段。如果你不想写脚本也可以用 OpenCode 的命令行参数在启动时指定模型这样不用改配置文件。适合临时切换的场景。6.3 本地模型的预热本地 Ollama 有个特点模型首次加载比较慢加载完之后连续对话就快了。如果你知道接下来要用某个模型可以提前发一个简单的请求把它预热这样正式用的时候就不用等加载了。还有一个技巧是保持 Ollama 服务常驻不要频繁重启。模型加载到显存后只要服务不重启模型就一直在后续请求都是秒回。频繁重启会导致每次都要重新加载体验很差。6.4 免费额度的合理规划免费额度是有限的怎么用有讲究。我的做法是把任务分级简单的、探索性的问题用免费额度复杂的、需要多轮迭代的任务攒着等有付费额度或者本地环境准备好了再做。这样能把有限的免费额度用在刀刃上。另外免费额度通常按天重置。如果你知道今天额度用完了可以把不急的任务留到明天。规划好使用节奏免费方案也能撑起日常开发的大部分需求。7. 从零到跑通的完整检查清单7.1 安装阶段的检查点安装 OpenCode 之后先别急着配模型确认几个基础项命令行能正常启动、版本不是太旧、配置文件目录存在。这几项没问题再往下走。Ollama 的安装检查点类似服务能启动、命令行能执行、能跑通一个最小模型。如果最小模型都跑不起来先解决 Ollama 本身的问题别急着跟 OpenCode 对接。7.2 配置阶段的检查点配置文件的检查重点是 JSON 语法。建议用编辑器的 JSON 校验功能或者用命令行工具验证一下。语法错误是最常见的配置问题而且报错信息有时候不够直观提前校验能省很多事。配置写完后用 OpenCode 的模型列表功能确认一下配置有没有被正确加载。如果列表里没有你配的模型说明配置没生效检查文件路径和格式。7.3 首次请求的验证方法第一次发请求建议用最简单的任务比如让它回答一个简单问题。这样能快速确认链路是否通畅而不用等一个复杂任务跑完才发现有问题。如果首次请求失败按前面说的分层思路排查先看配置再看网络最后看服务。大部分问题都出在配置层尤其是密钥和模型名这两项。跑通之后建议把可用的配置备份一下。免费模型和免费额度的政策会变今天能用的配置过段时间可能需要调整。有个备份调整的时候有参照。三条路径我都实际跑过一段时间最后稳定下来的组合是OpenRouter 免费模型作为日常主力本地 Ollama 作为隐私场景的备选Zen 免费池偶尔用来快速验证一些想法。这个组合的好处是既有远程方案的便利又有本地方案的兜底不会因为某一条路径出问题就完全没法工作。如果你刚开始折腾建议也按这个思路来先把一条跑通再逐步加第二条不用一上来就追求全都配好。