企业官网建设流程全解析

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

OpenCode 这个终端里的 AI 编程助手，最近在开发者圈子里讨论度很高。它的定位很直接：把大模型能力塞进命令行，让你在写代码、读代码、改 bug 的时候不用切窗口，直接在终端里对话。但真正让很多人卡住的不是安装，而是“怎么用上免费模型”。官方自带的免费额度有使用限制，一旦触发就会看到那句让人头大的报错：error from provider (console): opencode's free tier can only be used from within opencode。这句话的意思是，免费池只能在 OpenCode 自己的客户端里调用，不能拿到别的地方去用，而且额度有限、并发有限。

所以实际使用中，大家会自然分化出三条路：第一条是继续用官方 Zen 免费池，适合刚上手、想零配置体验的人；第二条是接 OpenRouter 的免费模型，适合想要更多模型选择、愿意折腾 API Key 的人；第三条是本地跑 Ollama，适合对隐私敏感、网络环境不稳定、或者想离线使用的人。这三条路不是互斥的，很多人是组合着用——日常轻量任务走 Zen，复杂任务切 OpenRouter，敏感代码丢给本地 Ollama。

我自己的使用习惯是：Zen 当“默认档”，OpenRouter 当“备用档”，Ollama 当“离线档”。下面把三条路径的配置、踩坑点和实操细节全部拆开讲，尽量让不同基础的读者都能照着做下来。

1.1 为什么免费模型值得认真配置

很多人觉得“免费的就是凑合用”，但在 OpenCode 这个场景里，免费模型的价值被低估了。原因有三个：第一，编程助手的日常任务大部分是解释代码、补全片段、写注释、生成测试用例，这些任务对模型能力的要求没有想象中那么高，一个 7B 到 14B 的模型就能干得不错；第二，免费模型可以让你在没有心理负担的情况下大量试错，比如让模型反复重构同一段代码，不用担心 token 账单；第三，本地模型跑起来之后，你的代码不出本机，这对处理公司内部项目或者有保密要求的代码来说，是刚需。

提示：免费不等于无限制。Zen 免费池有调用频率和上下文长度限制，OpenRouter 免费模型有每日请求数上限，Ollama 本地模型受限于你的显存和内存。配置之前先想清楚自己的主要使用场景，再决定主用哪条路。

1.2 三条路径的核心差异对比

这张表不是让你二选一，而是帮你判断“主力用哪个、备用用哪个”。我见过不少人一上来就折腾本地部署，结果显卡不够、模型跑得比蜗牛还慢，最后放弃了。也见过有人死磕 OpenRouter 免费额度，结果一天用超了被限流。合理的做法是先跑通一条，再逐步加。

2. Zen 免费池：零配置上手的正确姿势

Zen 是 OpenCode 官方提供的模型服务入口，免费池的存在意义就是降低上手门槛。你装完 OpenCode，第一次运行的时候它会引导你选择 provider，选 Zen 就能直接用，不需要填任何 API Key。这也是为什么很多人说“OpenCode 开箱即用”——指的就是这条路径。

但免费池的限制也很明确。那句opencode's free tier can only be used from within opencode的报错，通常出现在两种情况下：一是你试图把 Zen 的接口地址和密钥拿到别的工具里用；二是你的 OpenCode 版本或者配置有问题，导致它认为你不在“官方客户端环境”里。前者是设计如此，后者需要排查。

2.1 Zen 免费池的配置与验证

安装 OpenCode 之后，配置文件通常位于用户目录下的.config/opencode/opencode.json（Linux/macOS）或者%APPDATA%\opencode\opencode.json（Windows）。如果你走 Zen 路径，这个文件里其实不需要写太多东西，核心就是确认 provider 指向 Zen。

一个典型的 Zen 配置片段长这样：

{ "provider": "zen", "model": "zen-default" }

具体字段名可能随版本变化，建议用opencode config或者查看官方文档确认当前版本的写法。配置完之后，运行opencode进入交互界面，随便问一句“解释一下这段代码”，如果能正常返回，说明 Zen 路径通了。

注意：如果你在公司网络或者某些网络环境下，Zen 服务可能连不上。这时候不要反复重试，直接切到 Ollama 本地路径，省时间。

2.2 免费池报错的排查思路

遇到free tier can only be used from within opencode这个报错，按下面顺序排查：

1. 确认你是在 OpenCode 客户端里调用，而不是把配置复制到了别的工具。
2. 检查 OpenCode 版本，老版本可能有兼容问题，升级到最新版再试。
3. 检查opencode.json里有没有多余的 provider 配置，有时候多个 provider 冲突会导致它误判。
4. 如果以上都没问题，可能是免费额度用完了，等一段时间或者换路径。

我自己的经验是，这个报错九成以上是因为“把 Zen 的配置拿去别的地方用了”。Zen 免费池的设计就是绑定客户端的，想通这一点就不会在这上面浪费时间。

2.3 Zen 免费池的实操心得

Zen 最大的优势是省事，最大的劣势是“不可控”——你不知道它什么时候限流、什么时候模型会换。所以我的建议是：把 Zen 当成“快速验证”工具，而不是“主力生产”工具。比如你想试试 OpenCode 的某个功能，或者临时问一个简单问题，用 Zen 没问题。但如果你要连续处理多个文件、做大规模重构，还是切到 OpenRouter 或者本地模型更稳。

另外，Zen 免费池的模型能力是固定的，你没法选。有时候它给的回答质量波动比较大，这不是你的问题，是服务端的负载和模型调度导致的。遇到这种情况，换个时间段再试，或者直接切路径。

3. OpenRouter 免费模型：多模型选择的性价比之选

OpenRouter 是一个模型聚合平台，它把很多家的模型放在一个接口后面，你用一个 API Key 就能调用不同厂商的模型。对 OpenCode 用户来说，OpenRouter 的价值在于：它有一些完全免费的模型，而且模型选择比 Zen 丰富得多。

但 OpenRouter 的免费模型有几个坑：第一，免费模型的列表是动态变化的，今天免费的明天可能就收费了；第二，免费模型通常有每日请求数限制，比如一天 50 次或者 100 次；第三，部分免费模型对上下文长度有限制，长代码文件可能塞不进去。

3.1 获取 OpenRouter API Key 的完整流程

第一步，访问 OpenRouter 官方入口，注册账号。注册过程不复杂，邮箱加密码就行。第二步，登录之后进入 Keys 页面，创建一个新的 API Key。创建的时候给它起个名字，比如 “opencode-free”，方便以后管理。第三步，复制这个 Key，注意它只显示一次，关掉页面就看不到了，所以先粘贴到安全的地方。

注意：OpenRouter 的 API Key 是敏感信息，不要提交到 Git 仓库，也不要写在会公开的配置文件里。建议用环境变量的方式注入。

第四步，在 OpenCode 的配置文件里填入 OpenRouter 的 provider 信息。一个参考配置如下：

{ "provider": "openrouter", "apiKey": "你的_OPENROUTER_KEY", "model": "模型ID" }

模型 ID 需要去 OpenRouter 的模型列表页面找，筛选 “Free” 标签，挑一个适合编程的。常见的免费编程模型包括一些开源模型的托管版本，具体哪个好用需要自己试。

3.2 免费模型的筛选与实测建议

OpenRouter 上的免费模型质量参差不齐，不是所有标着 “Free” 的都适合编程。我的筛选标准是三条：第一，看上下文长度，至少要有 32K，不然读不了一个中等大小的文件；第二，看模型参数量，太小的模型在代码理解上容易出错；第三，看社区反馈，OpenRouter 的模型页面有使用量统计，用的人多的通常不会太差。

实测下来，免费模型在以下任务上表现还可以：解释单段代码、生成简单函数、写注释、转换代码风格。但在以下任务上容易翻车：跨文件重构、复杂 bug 定位、需要长上下文推理的任务。所以用 OpenRouter 免费模型的时候，尽量把任务拆小，一次只问一个明确的问题。

3.3 OpenRouter 充值与否的取舍

OpenRouter 有充值选项，充值之后可以用付费模型，也可以提高免费模型的调用限额。但如果你只是想用免费模型，不充值也能用，只是要接受限额。充值方式支持多种支付渠道，具体以平台当前支持的为准。

我的建议是：先不充值，把免费额度用一段时间，看看自己实际需要多少调用量。如果发现经常被限流，再考虑充值。不要一上来就充值，因为免费模型和付费模型的差距没有你想象中那么大，很多日常任务免费模型完全够用。

3.4 OpenRouter 配置的常见问题

一个常见问题是 API Key 填对了但调用失败。这时候先检查 Key 有没有多余的空格，再检查 OpenRouter 账号有没有完成验证。有些免费模型要求账号绑定支付方式才能用，即使不扣费。另外，OpenRouter 的接口地址不要写错，配置里通常只需要填 provider 和 Key，地址是内置的。

另一个问题是模型 ID 写错。OpenRouter 的模型 ID 格式通常是厂商/模型名，比如meta-llama/llama-3-8b这种。写错一个字符就会报 “model not found”。建议直接从模型页面复制 ID，不要手打。

4. 本地 Ollama：离线与隐私的终极方案

Ollama 是一个本地大模型运行工具，它把模型下载、加载、推理这些步骤封装得很简单，一条命令就能跑起来。对 OpenCode 用户来说，Ollama 的意义在于：你的代码完全不出本机，而且不依赖网络。代价是你需要有一定的硬件资源，尤其是显存。

4.1 Ollama 安装与国内镜像源处理

Ollama 支持 Windows、macOS、Linux。安装包可以从官方渠道下载，但国内用户经常会遇到下载慢的问题。这时候可以用国内镜像源，具体镜像地址会变化，建议搜索“ollama 国内镜像源”找当前可用的。下载安装包之后，正常安装即可。

安装完成后，运行ollama --version确认安装成功。然后需要下载模型，这一步是最容易卡住的，因为模型文件通常有几个 GB。国内下载模型慢的话，可以配置镜像源，或者用离线安装包的方式，先在其他地方下载好模型文件，再导入。

提示：Ollama 的模型存储路径默认在用户目录下，如果系统盘空间不够，可以在安装前设置环境变量把模型目录指向其他盘。

4.2 模型选择与硬件匹配

Ollama 支持的模型很多，从 1B 到 70B 都有。选模型的核心原则是：模型大小要和你的显存匹配。一个粗略的估算方法是：模型参数量乘以 0.5 到 0.7，得到大概的显存需求（单位 GB）。比如 7B 模型大概需要 4 到 5 GB 显存，14B 需要 8 到 10 GB，32B 需要 20 GB 以上。

如果你的显存不够，模型会回退到 CPU 推理，速度会慢很多。所以选模型之前先看自己的显卡。以下是常见配置的参考：

编程任务建议至少 7B，有条件上 14B。3B 以下的模型在代码理解上经常出错，不太适合正经用。

4.3 OpenCode 接入 Ollama 的配置

Ollama 默认在本地的 11434 端口提供服务。OpenCode 接入 Ollama 的配置大概是这样的：

{ "provider": "ollama", "baseUrl": "http://localhost:11434", "model": "qwen2.5-coder:7b" }

模型名要和你ollama list里显示的一致。配置完之后，先在终端里用ollama run 模型名测试一下模型能不能正常对话，确认没问题再让 OpenCode 调用。

一个常见报错是500 internal server error: llama-server process，这通常是模型加载失败或者显存不足导致的。排查方法是：先看 Ollama 的日志，再确认模型文件有没有损坏，最后检查显存占用。

4.4 本地模型的性能调优

本地模型跑起来之后，如果觉得慢，可以调几个参数。一是num_ctx，控制上下文长度，调小可以省显存；二是num_gpu，控制有多少层跑在 GPU 上，显存够就调大；三是num_thread，控制 CPU 线程数，CPU 推理时有用。

这些参数可以在 OpenCode 的配置里传，也可以在 Ollama 的 Modelfile 里设。我的经验是，先把num_ctx设成 4096 或 8192，够用就行，不要一上来就设很大。上下文越长，显存占用越高，速度越慢。

5. 三条路径的组合使用与切换策略

单独用一条路径都有各自的局限，真正高效的做法是组合使用。我的日常配置是这样的：OpenCode 里配多个 provider，根据任务类型手动切换。轻量问答走 Zen，中等任务走 OpenRouter 免费模型，敏感代码或者断网环境走 Ollama。

5.1 多 provider 配置的写法

OpenCode 的配置文件支持多个 provider，你可以把它们都写进去，用的时候指定。一个多 provider 的配置示例：

{ "providers": { "zen": { "type": "zen" }, "openrouter": { "type": "openrouter", "apiKey": "你的_KEY" }, "ollama": { "type": "ollama", "baseUrl": "http://localhost:11434" } }, "defaultProvider": "zen" }

具体字段名以当前版本为准。配置好之后，在 OpenCode 里应该有切换 provider 的命令，或者通过启动参数指定。

5.2 什么任务走哪条路

我总结了一个简单的判断规则：

• 任务简单、不涉及敏感代码、网络正常：走 Zen，省事。
• 任务中等、需要更好的模型、网络正常：走 OpenRouter 免费模型。
• 任务涉及公司代码、隐私要求高、或者网络不稳定：走 Ollama。
• 任务复杂、免费模型搞不定：考虑 OpenRouter 付费模型，或者本地跑更大的模型。

这个规则不是死的，你可以根据自己的实际情况调整。关键是不要死磕一条路，哪条通走哪条。

5.3 切换时的注意事项

切换 provider 的时候，注意上下文会不会丢失。有些 OpenCode 版本在切换 provider 后会清空当前会话，所以切换前先把重要内容记下来。另外，不同 provider 的模型能力不同，同一个问题在不同模型上得到的回答质量可能差很多，切换后如果回答不理想，可以换个问法再试。

6. 常见问题速查与避坑经验

这一节把我在配置和使用过程中遇到的高频问题整理成速查表，方便你快速定位。

6.1 几个容易忽略的细节

第一个细节是配置文件的位置。不同系统、不同版本的 OpenCode，配置文件路径可能不一样。找不到的时候用opencode config命令或者看官方文档，不要凭感觉猜。

第二个细节是环境变量的优先级。有些配置项既可以在配置文件里写，也可以用环境变量设，环境变量通常优先级更高。如果你改了配置文件没生效，检查一下有没有环境变量覆盖了。

第三个细节是模型名称的大小写和分隔符。Ollama 的模型名用冒号分隔，OpenRouter 的模型 ID 用斜杠分隔，写错就报错。复制粘贴比手打靠谱。

6.2 我踩过的几个坑

第一个坑是 OpenRouter 免费模型的限额。我以为免费就是随便用，结果一天用超了被限流，第二天才恢复。后来我养成了习惯，把重任务集中处理，轻任务分散开，避免短时间内大量调用。

第二个坑是 Ollama 模型选太大。我一开始下了个 32B 的模型，结果显存不够，回退到 CPU 跑，一个回答等了好几分钟。后来换成 7B，速度快了很多，质量也够用。选模型不要贪大，合适最重要。

第三个坑是配置文件格式错误。JSON 对格式要求严格，多一个逗号、少一个引号都会导致解析失败。改完配置之后，用工具校验一下 JSON 格式，能省很多排查时间。

6.3 关于 OpenCode 版本与兼容性

OpenCode 更新比较频繁，不同版本的配置格式可能有变化。如果你照着旧教程配置不成功，先确认版本。另外，OpenCode 有一些周边工具和插件，比如 skills 机制，可以扩展功能，但这些不是必须的，先把基础的三条路径跑通再说。

提示：遇到问题的时候，先看 OpenCode 的日志输出，大部分错误信息都在里面。日志通常比报错信息更详细，能帮你快速定位问题。

7. 从免费模型到稳定工作流的演进建议

三条路径跑通之后，下一步是把它变成稳定的工作流。我的做法是：固定一套配置，写一个启动脚本，把常用的 provider 和模型预设好。这样每次打开 OpenCode 不用重新配，直接进入工作状态。

另外，建议定期检查 OpenRouter 的免费模型列表，因为它是动态变化的。有时候会新上一些不错的免费模型，有时候旧的会下架。保持关注，及时调整配置。

本地 Ollama 这边，建议把常用的模型提前下载好，避免用的时候临时下载。如果硬盘空间够，可以存两三个不同规模的模型，根据任务切换。

最后说一个实际体会：免费模型和付费模型的差距，在简单任务上几乎感觉不到，在复杂任务上才明显。所以如果你的日常任务以简单为主，三条免费路径完全够用，没必要纠结。把省下来的精力放在怎么把问题描述清楚、怎么拆解任务上，收益比换模型大得多。