1. 三条免费路线怎么选先想清楚再动手OpenCode 是跑在终端里的 AI 编程助手很多刚上手的人第一反应是能不能不花钱把它跑起来答案是能但前提是路径得选对。目前主流且靠谱的免费方案有三条内置的 Zen 免费池、OpenRouter 平台上的免费模型、还有完全本地运行的 Ollama。这三条路各有各的脾气也各有各的适用场景不是随便挑一个就能愉快写完一天代码的。先说个基础概念OpenCode 本身不生产模型它只是个壳负责把模型能力接到你的编辑器、终端和项目上下文里。它支持多 provider 配置也就是说你可以同时挂上好几个模型服务商用的时候随时切换。免费路径的本质就是把模型供应商这个环节换成不花钱的方案而 OpenCode 的角色就是帮你把各家免费资源统一成一个入口。为什么偏偏是这三条路因为它们的免费机制完全不同。Zen 免费池是 OpenCode 官方内置的打开就能用连账号都不用注册OpenRouter 是一个模型聚合平台上面有一批带:free后缀的免费模型你需要注册一个账号拿 API Key但模型选择非常丰富Ollama 则是把模型直接拉到本地跑完全不依赖任何在线服务代价是你得有一台配置还过得去的机器。三者的成本、隐私、速度和配置难度差异很大适合的人群也不一样。下面这张表是我日常判断用哪条路的依据路径成本是否需要联网数据是否出本机建议配置成本适合任务Zen 免费池免费需要是云端模型零配置开箱即用小段补全、临时问答、快速验证OpenRouter 免费模型免费有限额需要是云端模型注册 拿 Key约 10 分钟需要多种模型对比、偶尔重度使用本地 Ollama完全免费不需要否本地推理安装 拉模型视硬件而定私有代码、离线环境、追求隐私我个人的判断逻辑很简单临时摸鱼用 Zen认真干活但不想花钱用 OpenRouter 免费档涉及私有代码或者网络不稳的时候直接用 Ollama。三条路可以同时配在同一个 OpenCode 环境里互不冲突后面我会把组合配置也写出来。2. 第一条路Zen 免费池零配置开箱即用2.1 先装好 OpenCodeOpenCode 的安装方式不算复杂官方提供了 npm、brew 和 curl 脚本几种渠道。我长期在 macOS 和 Linux 上工作用得最多的是 npm 全局安装npm install -g opencode-ai装完先验证一下版本opencode --versionWindows 用户我多说一句不要用系统自带的旧版命令提示符去跑建议先装 Windows Terminal然后把默认 shell 切换成 PowerShell 7 或者 Git Bash否则后续很多交互式操作会卡在终端渲染上。旧版 cmd 的 ANSI 转义支持太差OpenCode 这种 TUI 应用在里头会显示错乱看起来就像程序坏了其实是终端的问题。需要注意的是OpenCode 迭代很快不同大版本的 npm 包名可能有变化如果opencode-ai这个包名在你安装时已经不再是官方推荐请以官方 README 上的安装说明为准。装完以后直接在终端输入opencode就能启动第一次进入是交互式会话界面底部有输入框斜杠开头能调出命令菜单。2.2 直接把 Zen 当默认模型Zen 免费池最舒服的地方在于完全不需要 API Key。你打开 OpenCode 后在会话里输入/models面板里应该就能看到 Zen 这一组模型通常是以zen/开头的 ID。选中一个就能直接对话整个流程从启动到用上模型不超过一分钟。如果你想把它写进当前项目的配置文件也很简单。OpenCode 会在项目目录或全局配置目录生成一份opencode.json具体路径以你使用的版本为准在provider块里声明 Zen 即可{ $schema: https://opencode.ai/config.json, provider: { zen: {} } }这样声明完之后OpenCode 会自动把 Zen 免费池里的模型作为可选项。你可以在配置里通过models字段只暴露你想用的那几款模型比如{ provider: { zen: { models: { zen/meta-llama-3.3-70b: {} } } } }注意模型 ID 前面的zen/前缀不能丢这是 OpenCode 用来区分模型归属 provider 的命名规则。如果你在别的 provider 下面写了一个zen的模型OpenCode 会一脸懵直接给你报 provider 错误。2.3 报错opencodes free tier can only be used from within opencode这是我在网上看到出现频率最高的一条 Zen 报错完整提示长这样error from provider (console): opencodes free tier can only be used from within opencode这句话翻译过来就是Zen 免费池只能在 OpenCode 内部使用。它不是一个 bug而是官方故意做的限制。Zen 免费池本质上是 OpenCode 自己托管的模型网关目的是给用户在 OpenCode 里免费用而不是提供通用 API。很多人的问题出在把 Zen 的 endpoint 或者模型 ID 抄出去塞进别的工具、脚本、或者自写的 HTTP 请求里。一旦 OpenCode 的服务端发现请求不是来自 OpenCode 客户端就会抛这个错误。另一种常见情况是你在 OpenCode 的配置里把某个自定义 provider 的名字写成了zen但实际又指向了别的地址OpenCode 以为你想走 Zen 免费池于是返回这个限制提示。解决办法很简单Zen 免费池只在 OpenCode 内部用不要试图把它搬出去。如果你确实需要在 OpenCode 之外的场景调用模型老老实实走 OpenRouter 的 API Key或者直接用本地 Ollama。在 OpenCode 内部先确认你选的模型 ID 带zen/前缀并且没有在自定义 provider 里重复定义zen这个名字报错就会消失。2.4 Zen 免费池的使用注意事项Zen 免费池虽然方便但它不是无限量的自助餐。我实际用下来的感受是它适合零散的小请求比如补全一个函数、解释一段报错、写个正则表达式这种量级完全没问题。但如果你想靠它连续跑一整天的代码生成、批量重构多个文件很容易碰到限流表现就是请求排队时间明显变长或者直接返回错误。还有一点Zen 免费池上的模型是官方统一维护的模型列表会不定期调整。今天可用的模型下周可能就换成了另一款。不要在一棵树上吊死平时多留意/models面板里的实际列表比看网上的旧教程靠谱得多。3. 第二条路OpenRouter 免费模型一个 Key 串起几十个模型3.1 注册、拿 Key 与充值OpenRouter 是一个模型聚合网关简单理解就是AI 模型的中介超市。它把几十家厂商的模型接口统一成一套 API你只需要注册一个账号、拿一个 Key就能调用平台上所有模型。对 OpenCode 用户来说这条路的诱惑在于平台上有一批标注为:free的免费模型比如 DeepSeek、Llama、Qwen 的某些版本这些模型不扣费适合拿来白嫖。注册流程不复杂。打开 openrouter.ai用邮箱注册并登录进入个人后台后找到 API Keys 页面创建一个新 Key。生成的 Key 长这样sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxsk-or-v1-是 OpenRouter 的标准前缀复制的时候注意不要把末尾的多余字符带进去。创建完之后平台一般会要求你设置月度消费上限这个建议顺手设一个比较小的值比如 $5 或者 $10。为什么因为免费模型是免费的但平台里还有大量付费模型如果后续谁不小心配置错了、或者有工具自动切换到了付费模型没有上限保护的话账单可能让你肉疼。关于充值我的建议是如果你只打算用免费模型完全不需要充值。如果你未来想跑付费模型比如 Claude、GPT 系列就需要先给账户充值平台支持常见的国际信用卡支付具体支持的渠道以你账号后台实际显示的为准。充值这事不用着急先把免费模型跑通再说。3.2 在 OpenCode 里配置 OpenRouterOpenCode 对 OpenRouter 的接入是原生支持级别的不需要装额外插件。在opencode.json的provider块里声明 openrouter然后填上你的 API Key{ $schema: https://opencode.ai/config.json, provider: { openrouter: { options: { apiKey: sk-or-v1-xxxxx }, models: { deepseek/deepseek-chat-v3-0324:free: {}, qwen/qwen-2.5-72b-instruct:free: {} } } } }模型 ID 的格式是厂商/模型名:free冒号后面的free后缀表示这是免费版本。这个 ID 不是随便编的需要去 OpenRouter 网站上的模型列表页查左侧筛选 Free就能看到当前所有免费模型和对应的完整 ID。配置完成保存后在 OpenCode 会话里输入/models就能看到你刚填进去的免费模型。选中即可使用。如果你不想把所有模型都写死在配置里也没关系OpenCode 支持通过/models面板浏览当前 provider 下的所有模型但手动声明的好处是可以有效防止误选付费模型——这个坑我踩过有一次没写 models 字段面板里居然出现了 Claude 的付费选项虽然我没选但总归是个风险。3.3 免费模型的限额与白嫖姿势OpenRouter 上的免费模型之所以免费是因为有非常严格的限流策略。常见的限制包括每个 IP 每分钟 5 个请求、每天最多 50 个请求之类具体数值每个模型不一样。这意味着你不能把免费模型当成主力日常模型来用更适合的场景是测试这个模型适不适合你的代码风格临时需要的时候切过去用一下同一段代码用不同模型对比结果我自己的习惯是永远在配置里保留两到三个免费模型然后根据任务类型切换。比如快速小改动用 Zen想试试某个新模型的风格就切到 OpenRouter 的免费档。免费模型的响应速度通常不如付费档高峰期甚至会有明显排队如果你连续操作很快就会撞上 429 限流。另外记住一点免费模型的列表不是固定不变的。某个免费模型可能因为上游厂商政策调整突然被移除或者改为付费这种情况我在上半年遇到过好几次。如果你某天用着用着发现某个模型突然报错或者消失去 OpenRouter 官网看公告通常都会给出原因。3.4 OpenRouter 常见报错排查我整理了一张 OpenRouter 接入过程中最常遇到的报错表报错现象可能原因处理方式Provider authenticationAPI Key 复制错误或没填回到后台重新复制检查配置里是否有多余空格HTTP 403免费模型不可用、地区限制或已下线去官网确认模型状态换一个免费模型HTTP 429触发限流等一会再试或者换模型、切换其他路径model_not_found模型 ID 写错查官网模型列表复制完整 ID请求超时免费模型高负载切换到低峰时段或改用 Ollama关于地区访问的问题说实话我不是很建议在这个问题上死磕。OpenRouter 是一个公开的 API 网关能不能顺畅访问取决于你当前的网络环境。如果官网能正常打开通常 API 也能正常请求如果访问本身就不稳定那最靠谱的办法不是折腾网络而是直接换成本地 Ollama或者选一个你网络环境下可以正常访问的模型服务。免费方案有的是不必非在一棵树上吊死。4. 第三条路本地 Ollama离线免费、隐私拉满4.1 安装 Ollama三个平台一次说清Ollama 的价值在于模型跑在你自己电脑上数据不出本机不依赖任何在线账号也没有请求限额。对于写私有代码、出差离线场景、或者单纯不想把代码片段发给外部 API 的人来说这是最让人安心的方案。安装方式按平台区分Windows去 Ollama 官网下载 exe 安装包双击安装装完命令行里就能用ollama命令。如果官网下载速度不理想可以找国内一些可信的开源镜像站看看有没有同步的安装包但一定要从可信来源下载不要用来路不明的文件。macOS最简单的是用 Homebrewbrew install ollama也可以直接从官网下 dmg 安装。Linux官方提供一键脚本curl -fsSL https://ollama.com/install.sh | sh。装完验证一下ollama -v能看到版本号就说明装好了。这里有个很容易忽略的点Ollama 装好之后默认会有一个后台服务在运行通常监听localhost:11434。如果你改了端口、或者服务没起来后面 OpenCode 连不上本地模型很多问题其实是服务没启动导致的不是配置写错了。4.2 下载模型慢怎么办安装完 Ollama下一步是拉模型。最直接的方式ollama pull qwen3:8bpull只会下载不运行ollama run qwen3:8b则会下载并进入交互对话。这里最大的痛点是速度。由于模型文件体积动辄几 GB 到几十 GB而默认源的海外的很多人在国内网络环境下拉取时速度感人进度条半天不动。针对这个问题我整理过几种实际可行的处理思路第一种用模型文件离线导入。如果你能从可信渠道比如 Hugging Face 的国内镜像站 hf-mirror.com下到一个 GGUF 格式的模型文件就可以完全绕开 Ollama 的下载源。把 GGUF 文件放到本地某个目录然后写一个ModelfileFROM ./qwen3-8b.Q4_K_M.gguf接着在同一个目录下执行ollama create qwen3-8b-local -f Modelfile这样 Ollama 就会用本地文件创建一个新模型之后ollama run qwen3-8b-local就能跑了。这套流程相当于把下载和装模型拆成了两步下载慢的问题被你手动绕过去了。第二种换时段或者换网络环境。同样的资源不同时段速度能有天壤之别晚上高峰时段明显更慢。如果你有条件用网络状况更好的环境把模型文件提前拉下来然后通过离线包装到目标机器上。第三种先评估一下模型大小。同样的模型量化等级越高文件越大比如 Q8 量化可能比 Q4 大一倍。对于大多数开发任务Q4_K_M 量化已经足够没必要追求最高精度文件小一半下载也快一半。4.3 把 Ollama 接到 OpenCodeOllama 接入 OpenCode 同样走 provider 声明。OpenCode 对 Ollama 的支持比较完善通常会自动发现本机正在运行的 Ollama 服务以及已经拉好的模型不一定需要手动写配置。如果自动发现失效或者你想明确指定可以这样写{ $schema: https://opencode.ai/config.json, provider: { ollama: { options: { baseURL: http://localhost:11434/v1 }, models: { qwen3:8b: {} } } } }baseURL指向 Ollama 的 OpenAI 兼容端点这个路径是 Ollama 官方支持的不需要额外装插件。这里有个小细节如果 Ollama 和 OpenCode 跑在同一台机器上用localhost就行如果是远程机器上的 Ollama要把 IP 换成实际的局域网地址并且确认 Ollama 服务监听了对应端口。配置完后在/models面板里选择 Ollama 组下的模型即可。我实测下来OpenCode 对本机 Ollama 的发现能力很强只要 Ollama 服务在跑、模型已拉好面板里基本都能直接看到不需要重启。4.4 硬件要求与模型推荐本地跑模型硬件是硬门槛。我用一张表给你一个粗略的参考模型规格最低内存建议典型使用场景7B~8B如 Qwen3 8B16GB 内存最好有 8GB 显存日常补全、问答、轻量重构14B~27B如 Qwen3 27B32GB 内存建议 12GB 以上显存复杂代码理解、中等规模项目分析70B 级别单卡 48GB 显存或苹果统一内存 64GB高质量生成但普通人跑不起如果你只有一台普通办公笔记本不要一上来就拉 70B 模型8B 级别的量化模型是性价比之王。我目前的主力就是 Qwen3 8B 的 Q4_K_M 量化版日常写代码、改 bug 完全够用。如果你对输出质量要求更高可以试试 27B 级别的模型但前提是你的内存能扛住并且有耐心接受更长的推理时间。这里还有一个额外的安利如果你不想用纯命令行管理模型和对话可以搭配 AnythingLLM 这类工具。它支持把 Ollama 作为底层模型源提供一个图形化的知识库/对话界面适合本地文档比较多、需要边看资料边问模型的人。配置方式很简单在 AnythingLLM 的模型设置里选择 Ollama然后填http://localhost:11434就行。4.5 本地模型速度和只思考不回答的问题本地模型最常见的两个问题一个是慢一个是模型一直输出思考链却没有最终答案。先说速度如果你用的是 CPU 推理7B 模型的生成速度可能只有每秒几个 token体验会比较磨人。有条件的话尽量走 GPU。如果你已经用上了 GPU 但还是慢检查一下是不是模型填满了显存导致推理退化到 CPU 模式。Ollama 有一些环境变量可以调节行为比如OLLAMA_NUM_PARALLEL控制并行请求数量OLLAMA_MAX_LOADED_MODELS控制同时驻留内存的模型数量。如果你的机器内存不太富裕建议把OLLAMA_MAX_LOADED_MODELS设成 1避免 Ollama 同时把多个模型加载进内存反而频繁换入换出。至于只思考不回答我遇到过的原因有三类。第一类是模型本身是 reasoning 模型默认会把思考过程完整输出但 OpenCode 某些版本对流式输出中的思考片段处理不够好导致你以为卡住了其实只是还没到最终答案。第二类是本地模型推理太慢长时间没有产出可显示的 token表现上就像只思考不回答。第三类是提示词里要求模型输出严格格式比如纯 JSON模型在思考链里已经写完了 JSON但最终回答部分因为超时或格式冲突被截断。排查思路先单独在终端用ollama run 模型名测一下如果单独跑也这样问题在模型本身单独跑没问题问题在 OpenCode 的配置或上下文长度。换一个不带思考链的模型、关闭模型的思考模式选项、或者调低上下文长度通常能解决问题。5. 三路并行与常见问题速查5.1 一个配置里同时启用三条路径三条免费路径不是单选题完全可以同时挂在一个 OpenCode 环境里。我现在的配置大概长这样{ $schema: https://opencode.ai/config.json, provider: { zen: {}, openrouter: { options: { apiKey: sk-or-v1-xxxxx }, models: { deepseek/deepseek-chat-v3-0324:free: {} } }, ollama: { options: { baseURL: http://localhost:11434/v1 }, models: { qwen3:8b: {} } } } }这样配置之后会话里输入/models你会看到三个 provider 下的所有可用模型。日常使用时的切换成本几乎为零小任务切 Zen想试试别的模型切 OpenRouter涉及敏感代码或者网络不稳切 Ollama。我给你的建议是先不倒腾配置直接用默认的 Zen 跑通一次完整流程再逐步加 OpenRouter 和 Ollama。一次只改一个变量出问题的时候才知道往哪查。5.2 常见问题速查表把网上讨论频率最高的问题整理成一张速查表遇到问题直接翻问题可能原因解决方案opencodes free tier can only be used from within opencodeZen 免费池被外部工具调用或自定义 provider 名字与 Zen 冲突只在 OpenCode 内部使用 Zen检查配置中 provider 名称不要重名Provider authentication/UnauthorizedOpenRouter API Key 错误重新复制 Key检查前后空格429 Too Many Requests免费模型触发限流等一段时间或切换其他 provider403 Forbidden免费模型下线或地区不可用去 OpenRouter 公告页确认换一个免费模型模型一直思考但不出结果模型推理模式、上下文过长、本地推理慢关思考模式、缩短上下文、单独跑ollama run验证Windows 下界面乱码或卡顿默认终端太老不支持 ANSI 转义改用 Windows Terminal PowerShell 7 或 Git BashOllama 拉模型速度慢默认下载源速度不佳用 GGUF 离线导入或换可信镜像源下载安装包OpenCode 旧仓库显示 archived项目迁移到新仓库直接去官网 opencode.ai 获取最新下载渠道不用旧链接想用图形界面管理本地模型命令行操作不直观装 AnythingLLM模型设置里填http://localhost:11434还有一个细节容易被忽略如果你在 OpenCode 里改了配置但没生效先试试重启 OpenCode 进程。这个工具不少配置项是启动时加载的热重载不一定每次都可靠。重启解决不了再检查配置文件的语法JSON 里多个逗号、漏掉引号这类低级错误我见过太多次。5.3 免费额度用光的兜底策略免费方案最大的不确定性就是额度。Zen 限流了、OpenRouter 免费模型挂了、本地 Ollama 又因为机器内存不够跑不动 27B 模型这时候怎么办我的经验是永远保持一套组合拳OpenRouter 配置里至少放两个不同厂商的免费模型这样即使一个挂了另一个还能顶上本地 Ollama 至少常驻一个 8B 级别的模型哪怕慢至少能用Zen 作为最后的快速通道小任务随手切过去。三套资源同时可用你基本不会陷入想干活但模型全挂的尴尬。6. 最后分享几点我的实际体会免费路线用久了我有几个比较深的感受写在这里给后来人参考。第一不要迷信免费。免费模型的稳定性、响应速度、上下文理解能力整体上确实不如付费模型。免费方案适合低频使用和轻量任务如果你每天要在 OpenCode 里高强度工作四五个小时最终大概率还是会绕回付费 API 或者认真的本地推理方案。这不是劝你氪金而是提前给你一个合理的预期管理。第二API Key 的管理是隐私安全的底线。无论是 OpenRouter 的 Key 还是其他任何服务的 Key不要写进项目目录下的配置文件里然后提交到仓库。我习惯把 Key 放在用户级别的全局配置里或者通过环境变量注入确保项目克隆出去的人看不到我的密钥。免费 Key 虽然不值钱但一旦泄露别人盗用你的免费额度导致限流反而会影响你自己用。第三本地模型调试有一套固定节奏。我踩过很多次坑之后总结的顺序是先单独用ollama run 模型名验证模型本身有没有问题再接入 OpenCode接入后如果报错先看 OpenCode 的日志输出再检查baseURL和模型 ID改完配置必须重启一次 OpenCode 进程。按这个顺序排查大多数问题十分钟内能定位。第四小技巧如果你机器内存不大但又想用本地模型给 OpenCode 提供支持可以在 Ollama 的启动配置里把OLLAMA_NUM_PARALLEL设为 1并控制系统同时只加载一个模型。牺牲并发换取稳定性在写代码这种串行场景下几乎没有感知损失。关于未来方向我比较看好本地模型和云端 API 混合的模式日常杂活用本地免费小模型重要任务按需切到云端大模型OpenCode 这种多 provider 架构天然就是为这个模式设计的。学会配置好这三条免费路径你后面再玩其他 AI 编程工具思路也是相通的。