做终端 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): opencodes 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_KEYsk-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 免费模型选择建议如果你刚开始用我建议优先试这几个免费模型我按编程场景排了序模型 ID 示例特点需要注意deepseek/deepseek-chat:free编程综合能力强代码生成逻辑严谨晚高峰偶尔限流qwen/qwen3:free中文理解好命名和注释靠谱响应稍慢meta-llama/llama-3.3-70b:free通用任务稳定长上下文处理还行编程精细度不如前两者mistralai/mistral-small:free轻量快速适合简单重构复杂架构推理能力有限模型选择其实不是越多越好我建议你在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 --versionmacOS 版本安装后会自动在后台运行服务Linux 可能需要手动执行ollama serve启动。启动成功的标志是访问http://localhost:11434能返回一个文本页面告诉你 Ollama is running。4.3 下载模型与硬件匹配的实操记录Ollama 安装好之后下一步就是拉模型。我推荐从这几个开始ollama pull qwen3:8b ollama pull deepseek-r1:7bqwen3: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 serveOpenCode 连接时会报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 高频报错速查表以下是我整理的高频报错速查表遇到问题直接对着查报错信息可能原因解决方式opencodes free tier can only be used from within opencode离开了 OpenCode 客户端调用 Zen 免费池或配置的 token 来源异常回到 OpenCode 内使用检查 provider 配置来源401 UnauthorizedOpenRouter Key 错误、过期、或复制时带了空格重新生成 Key用环境变量引用429 rate limit触发免费模型频率限制等几分钟再试切换其他免费模型ECONNREFUSED localhost:11434Ollama 服务未启动执行ollama serve或重启 Ollamamodel not found模型 ID 拼写与平台/本地不一致用/models查可用模型复制精确 IDconnect ETIMEDOUT网络到目标 API 服务不稳定检查网络连通性改走本地 Ollama5.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 用得顺手。