1. 三条免费路径的选型逻辑与适用场景OpenCode 这个终端里的 AI 编程助手最近在开发者圈子里讨论度很高。它的定位很直接把大模型能力塞进命令行让你不离开终端就能完成代码补全、重构、解释、生成测试这些事。但真正让它在众多同类工具里站住脚的是它对模型来源的开放态度——你可以接商业 API也可以走免费池还能挂本地模型。问题在于很多人装完之后卡在第一步到底怎么用上免费模型我前后折腾了大概两周把三条主流路径都跑了一遍Zen 免费池、OpenRouter 免费模型、本地 Ollama。这三条路各有各的脾气不是简单一句“哪个好用”能概括的。选哪条取决于你的网络环境、机器配置、以及对稳定性和隐私的要求。下面这张表是我实测后的一个快速对照你可以先对号入座。路径成本网络要求硬件要求稳定性适合人群Zen 免费池完全免费需能访问 OpenCode 服务极低中等有额度限制想零配置快速上手的人OpenRouter 免费模型免费额度付费可选需能访问 OpenRouter极低较高模型选择多想灵活切换模型的人本地 Ollama电费完全离线较高需足够内存取决于本机注重隐私、想离线用的人先说 Zen 免费池。这是 OpenCode 官方内置的一条路径你装好 OpenCode 之后默认就能用不需要额外申请密钥。它的原理是 OpenCode 官方提供了一层代理把请求转发到后端模型。好处是零配置坏处是有使用限制——社区里流传的那个报错opencodes 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 opencodeLinux 用户可以用官方的一键脚本或者从 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 基本就能用。但“能用”和“用好”之间还有一段距离尤其是那个opencodes free tier can only be used from within opencode的报错让不少人以为免费池坏了。这一节把 Zen 的机制、限制和实际使用技巧讲清楚。3.1 Zen 免费池的工作原理Zen 是 OpenCode 官方提供的一个模型接入层。你可以把它理解成一个“官方代购”你的请求先发给 OpenCode 的服务器服务器再转发给后端的大模型然后把结果返回给你。这样做的好处是用户端零配置不需要自己申请任何密钥。但正因为是官方代购它必须做两件事一是识别请求确实来自 OpenCode 客户端二是控制免费额度的使用。那个报错信息opencodes 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 限流了切 OpenRouterOpenRouter 网络不通了切 Ollama总有一条路能走通。对于把 OpenCode 当主力工具的人来说这种冗余设计很有必要。6.2 常见报错速查与解决思路折腾这三条路的过程中我记录了一些高频报错和对应的解决思路整理成表方便查阅。报错信息可能原因解决思路opencodes free tier can only be used from within opencode非 OpenCode 客户端调用 Zen确认通过 OpenCode 发起请求error from provider (console)Provider 配置错误或服务不可达检查 baseURL、apiKey、网络连通性429 Too Many Requests触发速率限制降低频率、切换模型、考虑充值500 internal server error: llama-server processOllama 模型文件损坏或内存不足重新 pull 模型、检查内存配置不生效JSON 格式错误或优先级问题验证 JSON、检查项目级配置覆盖排查问题的通用思路是先确认配置文件本身没问题再确认网络能通到服务地址最后确认密钥或模型名正确。这三步能解决大部分问题。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 的镜像源地址这两样会变动。养成每隔一段时间检查一下的习惯就能一直用下去。