OpenCode 免费模型全攻略：Zen 免费池、OpenRouter 与本地 Ollama 三路配置实战

做终端 AI 编程助手这一年多，我试过不少工具，OpenCode 算是我翻牌频率最高的一款。它开源、轻量、直接在终端里干活，最关键的是它对"免费模型"的支持相当友好。网上聊 OpenCode 免费方案的人不少，但大多只讲其中一条路，很少有人把 Zen 免费池、OpenRouter 免费模型、本地 Ollama 这三条路径放在一起系统讲清楚。这篇文章就专门聊这个：三者分别怎么配置、各有什么限制、踩过哪些坑、日常怎么切换最省钱，我会把实际操作过程完整捋一遍，保证你看完能直接照着做。

适合读这篇的人，主要是这三类：一是学生党，掏钱买大模型 API 肉疼，想先白嫖足够的编程能力；二是刚接触 AI 编程助手的开发者，想找个免费入口试水，看看 OpenCode 到底好不好用；三是公司代码保密要求高、或者网络环境不稳定的开发者，倾向本地部署开源模型，让 AI 编程完全回归离线。这三类需求，刚好对应三条路径。

1. 内容整体设计与思路拆解：为什么是这三条路

1.1 OpenCode 是什么，为什么人人都想白嫖模型

OpenCode 本质上是一个运行在终端里的 AI 编程代理，你给它下指令，它会在你的项目目录里读代码、改文件、跑命令，像一个坐在你旁边帮你写代码的工程师。相比网页版助手，它的优势是能直接操作真实项目，上下文自动挂载，不需要复制粘贴整个代码库；相比 Cursor 这类全家桶，它又足够轻，一个终端窗口加一个配置文件就能跑起来。

工具本身是开源免费的，成本主要取决于你调用的模型。OpenAI、Anthropic 这类官方 API 按 token 计费，写个大一点的模块可能就是几块钱甚至几十块钱人民币。所以我周围几乎所有人拿到 OpenCode 后的第一反应都一样：能不能配个免费模型用？答案是可以，而且不止一种方式。OpenCode 的架构天然支持多 provider，你可以把它理解成一台电视，Zen、OpenRouter、Ollama 分别是不同的信号源，插上哪个线就能看哪个台的节目，切换成本很低。

1.2 三条免费路径的定位差异

这三条路径虽然都是"免费"，但定位完全不同，很久之前我第一次接触时也混淆过。

Zen 免费池是 OpenCode 生态里内置的免费体验入口，我习惯把它叫作"官方蹭饭通道"。它由 OpenCode 平台维护，底层复用多个开源模型，好处是你几乎不需要配置，跟着初始化向导走就能开始用，坏处是限制多、模型可选项少、随时可能限流。

OpenRouter 是第三方模型聚合服务，相当于"模型百货超市"。免费模型是各家开源模型提供方放上去的，标着:free后缀，你用同一个 API Key 就能调用不同厂商的模型。这条路适合那些对模型有选择权诉求的人，比如想试试 DeepSeek、Qwen 的编程能力差异。

Ollama 则是把开源模型拉到本地跑，不需要任何外部 API，你的电脑本身就是算力提供方。这条路没有网络依赖、没有隐私风险，代价是你的硬件得扛得住。三者并不互斥，我现在的用法是把它们配在同一个 OpenCode 里，按场景切换。

1.3 免费机制背后的思路

理解这三条路径之前，先搞清楚"免费"为什么可以成立。

Zen 免费池之所以限制"只能从 OpenCode 内部调用"，是因为它本质上是 OpenCode 官方用来引流和降低体验门槛的成本投入，你直接拿着它暴露出来的接口去外部刷，相当于绕过平台薅羊毛，自然会被拦截。这个限制既保护服务不被滥用，也方便平台统计真实用户数据。

OpenRouter 的免费模型成本不是 OpenRouter 自己担的，而是模型提供方或社区赞助算力，所以每个免费模型都有每日请求上限、速率限制，高峰期甚至直接下线，这也是免费额度波动大的原因。

Ollama 的"免费"最纯粹，因为算力、电费、时间都是你自己的，你不欠任何人，所以没有任何外部限制，只受限于你的 GPU 和内存。想明白这三层逻辑，你就知道遇到限流时该先责怪谁，以及怎么调整预期。

2. 路径一：先用 Zen 免费池，开箱即用的官方入口

2.1 Zen 免费池的限制和报错原理

Zen 免费池是条最省事的路，但对它的限制必须先心里有数。第一次用的人经常遇到这个报错：

error from provider (console): opencode's free tier can only be used from within opencode

这句话翻译过来是"OpenCode 的免费套餐只能从 OpenCode 内部使用"。出现这个报错通常有两个原因。第一，你确实绕过了 OpenCode，比如把 Zen 免费池的接口地址填到了别的工具里，或者用 curl 直接请求，平台识别出请求来源不是 OpenCode 客户端，直接拒绝。第二，你在 OpenCode 内使用时，token 或配置来源异常，比如从某个自动生成配置的网页复制了一段残缺的 provider 配置，导致客户端没携带正确的标识头。

实际使用中 Zen 免费池还有频率限制和时段波动。我曾经遇到过早上开工两小时一切正常，到下午连续几个难题后请求直接 429，等十来分钟又恢复了。这不是故障，就是触发了限流。正常使用计划任务没问题，拿它当没有限制的付费接口去刷，迟早会被封。

2.2 零成本跑通 OpenCode 加 Zen 的具体步骤

第一步先装 OpenCode。macOS 和 Linux 可以用官方安装脚本，Windows 环境更推荐走 npm 安装，因为脚本在 Windows 下偶尔会遇到权限问题：

curl -fsSL https://opencode.ai/install | bash # 或者 npm install -g opencode-ai

装完在终端输入opencode --version能看到版本号，说明安装成功。第一次运行就进入初始化向导，它让你选 provider，这时候直接选 Zen，然后它会自动帮你把免费池配置写好。整个过程不需要你注册账号，也不需要 API Key，真心是零成本。

配置写完保存在opencode.json里，通常在用户目录或者项目根目录。如果你用手动配置，一个最简化的 Zen 配置大概长这样，具体字段名以你下载到的版本为准：

{ "provider": { "zen": { "name": "OpenCode Zen Free Pool", "options": { "baseURL": "https://opencode.ai/v1" }, "models": { "default": { "name": "Zen Default" } } } } }

启动后你在项目目录里执行opencode，它会进入交互式会话。直接输入任务，比如"帮我把这个目录下的工具函数补上错误处理"，它会先读取项目结构，再调用 Zen 免费池的模型来写代码。用对话循环里的/status可以查看当前会话消耗，/models能列出当前 provider 支持的所有模型。

2.3 免费池的用量管理技巧

Zen 免费池的额度是看不见具体数字的，但你能通过行为感知到。我用下来的经验是，把大任务拆成小任务，反而更省额度也更不容易触发限流。比如不要一次性丢给它十个文件的重构需求，而是拆成"先分析调用链"、"再改接口定义"、"最后替换实现"三步，每一步生成的结果也更扎实。

另外强烈建议在改动代码前先让它输出方案。OpenCode 有 plan 模式，在这个模式下模型只做分析和规划，不直接改文件，等方案确认后再执行。这个操作对免费额度而言是"省流"的：如果方案思路错了，你损失的只是一次分析，而不是一连串失败的代码修改。

3. 路径二：OpenRouter 免费模型，模型自由的第一站

3.1 OpenRouter 是什么，免费模型从哪来

OpenRouter 是一个模型聚合平台，一个 Key 访问几百个模型。它自己不出模型，而是把各家的开源模型、部分闭源模型统一封装成 OpenAI 风格的 API，开发者不用为每个模型单独注册服务商。对 OpenCode 用户来说，OpenRouter 最大的价值就是它提供了大量:free后缀的免费模型。

这些免费模型里有不少编程能力相当能打的，比如 DeepSeek 系列、Qwen 系列、Llama 系列，它们的选择逻辑和官方 API 略有不同。免费模型之所以免费，是因为提供方希望收集使用反馈、积累社区口碑，所以你不要指望它和付费版完全一致，实测下来，免费版的稳定性确实波动更大，尤其是晚高峰时段。

3.2 注册、获取 API Key 与小额充值

路径二的第一步是去 OpenRouter 官网注册账号。注册不需要什么特殊门槛，邮箱即可。登录后进入 Keys 页面，点击创建 Key，会生成一串以sk-or-v1-开头的字符串，这就是你的 API Key，注意它只在创建时完整展示一次，页面刷新后就只能看到部分字符了。

拿到 Key 后，我建议不要直接写进配置文件的明文里，而是用环境变量管理。在.bashrc或.zshrc里加上：

export OPENROUTER_API_KEY="sk-or-v1-你创建的key"

这样既安全，又方便在多个工具之间复用。关于充值，很多人看到"充值"两个字就犹豫，其实 OpenRouter 支持灵活的按量付费，而且很便宜。如果你只是偶尔免费模型不够用，充个几美元就能解锁更强的付费模型，用不完的余额还在。当然，纯白嫖玩家可以完全跳过充值，免费模型够你日常写代码了。

3.3 OpenCode 接入 OpenRouter 的实操配置

OpenCode 接入 OpenRouter 有两种方式，命令行直接指定最方便：

opencode --provider openrouter --model deepseek/deepseek-chat:free

另一种是在opencode.json里写完整配置，这样以后启动时不用每次带参数。示例配置如下：

{ "provider": { "openrouter": { "name": "OpenRouter", "options": { "baseURL": "https://openrouter.ai/api/v1", "apiKey": "{env:OPENROUTER_API_KEY}" }, "models": { "deepseek/deepseek-chat:free": {}, "qwen/qwen3:free": {} } } } }

配置里的apiKey用{env:OPENROUTER_API_KEY}引用环境变量，而不是明文写死 Key，这是个容易被忽略但很重要的习惯。配置完成后重启 OpenCode，用/models应该能列出你配置的两个模型。我在实操中遇到过一个坑：如果 OpenCode 内置的 provider 列表里已经有 OpenRouter 的预置配置，而你又在opencode.json里重复定义同名 provider，有时会覆盖掉预置配置里的模型列表，导致模型找不全。解决办法就是只保留一处定义，优先用项目配置文件统一管理。

3.4 免费模型选择建议

如果你刚开始用，我建议优先试这几个免费模型，我按编程场景排了序：

模型选择其实不是越多越好，我建议你在opencode.json里只保留两到三个常用的免费模型，这样/models列表干净，切换快。如果某个模型返回404或model not found，基本都是模型 ID 拼写问题，去 OpenRouter 官网模型列表页复制完整 ID，别手敲。

4. 路径三：本地 Ollama 部署，数据不出门的终极选择

4.1 Ollama 是什么，为什么本地路线值得认真做

Ollama 是我个人最欣赏的一个开源项目，它的目标就是"简化本地大模型运行"。你不需要懂 CUDA 配置、不需要手动下载权重文件，一条命令就能把几 GB 到几十 GB 的模型拉下来跑。它自带一个 OpenAI 兼容的本地 API 服务，默认地址是http://localhost:11434/v1，这意味着像 OpenCode 这类工具都可以通过接口直接对接。

选择本地路线的理由，对我而言最核心的是隐私和成本。公司内部项目、未公开的算法代码，往第三方 API 传一次就多一分泄露风险，本地跑模型数据完全不出内网。长期来看，如果你每天都在高频使用 AI 编程助手，本地电费远低于 API 费用。当然，本地路线的代价也很明显——你的电脑配置决定模型上限。

4.2 安装 Ollama 与解决下载慢的实际经验

安装 Ollama 的第一步是去官网下载对应系统的安装包。很多人卡在这一步，下载速度感人。我记得第一次下载 macOS 安装包时，进度条几乎纹丝不动，一度以为网络断了。后来发现解决办法没有那么玄学，就是换一个网络源，或者直接配置环境变量指向镜像仓库。

安装完成后在终端验证：

ollama --version

macOS 版本安装后会自动在后台运行服务，Linux 可能需要手动执行ollama serve启动。启动成功的标志是访问http://localhost:11434能返回一个文本页面，告诉你 "Ollama is running"。

4.3 下载模型与硬件匹配的实操记录

Ollama 安装好之后，下一步就是拉模型。我推荐从这几个开始：

ollama pull qwen3:8b ollama pull deepseek-r1:7b

qwen3:8b是目前本地编程任务里性价比很高的选择，8B 参数量在代码补全和简单重构上表现不错；deepseek-r1:7b是推理增强模型，适合让模型先分析再写码的场景。

模型下载同样可能遇到速度问题。一个有效做法是在启动服务前设置代理环境变量或镜像源指向，让模型文件从更快的位置拉取。下载完成后ollama list可以看到本地已安装的模型列表，ollama run qwen3:8b可以直接在终端里聊天测试效果。

硬件匹配上，8B 模型量化后大概 4.7GB，建议内存至少 16GB，不然会频繁交换内存，响应慢到怀疑人生。如果你只有 8GB 内存，可以考虑更小的qwen3:4b或者tinyllama，虽然能力弱一些，但至少能用。

4.4 OpenCode 对接 Ollama 的完整配置

Ollama 自己跑起来之后，OpenCode 对接非常直接。核心思路是把 Ollama 当成一个 OpenAI 兼容的本地服务。在opencode.json里配置：

{ "provider": { "ollama": { "name": "Ollama Local", "options": { "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" }, "models": { "qwen3:8b": {} } } } }

注意这里的apiKey随便填一个字符串占位就行，Ollama 本地接口不校验 Key，但 OpenAI 兼容格式要求这个字段存在。baseURL必须指向localhost:11434/v1，少写/v1会报路径错误。

配置完启动 OpenCode，选择ollama/qwen3:8b模型，就可以开始本地 AI 编程了。实测感受：简单脚本、函数重命名、单文件重构，本地 8B 模型的完成度完全够用；但让它跨多模块设计接口、理解复杂业务逻辑时，明显不如云端大模型。我的建议是，本地模型负责"快、碎、密"的小任务，云端模型负责"大、全、深"的复杂任务。

4.5 本地部署的三个常见坑

第一个坑是模型名不匹配。OpenCode 配置里写的模型名必须和ollama list输出的完全一致，多一个冒号少一个冒号都不行。我之前把qwen3:8b写成了qwen3:8b-instruct，调用直接报模型不存在。

第二个坑是服务没启动。Linux 环境下如果忘了执行ollama serve，OpenCode 连接时会报ECONNREFUSED，本地 11434 端口无响应。排查顺序：先 curlhttp://localhost:11434/v1/models看看通不通，再检查 OpenCode 配置。

第三个坑是跨设备调用。如果你还有一台性能更强的机器跑 Ollama，想在笔记本上用 OpenCode 远程连它，把baseURL改成那台机器的局域网 IP 加端口，比如http://192.168.x.x:11434/v1，同时需要确保 Ollama 服务端设置了允许外部访问的环境变量，否则默认只监听 127.0.0.1，外部机器连不上。

5. 三条路径的选择逻辑与避坑清单

5.1 我个人的日常切换策略

三条路线都配好后，日常使用就是按场景做选择题，这几乎成了我的肌肉记忆。

写小工具脚本、做算法题、调正则表达式这类任务，我用 Zen 免费池，因为它零配置、响应快，适合高频小任务。做项目前期方案设计、生成项目脚手架、跨文件重构这类重活，我切到 OpenRouter 的 DeepSeek 免费模型，它的上下文理解更扎实，生成代码结构更完整。而处理公司私有项目、客户代码，或者单纯不想被网络波动干扰的时候，就切到本地 Ollama。切换的方式很简单，OpenCode 会话里/models直接换，或者在启动时用--provider指定，不用改配置文件。

这种切换不是凭感觉，而是我踩过几次坑后的总结。最开始我只用 Zen 一个免费池，结果遇到一次大规模限流，整整半天效率为零；后来全切到 OpenRouter 免费模型，结果又赶上它某个热门模型临时下线；直到把本地 Ollama 作为兜底，才真正觉得手里有了完整方案。

5.2 高频报错速查表

以下是我整理的高频报错速查表，遇到问题直接对着查：

5.3 省钱与效率平衡的实战心得

最后聊点真正值钱的经验。免费模型的最大限制不是能力，而是不可控的可用性。为了和它共处，我总结出几条铁律。

第一，重要任务永远有 Plan B。写核心代码前，先想清楚如果当前免费池炸了，我最快切到哪条路径继续。这个 Plan B 不一定是实际切换，也可能是提前把任务拆解好，换个模型立刻能继续。

第二，上下文长度要克制。免费模型普遍对超长上下文敏感，更容易在长会话中"迷失方向"。我习惯每个会话聚焦一个具体任务，完成就开新会话，比起挂一个 100k token 的长会话，响应更快、质量更高、限流概率也低。

第三，灵活使用 plan 模式。OpenCode 的--plan参数真的能帮你省大量无效工作。先让模型出一份改动方案，你确认没问题了再让它动手。免费模型执行能力再强，方向错了也是白干。

写在最后

我觉得 OpenCode 最打动人的地方，就是它把"选择权"真正交到了用户手上。Zen 免费池、OpenRouter、本地 Ollama 这三条路，不是谁取代谁的关系，而是互补的，像一套组合工具，平常随手拿最顺手的那个，遇到特殊情况总有备用方案。

最后再分享一个实用小技巧：给自己写个启动脚本，根据第一个参数自动选择 provider。比如ai quick走 Zen、ai big走 OpenRouter、ai local走 Ollama，这样大脑不用记配置细节，手起刀落就能开工。实测下来，这个习惯帮我省下了很多"今天该用哪个模型"的精神内耗，也让我把每条路径的免费额度都利用到了极致。希望这篇文章能帮你少踩几个坑，早点把 OpenCode 用得顺手。