企业官网建设流程全解析

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

OpenCode 这个终端里的 AI 编程助手，最近在开发者圈子里讨论度很高。它的定位很直接：把大模型能力塞进命令行，让你在终端里就能完成代码补全、重构、解释、生成测试这些事，不用来回切浏览器。但真正让很多人卡住的不是安装，而是模型从哪来。官方自带的免费额度有使用范围限制，一旦在非官方客户端环境里调用，就会撞上那句经典的报错——opencode's free tier can only be used from within opencode。这句话翻译成人话就是：免费池认客户端，换个壳子就不给用。

所以实际能长期跑通的免费方案，基本就三条路：Zen 免费池、OpenRouter 免费模型、本地 Ollama。这三条路不是互相替代的关系，而是对应三种不同的使用心态和场景。我先把选型逻辑讲清楚，后面再逐条拆实操，这样你看的时候能对号入座，不用三条全试一遍。

Zen 免费池的本质是 OpenCode 官方提供的托管额度，优点是零配置、开箱即用，缺点是额度有限、有客户端校验、高峰期可能排队。它适合刚上手、想先跑通流程、验证 OpenCode 到底顺不顺手的人。你不需要注册第三方账号，不需要配密钥，装完就能对话，这是它最大的价值。

OpenRouter 免费模型走的是聚合平台路线。OpenRouter 本身是一个模型路由服务，把各家模型统一成一个 API 接口，里面有一批标注:free的模型可以零成本调用。它的优点是模型选择多、可以随时切换、免费额度相对慷慨；缺点是需要注册、需要拿 API Key、部分免费模型有速率限制，而且充值渠道对国内用户不算友好。它适合已经确定要长期用 OpenCode、愿意花十分钟做一次配置的人。

本地 Ollama 是彻底的自给自足方案。模型跑在你自己机器上，不依赖任何外部服务，没有额度、没有速率限制、没有网络波动，隐私性最好。代价是吃硬件——内存、显存、磁盘都得够，而且小参数模型的能力和云端大模型有明显差距。它适合有独立显卡或大内存机器、对数据隐私敏感、或者网络环境不稳定的人。

把这三条路放在一张表里对比，选型会清晰很多：

我的建议是：先用 Zen 跑通，再用 OpenRouter 转正，Ollama 作为备份或隐私场景补充。这个顺序符合学习曲线，也避免一上来就被硬件或配置劝退。下面逐条展开。

2. Zen 免费池：零配置起步与客户端校验的坑

2.1 Zen 免费池到底是什么

Zen 是 OpenCode 生态里内置的模型服务入口，你可以理解成官方给你开的一个"体验账户"。它背后挂的模型会随版本更新调整，但整体定位是"够用、稳定、免配置"。装好 OpenCode 之后，默认的模型列表里就能看到 Zen 相关的条目，选中就能对话，不需要你填任何密钥。

这个设计对新手非常友好。很多人第一次接触终端 AI 助手，最怕的就是"装完了不知道怎么让它说话"。Zen 把这一步的门槛降到了零，你打开终端、进项目目录、敲opencode，它就能开始工作。代码解释、小段重构、写个正则、生成单元测试，这些日常需求 Zen 都能接住。

但它的限制也很明确。第一是额度，免费池不是无限用的，用超了会提示你切换或等待。第二是客户端校验，也就是那句报错的来源。OpenCode 会检查调用来源，如果不是从它自己的客户端发起的请求，免费池就拒绝服务。这个机制本身是为了防止额度被滥用，但对用户来说，意味着你不能把 Zen 的额度"借"给别的工具用。

2.2 从安装到第一次对话的完整流程

安装 OpenCode 的方式取决于你的系统。macOS 和 Linux 用户通常用包管理器或官方脚本，Windows 用户建议在 WSL 里跑，因为终端体验和依赖兼容性都更好。装完之后，第一次运行会在用户目录下生成配置文件夹，模型设置、会话历史、技能配置都在里面。

启动流程大致是这样：

# 进入你的项目目录 cd ~/projects/my-app # 启动 opencode opencode # 首次启动会引导你选择模型 # 在模型列表里选择 Zen 相关的免费条目

进去之后，你可以先用一句简单的话测试连通性，比如让它解释当前目录下某个文件的作用。如果它能正常返回，说明 Zen 免费池已经通了。这时候你可以开始试更复杂的任务，比如"把这个函数拆成三个小函数并加上类型注解"，观察它的输出质量是否符合预期。

提示：第一次用建议先拿一个不重要的测试项目练手，别直接在生产仓库里让它改代码。AI 助手的输出需要你 review，养成"先看 diff 再接受"的习惯。

2.3 客户端校验报错的真实原因与应对

那句opencode's free tier can only be used from within opencode是很多人踩的第一个坑。它的触发场景通常是：你把 OpenCode 的配置或额度信息复制到了别的工具里，或者用第三方客户端去调 OpenCode 的接口。系统检测到请求来源不对，直接拒绝。

应对方式其实很简单：老老实实在 OpenCode 自己的客户端里用。如果你确实需要把模型能力接到别的工具上，那就别指望 Zen 免费池，转去 OpenRouter 或本地 Ollama。这不是 bug，是设计如此，跟它较劲没意义。

还有一个容易忽略的点：Zen 免费池的可用模型会随版本变化。有时候你昨天还能用的模型，今天更新后列表里就没了。遇到这种情况，先检查 OpenCode 是不是自动更新了，然后在模型列表里重新选一个可用的免费条目即可。别慌，这不是你的配置坏了。

2.4 Zen 免费池的实操心得

我用下来的体会是，Zen 适合做轻量、高频、低风险的任务。比如：

• 解释一段看不懂的代码
• 给变量起名、写注释
• 生成简单的正则或 SQL
• 把一段逻辑翻译成另一种语言
• 快速写个测试骨架

这些任务对模型能力要求不高，Zen 完全够用，而且响应快、不花钱。但如果你要它做复杂的架构重构、跨文件的大改动，它的能力边界就会显现，输出质量会下降。这时候就该考虑换更强的模型了。

另外，Zen 的额度消耗和你的使用强度直接相关。长对话、大文件、反复追问都会加速消耗。我的习惯是：一个任务开一个新会话，别在一个会话里聊几十轮，既省额度又避免上下文污染。

3. OpenRouter 免费模型：注册、密钥与模型筛选

3.1 OpenRouter 是什么，为什么值得配

OpenRouter 是一个模型聚合路由平台。它把不同厂商的模型统一到一个 API 接口下，你只需要一个密钥，就能调用平台上的各种模型。对 OpenCode 用户来说，它的价值在于：模型选择多、有免费档、切换成本低。

平台里有一批模型带:free后缀，这些是可以零成本调用的。它们的参数规模、能力水平参差不齐，有的适合写代码，有的适合聊天，有的适合长文本。你需要做的是筛选出适合编程任务的免费模型，然后配到 OpenCode 里。

相比 Zen，OpenRouter 的优势是不绑定客户端。你在 OpenCode 里能用，在别的支持 OpenAI 兼容接口的工具里也能用。这意味着你的配置是可迁移的，不会因为换个工具就作废。这是它值得花时间配置的核心理由。

3.2 获取 API Key 的完整步骤

注册流程不复杂，但有几个细节要注意。打开 OpenRouter 官网，用邮箱注册账号，验证之后进入控制台。在密钥管理页面创建一个新的 API Key，复制保存好——这个 Key 通常只显示一次，关掉页面就看不到了。

拿到 Key 之后，回到 OpenCode 的配置里填入。OpenCode 支持 OpenAI 兼容的接口配置，你需要设置三个东西：

{ "provider": "openrouter", "baseURL": "https://openrouter.ai/api/v1", "apiKey": "你的密钥" }

具体字段名可能随版本略有差异，但核心就是这三项：接口地址、密钥、模型名。模型名要填 OpenRouter 上的完整标识，比如某个带:free后缀的模型 ID。填错模型名会直接报错，这是最常见的配置问题。

注意：密钥属于敏感信息，别提交到 Git 仓库里。建议放在环境变量或本地配置文件里，并在.gitignore中排除配置文件。

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

OpenRouter 上的免费模型很多，但不是每个都适合编程。筛选时我一般看几个指标：上下文长度、是否支持工具调用、社区反馈。上下文太短的模型处理不了大文件，不支持工具调用的模型没法用 OpenCode 的一些高级功能。

实测下来，免费档里适合编程的模型通常有这些特征：参数规模在中等以上、专门针对代码做过训练、响应速度可接受。你可以先在 OpenRouter 的模型列表里按"免费"筛选，然后逐个试。试的时候用同一个任务对比，比如"给这个函数写单元测试"，看哪个输出质量最好。

这里有个经验：免费模型的高峰期会限速。如果你发现响应特别慢或者频繁报错，可能是当前时段负载高。换个时间段再试，或者临时切到别的免费模型，通常能缓解。

3.4 充值、支付与额度管理

OpenRouter 的免费额度用完之后，可以充值继续用付费模型。支付渠道对国内用户不算特别友好，通常需要支持国际支付的卡。如果你只是用免费档，这部分可以先不管。

额度管理上，建议在控制台里设置用量上限，避免意外超支。免费模型虽然不花钱，但有些平台会对免费调用做频率限制，设置上限也能帮你监控使用情况。另外，定期检查密钥的使用记录，发现异常调用及时吊销重建，这是基本的安全习惯。

3.5 OpenRouter 配置的避坑要点

几个我踩过的坑，提前说清楚：

第一，模型名必须精确。OpenRouter 的模型 ID 是大小写敏感的，少一个字符都调不通。复制的时候别手打，直接复制粘贴。

第二，接口地址别写错。OpenAI 兼容接口的路径是固定的，写错了会返回 404。如果你不确定，去 OpenRouter 的文档页复制标准配置。

第三，免费模型会下架。平台上的免费模型是动态调整的，今天能用的明天可能就没了。遇到突然报错，先去模型列表确认这个模型还在不在。

第四，别把密钥分享出去。网上有些所谓的"密钥大全"帖子，里面的密钥要么已失效，要么来路不明，用了可能被封号。自己注册一个，几分钟的事。

4. 本地 Ollama：部署、拉模型与国内加速

4.1 Ollama 的定位与硬件门槛

Ollama 是一个本地大模型运行时，它把模型的下载、加载、推理都封装成了简单命令。装好之后，一行ollama run 模型名就能开始对话。对 OpenCode 来说，Ollama 提供的是 OpenAI 兼容的本地接口，配上去就能用。

它的最大卖点是完全本地。模型跑在你自己的机器上，数据不出本机，没有额度、没有速率限制、断网也能用（前提是模型已经拉下来）。对处理敏感代码、或者网络环境不稳定的人来说，这是刚需。

但硬件门槛是绕不开的。模型参数越大，对内存和显存的要求越高。粗略的经验是：7B 级别的模型，量化后大概需要 8G 左右内存；13B 需要 16G 上下；再往上就得看显存了。如果你的机器只有 8G 内存，跑小参数模型可以，但别指望它能处理复杂任务。

4.2 安装与首次拉取模型

安装 Ollama 本身很简单，官网下载对应系统的安装包，一路下一步即可。Windows 用户注意，安装后它会在后台起一个服务，OpenCode 通过本地端口和它通信。

装完之后，拉一个模型测试：

# 拉取一个适合编程的小参数模型 ollama pull qwen2.5-coder:7b # 运行测试 ollama run qwen2.5-coder:7b

拉取过程会下载几个 G 的文件，速度取决于你的网络。国内用户经常会遇到下载慢的问题，这时候需要配置镜像源。Ollama 支持通过环境变量指定镜像地址，设置之后重新拉取，速度会有明显改善。

提示：模型文件占磁盘空间，几个模型下来就是几十 G。建议定期清理不用的模型，命令是ollama rm 模型名。

4.3 国内下载慢的解决思路

下载慢是本地部署最常见的痛点。原因通常是默认的模型仓库在境外，直连速度不稳定。解决办法是换镜像源。Ollama 允许通过环境变量覆盖默认的仓库地址，把它指向国内的镜像服务，下载速度能提升不少。

设置方式是在启动 Ollama 服务前配置环境变量。Linux 和 macOS 可以在 shell 配置里加，Windows 在系统环境变量里加。设置完重启服务，再拉模型就会走镜像。

如果镜像源也不稳定，还有个办法是手动下载模型文件。有些社区会提供模型的离线包，下载后用ollama create从本地文件导入。这个方式麻烦一点，但适合网络条件特别差的情况。

4.4 把 Ollama 接入 OpenCode

Ollama 默认在本地某个端口提供 OpenAI 兼容接口。在 OpenCode 的配置里，把 provider 指向本地地址即可：

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

注意这里的 apiKey 随便填一个占位符就行，本地服务不校验。模型名要和你ollama list里看到的完全一致。

配好之后测试一下，让它解释一段代码。如果响应正常，说明链路通了。本地模型的响应速度取决于硬件，第一次加载模型会慢一些，之后会快起来。

4.5 本地模型的现实预期

我得说句实话：本地小模型的能力和云端大模型有差距。7B 级别的模型写简单代码、做代码解释没问题，但遇到复杂逻辑、跨文件重构，输出质量会明显下降。它的价值在于隐私和离线，不在于能力对标。

所以我的用法是：日常轻量任务用本地模型，复杂任务切云端。这样既保护了敏感代码，又在需要时用上了更强的能力。别指望一个 7B 模型能替代云端大模型，那不现实。

另外，本地模型的上下文长度通常也有限。处理大文件时要注意，超出上下文的部分会被截断，导致输出不完整。遇到这种情况，把任务拆小，分多次处理。

5. 三条路径的切换与常见问题速查

5.1 在 OpenCode 里灵活切换模型

OpenCode 的模型配置支持多套方案并存。你可以在配置文件里定义多个 provider，然后在会话里切换。这样一条路不通时，能快速换另一条，不用重新配置。

切换的粒度可以是全局的，也可以是单次会话的。全局切换改配置文件，单次切换在启动时指定。我的习惯是：默认用 OpenRouter，网络不好时切 Ollama，临时试新东西用 Zen。这个组合覆盖了大部分场景。

切换时要注意，不同模型的上下文长度和输出风格不一样。换模型后，之前的长对话可能因为上下文超限而表现异常。建议换模型时开新会话，避免上下文混乱。

5.2 常见报错与排查表

下面这张表是我整理的高频问题和对应解法，遇到报错先查这里：

5.3 独家避坑经验

几个从实际使用里总结出来的点，文档里通常不会写：

第一，配置文件备份。OpenCode 更新有时会重置配置，提前把配置文件复制一份，更新后对比恢复，能省不少事。

第二，密钥轮换。定期更换 API Key，尤其是怀疑泄露时。OpenRouter 控制台可以一键吊销旧密钥，操作很快。

第三，模型名用变量管理。如果你经常切换模型，把模型名抽成环境变量，改一处就全局生效，比到处改配置文件省心。

第四，本地模型别贪大。参数越大越吃硬件，跑不动的模型不如不跑。选一个你机器能流畅运行的，比选一个跑起来卡顿的强。

第五，善用会话隔离。不同任务开不同会话，既省额度又避免上下文污染。这个习惯在三条路径上都适用。

5.4 关于"只思考不回答"和技能配置

有用户反馈 OpenCode 有时"只思考不回答"，这通常是模型输出被截断或工具调用卡住导致的。排查方向：检查模型是否支持工具调用、上下文是否超限、网络是否稳定。换个模型或开新会话，多数情况能解决。

OpenCode 的技能（skill）机制允许你扩展它的能力，比如接入特定的代码规范检查、自定义命令等。技能配置放在配置目录下，安装和使用方式随版本有差异，建议以官方文档为准。技能用好了能显著提升效率，但别一上来就装一堆，先跑通基础流程再说。

6. 我的实际组合方案与长期维护建议

跑了一段时间之后，我现在的固定组合是这样的：主力用 OpenRouter 的免费编程模型，本地 Ollama 跑一个小参数模型做隐私任务和离线备份，Zen 留着做快速验证。这个组合的好处是，任何一条路出问题，都有备选，不会卡住工作流。

维护上，我每周会做几件事：检查 OpenRouter 的免费模型列表有没有变化、清理 Ollama 里不用的模型释放磁盘、确认配置文件没被更新覆盖。这几件事加起来不到十分钟，但能避免很多突发问题。

最后分享一个实用技巧：把三条路径的配置写成模板，存在一个单独的文件里。需要切换时，复制对应段落覆盖当前配置即可。这样比每次手动改字段快得多，也不容易出错。配置这东西，一次整理好，长期受益。

如果你刚开始接触，别想着一次把三条路全配通。先把 Zen 跑起来，感受一下 OpenCode 的工作方式；觉得顺手了，再花时间配 OpenRouter；有隐私需求或硬件条件，再上 Ollama。一步一步来，比一口气全上要稳得多。