OpenCode免费使用指南：Zen免费池、OpenRouter与本地Ollama三条路线详解

1. 三条免费路线怎么选：先想清楚再动手

OpenCode 是跑在终端里的 AI 编程助手，很多刚上手的人第一反应是：能不能不花钱把它跑起来？答案是能，但前提是路径得选对。目前主流且靠谱的免费方案有三条：内置的 Zen 免费池、OpenRouter 平台上的免费模型、还有完全本地运行的 Ollama。这三条路各有各的脾气，也各有各的适用场景，不是随便挑一个就能愉快写完一天代码的。

先说个基础概念：OpenCode 本身不生产模型，它只是个壳，负责把模型能力接到你的编辑器、终端和项目上下文里。它支持多 provider 配置，也就是说你可以同时挂上好几个模型服务商，用的时候随时切换。免费路径的本质，就是把"模型供应商"这个环节换成不花钱的方案，而 OpenCode 的角色就是帮你把各家免费资源统一成一个入口。

为什么偏偏是这三条路？因为它们的免费机制完全不同。Zen 免费池是 OpenCode 官方内置的，打开就能用，连账号都不用注册；OpenRouter 是一个模型聚合平台，上面有一批带:free后缀的免费模型，你需要注册一个账号拿 API Key，但模型选择非常丰富；Ollama 则是把模型直接拉到本地跑，完全不依赖任何在线服务，代价是你得有一台配置还过得去的机器。三者的成本、隐私、速度和配置难度差异很大，适合的人群也不一样。

下面这张表是我日常判断用哪条路的依据：

我个人的判断逻辑很简单：临时摸鱼用 Zen，认真干活但不想花钱用 OpenRouter 免费档，涉及私有代码或者网络不稳的时候直接用 Ollama。三条路可以同时配在同一个 OpenCode 环境里，互不冲突，后面我会把组合配置也写出来。

2. 第一条路：Zen 免费池，零配置开箱即用

2.1 先装好 OpenCode

OpenCode 的安装方式不算复杂，官方提供了 npm、brew 和 curl 脚本几种渠道。我长期在 macOS 和 Linux 上工作，用得最多的是 npm 全局安装：

npm install -g opencode-ai

装完先验证一下版本：

opencode --version

Windows 用户我多说一句：不要用系统自带的旧版命令提示符去跑，建议先装 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 报错：opencode's free tier can only be used from within opencode

这是我在网上看到出现频率最高的一条 Zen 报错，完整提示长这样：

error from provider (console): opencode's 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-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

sk-or-v1-是 OpenRouter 的标准前缀，复制的时候注意不要把末尾的多余字符带进去。创建完之后，平台一般会要求你设置月度消费上限，这个建议顺手设一个比较小的值，比如 $5 或者 $10。为什么？因为免费模型是免费的，但平台里还有大量付费模型，如果后续谁不小心配置错了、或者有工具自动切换到了付费模型，没有上限保护的话，账单可能让你肉疼。

关于充值，我的建议是：如果你只打算用免费模型，完全不需要充值。如果你未来想跑付费模型（比如 Claude、GPT 系列），就需要先给账户充值，平台支持常见的国际信用卡支付，具体支持的渠道以你账号后台实际显示的为准。充值这事不用着急，先把免费模型跑通再说。

3.2 在 OpenCode 里配置 OpenRouter

OpenCode 对 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 接入过程中最常遇到的报错表：

关于"地区访问"的问题，说实话我不是很建议在这个问题上死磕。OpenRouter 是一个公开的 API 网关，能不能顺畅访问取决于你当前的网络环境。如果官网能正常打开，通常 API 也能正常请求；如果访问本身就不稳定，那最靠谱的办法不是折腾网络，而是直接换成本地 Ollama，或者选一个你网络环境下可以正常访问的模型服务。免费方案有的是，不必非在一棵树上吊死。

4. 第三条路：本地 Ollama，离线免费、隐私拉满

4.1 安装 Ollama：三个平台一次说清

Ollama 的价值在于：模型跑在你自己电脑上，数据不出本机，不依赖任何在线账号，也没有请求限额。对于写私有代码、出差离线场景、或者单纯不想把代码片段发给外部 API 的人来说，这是最让人安心的方案。

安装方式按平台区分：

• Windows：去 Ollama 官网下载 exe 安装包，双击安装，装完命令行里就能用ollama命令。如果官网下载速度不理想，可以找国内一些可信的开源镜像站看看有没有同步的安装包，但一定要从可信来源下载，不要用来路不明的文件。
• macOS：最简单的是用 Homebrew：brew install ollama，也可以直接从官网下 dmg 安装。
• Linux：官方提供一键脚本：curl -fsSL https://ollama.com/install.sh | sh。

装完验证一下：

ollama -v

能看到版本号就说明装好了。这里有个很容易忽略的点：Ollama 装好之后默认会有一个后台服务在运行，通常监听localhost:11434。如果你改了端口、或者服务没起来，后面 OpenCode 连不上本地模型，很多问题其实是服务没启动导致的，不是配置写错了。

4.2 下载模型慢怎么办

安装完 Ollama，下一步是拉模型。最直接的方式：

ollama pull qwen3:8b

pull只会下载不运行，ollama run qwen3:8b则会下载并进入交互对话。这里最大的痛点是速度。由于模型文件体积动辄几 GB 到几十 GB，而默认源的海外的，很多人在国内网络环境下拉取时速度感人，进度条半天不动。

针对这个问题，我整理过几种实际可行的处理思路：

第一种，用模型文件离线导入。如果你能从可信渠道（比如 Hugging Face 的国内镜像站 hf-mirror.com）下到一个 GGUF 格式的模型文件，就可以完全绕开 Ollama 的下载源。把 GGUF 文件放到本地某个目录，然后写一个Modelfile：

FROM ./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 接到 OpenCode

Ollama 接入 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 硬件要求与模型推荐

本地跑模型，硬件是硬门槛。我用一张表给你一个粗略的参考：

如果你只有一台普通办公笔记本，不要一上来就拉 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 常见问题速查表

把网上讨论频率最高的问题整理成一张速查表，遇到问题直接翻：

还有一个细节容易被忽略：如果你在 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 编程工具，思路也是相通的。