OpenCode 免费模型接入指南：Zen、OpenRouter 与本地 Ollama 配置

1. 三条免费路径的选型逻辑与适用场景

OpenCode 这个终端里的 AI 编程助手，最近在开发者圈子里讨论度很高。它的定位很直接：把大模型能力塞进命令行，让你不离开终端就能完成代码补全、重构、解释、生成测试这些事。但真正让它在众多同类工具里站住脚的，是它对模型来源的开放态度——你可以接商业 API，也可以走免费池，还能挂本地模型。问题在于，很多人装完之后卡在第一步：到底怎么用上免费模型？

我前后折腾了大概两周，把三条主流路径都跑了一遍：Zen 免费池、OpenRouter 免费模型、本地 Ollama。这三条路各有各的脾气，不是简单一句“哪个好用”能概括的。选哪条，取决于你的网络环境、机器配置、以及对稳定性和隐私的要求。下面这张表是我实测后的一个快速对照，你可以先对号入座。

先说 Zen 免费池。这是 OpenCode 官方内置的一条路径，你装好 OpenCode 之后，默认就能用，不需要额外申请密钥。它的原理是 OpenCode 官方提供了一层代理，把请求转发到后端模型。好处是零配置，坏处是有使用限制——社区里流传的那个报错opencode's free tier can only be used from within opencode，说的就是有人试图绕过 OpenCode 客户端直接调用免费池，被挡了。这个限制其实合理，官方要防止免费额度被滥用。

OpenRouter 是第二条路。它本身是一个模型聚合平台，把各家模型统一成一个 API 接口。OpenRouter 上有不少带:free后缀的模型，比如一些开源模型的免费版本。你需要去 OpenRouter 官网注册账号，拿到 API Key，然后填进 OpenCode 的配置里。这条路的好处是模型选择极其丰富，从轻量到重量级都有，而且免费额度对个人开发者来说通常够用。缺点是免费模型有时会有速率限制，高峰期可能排队。

第三条是本地 Ollama。这是最“硬核”的一条路，模型完全跑在你自己的机器上，不依赖任何外部服务。Ollama 的安装和模型下载在国内网络环境下确实有坑，下载慢、超时是常态，但一旦跑起来，隐私和离线可用性是最好的。适合手头有性能还不错的机器、又不想把代码传到云端的开发者。

我个人的建议是：先用 Zen 免费池把 OpenCode 跑通，确认工具链没问题；然后根据需求决定是转向 OpenRouter 获取更多模型选择，还是部署 Ollama 追求隐私和离线。三条路并不互斥，你完全可以在opencode.json里配置多个 provider，按场景切换。

2. OpenCode 安装与 opencode.json 配置基础

在聊三条路径的具体操作之前，得先把地基打好。OpenCode 的安装本身不复杂，但配置文件的写法是很多人第一次接触时容易懵的地方。这一节我把安装和配置的基础讲透，后面三条路径的操作都会围绕这个配置文件展开。

2.1 OpenCode 安装的几种方式与选择

OpenCode 提供了多种安装方式，常见的有包管理器安装和直接下载二进制。如果你用的是 macOS，用 Homebrew 是最省事的：

brew install opencode

Linux 用户可以用官方的一键脚本，或者从 GitHub Releases 下载对应架构的二进制文件。Windows 用户稍微麻烦一点，官方有桌面版，也可以在 WSL 里跑命令行版本。社区里有人问opencode在windows环境下什么shell工具好用，我的经验是：如果你在 Windows 上做开发，直接用 WSL2 配 Ubuntu，体验和原生 Linux 几乎一致，比在 PowerShell 里折腾兼容性问题省心得多。

安装完成后，运行opencode --version确认版本。这里提醒一句，OpenCode 迭代很快，v2 和早期版本在配置格式上有差异，网上一些老教程可能对不上。遇到配置不生效的情况，先确认你的版本号，再看对应版本的文档。

2.2 opencode.json 的结构与核心字段

OpenCode 的配置文件叫opencode.json，通常放在项目根目录或者用户主目录下。项目级的配置会覆盖全局配置，这个设计很实用——你可以给不同项目配不同的模型。

一个典型的配置文件结构是这样的：

{ "provider": { "zen": { "type": "zen" }, "openrouter": { "type": "openai", "baseURL": "https://openrouter.ai/api/v1", "apiKey": "你的密钥" }, "ollama": { "type": "openai", "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" } }, "model": "zen/default" }

这里有几个关键点需要解释。provider字段定义了模型来源，每个 provider 有自己的type。Zen 是 OpenCode 内置类型，直接写zen就行。OpenRouter 和 Ollama 都兼容 OpenAI 的接口格式，所以type写openai，然后通过baseURL指向不同的服务地址。

model字段指定当前默认使用哪个模型，格式是provider名/模型名。这个字段决定了你敲下命令时默认走哪条路。

注意：apiKey这种敏感信息不建议直接写死在项目配置文件里，尤其是要提交到 Git 的项目。可以用环境变量替代，OpenCode 支持从环境变量读取密钥。

2.3 配置文件的优先级与调试方法

配置文件生效顺序是：项目根目录的opencode.json优先于用户主目录的全局配置。如果你发现改了配置没反应，先检查是不是被项目级配置覆盖了。

调试配置有个小技巧：OpenCode 启动时会打印当前加载的配置来源和使用的模型。如果模型没按预期工作，看启动日志里的 provider 和 model 字段，基本能定位问题。我踩过的一个坑是 JSON 里多了个逗号，导致整个配置解析失败，但报错信息很隐晦，只提示“无法加载配置”。后来养成习惯，改完配置用python -m json.tool opencode.json验证一下 JSON 合法性，能省不少排查时间。

3. Zen 免费池：零配置上手与限制突破

Zen 免费池是三条路里门槛最低的，装完 OpenCode 基本就能用。但“能用”和“用好”之间还有一段距离，尤其是那个opencode's free tier can only be used from within opencode的报错，让不少人以为免费池坏了。这一节把 Zen 的机制、限制和实际使用技巧讲清楚。

3.1 Zen 免费池的工作原理

Zen 是 OpenCode 官方提供的一个模型接入层。你可以把它理解成一个“官方代购”：你的请求先发给 OpenCode 的服务器，服务器再转发给后端的大模型，然后把结果返回给你。这样做的好处是用户端零配置，不需要自己申请任何密钥。

但正因为是官方代购，它必须做两件事：一是识别请求确实来自 OpenCode 客户端，二是控制免费额度的使用。那个报错信息opencode's free tier can only be used from within opencode，就是第一道防线的产物——有人试图用 curl 或者其他工具直接调用 Zen 的接口，被服务器拒绝了。

这个机制对正常使用没有影响，你只要是通过 OpenCode 客户端发起的请求，都能正常走通。所以看到这个报错，先确认你是不是在用 OpenCode 本身，而不是在调试接口。

3.2 免费额度的实际体验与应对

Zen 免费池有额度限制，具体数字官方没有公开固定值，会根据负载动态调整。我的实测体验是：日常的代码问答、补全、解释，额度基本够用；但如果频繁让它生成大段代码或者做复杂重构，可能会触发限流。

限流时的表现通常是响应变慢或者返回一个提示额度用尽的错误。遇到这种情况，有几个应对方式。一是错峰使用，避开国内晚上的高峰时段。二是把复杂任务拆成小步骤，减少单次请求的 token 消耗。三是配置一个备用 provider，比如 OpenRouter 的免费模型，在 Zen 限流时切换过去。

实操心得：Zen 免费池最适合用来“试水”和轻量使用。如果你打算把 OpenCode 作为日常主力工具，建议至少再配一条备用路径，避免关键时刻被限流卡住。

3.3 Zen 与其他路径的切换策略

在opencode.json里，你可以把 Zen 设为默认模型，同时配好 OpenRouter 和 Ollama。切换的方式很简单，改model字段，或者在 OpenCode 的交互界面里用命令切换。

我的习惯是：默认走 Zen，因为零成本且响应快；需要处理敏感代码时切到 Ollama；需要特定模型能力（比如某个擅长某种语言的模型）时切到 OpenRouter。这种“三线并行”的配置，让 OpenCode 的可用性提升了一个档次，不会因为单条路径出问题就整个瘫痪。

4. OpenRouter 免费模型：密钥获取与模型选择

OpenRouter 这条路的灵活度是三条里最高的。它像一个模型超市，你办一张会员卡（API Key），就能在里面挑各种模型用。免费模型是它的一个亮点，但怎么挑、怎么配、怎么避免踩坑，有不少细节。

4.1 OpenRouter 账号注册与 API Key 获取

OpenRouter 的官方入口直接搜就能找到。注册流程很标准，邮箱加密码，验证后就能进控制台。进去之后找到 API Keys 页面，创建一个新的 Key。创建时可以设置额度上限，这个功能建议用上，防止意外超支。

拿到 Key 之后，把它填进opencode.json的 OpenRouter provider 配置里。前面提过，更安全的做法是用环境变量。OpenCode 支持在配置里写"apiKey": "${OPENROUTER_API_KEY}"这种形式，然后你在系统环境变量里设置实际值。

关于充值，OpenRouter 支持多种支付方式，国内用户关心的支付宝渠道，实测是可以用的。不过免费模型不需要充值也能用，充值主要是为了解锁付费模型或者提高免费模型的速率限制。

4.2 免费模型的筛选与实测推荐

OpenRouter 上的模型列表很长，带:free后缀的就是免费版本。但免费模型的质量参差不齐，不是所有都值得用。我实测下来，筛选免费模型主要看三个维度：上下文长度、擅长的任务类型、以及响应速度。

上下文长度决定了它能一次处理多少代码。做代码相关的工作，上下文太短的模型基本没法用，因为一个稍大的文件就超了。任务类型方面，有些模型偏通用对话，有些专门优化过代码生成。响应速度则直接影响使用体验，太慢的模型会让人失去耐心。

选模型时，OpenRouter 的模型页面会显示每个模型的详细参数和用户评价，花几分钟对比一下能省很多试错时间。我的建议是选两到三个免费模型配在配置里，根据任务类型切换。

4.3 速率限制与错误处理

OpenRouter 的免费模型普遍有速率限制，常见的是每分钟请求数或者每天请求数的限制。触发限制时会返回 429 状态码。OpenCode 遇到这种情况通常会提示错误，但不会自动重试。

处理速率限制，一是控制请求频率，把不紧急的任务攒一攒批量处理；二是配置多个免费模型，一个限流了切另一个；三是如果确实用量大，考虑给 OpenRouter 充点值，付费后的速率限制会宽松很多。

注意：OpenRouter 的免费模型政策可能会调整，今天免费的模型明天可能就收费了。定期检查一下你配置的模型是否还在免费列表里，避免不知不觉产生费用。

5. 本地 Ollama：安装、镜像加速与模型部署

Ollama 是三条路里技术含量最高、但长期收益也最大的一条。模型跑在本地，不依赖网络，隐私性最好。但安装和模型下载在国内网络环境下确实有门槛，这一节把踩过的坑和解决方案都整理出来。

5.1 Ollama 安装与国内镜像源配置

Ollama 官方提供了各平台的安装包。macOS 和 Windows 有图形化安装程序，Linux 有一键脚本。问题出在下载环节——官方源在国内访问速度不稳定，ollama下载慢是社区里高频出现的问题。

解决方案是使用国内镜像源。一些高校和云服务商提供了 Ollama 安装包和模型文件的镜像。配置方式通常是在安装前设置环境变量，或者在 Ollama 的配置里指定镜像地址。具体镜像地址会变动，建议在社区里找最新的可用源。

如果你需要离线安装，可以提前在有网络的机器上下载好安装包和模型文件，拷贝到目标机器。ollama离线安装包这个需求在隔离环境里很常见，思路就是“先下载后搬运”。

5.2 模型下载加速与常见错误处理

装好 Ollama 之后，下一步是拉取模型。ollama pull命令默认从官方源下载，国内速度堪忧。解决办法同样是配置镜像源。Ollama 支持通过环境变量指定模型下载的镜像地址，设置好之后ollama pull会走镜像，速度能提升一个数量级。

社区里有人遇到ollama run qwen3.5:2b error: 500 internal server error: llama-server process这类报错。这个错误通常和模型文件损坏或者内存不足有关。排查思路：先确认模型文件完整下载了，可以删掉重新 pull；再检查机器内存是否够用，小模型对内存要求低，大模型可能需要十几 GB 甚至更多。

实操心得：下载大模型时，建议在稳定的网络环境下进行，中途断网可能导致文件损坏。如果反复失败，试试换一个小一点的模型先跑通流程，确认 Ollama 本身没问题，再挑战大模型。

5.3 将 Ollama 接入 OpenCode 的完整配置

Ollama 跑起来之后，接入 OpenCode 就简单了。Ollama 默认在http://localhost:11434提供服务，并且兼容 OpenAI 的接口格式。在opencode.json里加一个 provider：

{ "provider": { "ollama": { "type": "openai", "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" } }, "model": "ollama/qwen2.5-coder" }

注意apiKey这里填什么其实无所谓，Ollama 本地服务不校验密钥，但 OpenCode 的 OpenAI 兼容层要求这个字段非空，所以随便填一个占位就行。模型名要和你ollama list里显示的一致。

配置好之后，把model字段改成ollama/你的模型名，OpenCode 就会走本地模型。实测下来，本地模型的响应速度取决于你的硬件，GPU 加速会快很多，纯 CPU 跑小模型也能用，就是慢一些。

6. 三条路径的协同配置与故障排查实录

单独跑通一条路径只是开始，真正的效率提升来自于三条路径的协同。这一节讲怎么在opencode.json里把三条路都配好，以及遇到问题时怎么快速定位。

6.1 多 Provider 配置的完整示例

一个把三条路径都配好的opencode.json大概长这样：

{ "provider": { "zen": { "type": "zen" }, "openrouter": { "type": "openai", "baseURL": "https://openrouter.ai/api/v1", "apiKey": "${OPENROUTER_API_KEY}" }, "ollama": { "type": "openai", "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" } }, "model": "zen/default" }

默认走 Zen，需要切换时改model字段。OpenCode 的交互模式里通常也有切换模型的命令，不用每次改文件。

这种配置的好处是容错性强。Zen 限流了切 OpenRouter，OpenRouter 网络不通了切 Ollama，总有一条路能走通。对于把 OpenCode 当主力工具的人来说，这种冗余设计很有必要。

6.2 常见报错速查与解决思路

折腾这三条路的过程中，我记录了一些高频报错和对应的解决思路，整理成表方便查阅。

排查问题的通用思路是：先确认配置文件本身没问题，再确认网络能通到服务地址，最后确认密钥或模型名正确。这三步能解决大部分问题。

6.3 性能与成本的平衡取舍

三条路径在性能和成本上的取舍很明确。Zen 免费但有限流，适合轻量日常使用。OpenRouter 灵活但免费模型有速率限制，适合需要特定模型能力的场景。Ollama 无限制但吃硬件，适合隐私敏感和离线场景。

我的实际用法是：日常问答和补全走 Zen，遇到 Zen 限流或者需要特定模型时切 OpenRouter，处理公司内部代码或者断网环境下用 Ollama。这种组合下来，一个月在模型上的花费基本为零，同时保持了很高的可用性。

提示：如果你主要用 Ollama，建议至少准备两个不同规模的模型。小模型用于快速问答，大模型用于复杂任务。切换成本很低，但体验差异明显。

7. 进阶玩法：Skills 与多工具协同

OpenCode 的能力不止于对话，它的 Skills 机制和与其他工具的协同，能把免费模型的价值进一步放大。这一节聊几个进阶方向。

7.1 OpenCode Skills 的安装与使用

Skills 可以理解为 OpenCode 的插件系统，通过安装不同的 Skill 来扩展它的能力。社区里已经有不少现成的 Skill，覆盖代码审查、文档生成、测试编写等场景。

安装 Skill 的方式通常是把它放到指定的目录，或者在配置里声明。具体路径和格式随版本变化，建议参考对应版本的文档。我装过几个代码相关的 Skill，配合免费模型使用，效果比裸模型好不少——Skill 相当于给模型预设了提示词和工作流，让它更聚焦在特定任务上。

7.2 与 Claude Code 等工具的接入思路

社区里有人讨论opencode go接入claude code这类话题，思路是把 OpenCode 作为统一的模型接入层，其他工具通过它来调用模型。这种架构的好处是模型配置集中管理，换模型只需要改一处。

实现方式通常是利用 OpenCode 的本地服务能力，让其他工具把请求发到 OpenCode，再由 OpenCode 转发到具体的 provider。这种玩法适合工具链比较复杂的开发者，能把模型管理这件事从各个工具里抽离出来。

7.3 用免费模型做实际开发的体验

最后聊聊用免费模型做实际开发的真实感受。我用 Zen 和 OpenRouter 的免费模型写过一些中小型项目的代码，整体可用，但有几个心得。

一是免费模型在简单任务上表现很好，比如写个工具函数、解释一段代码、生成单元测试。二是复杂任务上，免费模型和顶级付费模型差距明显，尤其是需要长上下文推理的场景。三是提示词的质量对结果影响很大，同样的模型，好的提示词能让输出质量提升一个档次。

所以我的策略是：把免费模型用在它擅长的场景，复杂任务拆解成小步骤喂给它，配合清晰的提示词。这样下来，免费模型能满足我八成的日常需求，剩下两成再考虑付费模型或者本地大模型。

这套三条路径的配置我用了几个月，整体很稳。唯一需要定期维护的是 OpenRouter 的免费模型列表和 Ollama 的镜像源地址，这两样会变动。养成每隔一段时间检查一下的习惯，就能一直用下去。