OpenCode 这个工具最近在开发者圈子里讨论度很高但真正让大多数人卡住的不是它怎么装而是装完之后怎么让它跑起来不花钱。官方免费池有使用限制OpenRouter 的免费模型额度规则经常变本地 Ollama 又涉及下载和配置的一堆坑。我把这三条路径都完整走了一遍下面按实际操作的顺序拆开讲每一步都附上我踩过的坑和验证过的配置。1. 先搞清楚 OpenCode 的模型调用逻辑1.1 它和普通 AI 编程插件的区别在哪OpenCode 的定位不是一个简单的代码补全工具它更像是一个跑在终端里的编程代理。你可以用自然语言让它读项目文件、改代码、跑命令、做重构。这种工作方式决定了它对模型能力的要求比单纯的补全高得多——它需要模型能理解上下文、能做多步推理、能调用工具。这就引出一个关键问题模型从哪来。OpenCode 本身不训练模型它是一个客户端需要接后端模型服务。目前它支持三种接入方式官方自带的 Zen 免费池、OpenRouter 这类第三方模型聚合平台、以及本地跑的 Ollama。三条路径的成本、门槛、稳定性完全不同。我一开始以为随便接一个就行实际用下来发现选错了路径会浪费大量时间。比如你如果只是想试试 OpenCode 的基本功能直接用它自带的免费池最省事但如果你要长期用来做正式项目开发本地 Ollama 或者 OpenRouter 付费额度才是靠谱选择。1.2 配置文件 opencode.json 是整个接入的核心不管你走哪条路径最终都要落到一个配置文件上。OpenCode 读取的配置文件名是opencode.json放在项目根目录或者用户配置目录下。这个文件决定了它用哪个 provider、哪个模型、以及相关的认证信息。一个最常见的误区是很多人装完 OpenCode 就直接在终端里敲命令发现报错error from provider (console): opencodes free tier can only be used from within opencode然后一脸懵。这个报错的含义其实很明确——你用的免费额度只能在 OpenCode 自己的客户端里调用不能拿到别的地方用。这不是 bug是设计如此。所以第一步永远是先把opencode.json的结构搞清楚。它的基本骨架长这样{ provider: { openrouter: { npm: openrouter/ai-sdk-provider, options: { apiKey: 你的密钥 } } }, model: openrouter/anthropic/claude-3.5-sonnet }不同 provider 的字段名和嵌套结构会有差异后面每条路径我会给出对应的完整配置。这里先记住一个原则provider 字段决定用哪家服务model 字段决定用哪个具体模型options 里放认证和参数。1.3 三条路径的适用场景对比在动手之前先根据你的实际情况选路径能省很多事。我整理了一个对比表维度Zen 免费池OpenRouter 免费模型本地 Ollama上手难度最低中等中等偏高是否需要注册否是否是否需要付费否免费额度有限否网络要求需要能访问官方服务需要能访问 OpenRouter完全本地模型能力中等可选范围大取决于本地硬件稳定性一般有额度限制免费模型经常限流取决于本机性能适合场景快速体验灵活切换模型隐私敏感、长期使用如果你只是想花十分钟看看 OpenCode 到底能干什么走第一条。如果你需要经常换不同模型对比效果走第二条。如果你对代码隐私有要求或者想在没有网络的环境下用走第三条。2. Zen 免费池零配置起步但要知道边界2.1 免费池到底免费在哪OpenCode 自带的 Zen 免费池本质上是官方提供的一个共享模型端点。你不需要注册任何账号不需要填 API key装完就能用。这对第一次接触的人来说非常友好。但它的限制也很明确。第一只能在 OpenCode 客户端内部调用你没法把这个额度拿去接别的工具。第二有调用频率和总量的限制具体数值官方没有公开固定值会根据负载动态调整。第三可选的模型范围有限通常是一些中等能力的模型做简单的代码理解和修改够用但复杂重构会力不从心。我第一次用的时候拿它改一个两百行的 Python 脚本理解需求没问题但涉及到跨文件的依赖分析就开始出错。所以我的建议是免费池用来熟悉 OpenCode 的交互方式和工作流不要指望它扛正式项目的开发任务。2.2 触发免费池的正确姿势很多人遇到opencodes free tier can only be used from within opencode这个报错是因为他们在配置文件里手动指定了别的 provider但又想蹭免费额度。正确做法是如果你要用免费池就不要在opencode.json里配置任何 provider让 OpenCode 走默认逻辑。具体操作是确保你的项目目录下没有opencode.json或者这个文件里没有覆盖默认 provider 的配置。然后直接在终端里启动 OpenCode它会自动连接到免费池。如果你之前配过别的 provider想切回免费池最简单的办法是把opencode.json临时改名或者删掉。我一般会把它重命名为opencode.json.bak需要的时候再改回来。注意免费池的可用性会随官方策略调整如果你发现突然不能用了先检查是不是官方收紧了额度而不是怀疑自己的配置。2.3 免费池实际能做什么、不能做什么我用免费池跑了一周总结出它的能力边界。能做的单文件代码解释、简单的函数改写、生成基础测试用例、回答编程概念问题。不能做的跨多文件的架构级重构、需要长上下文记忆的连续对话、对性能要求高的代码生成。还有一个容易被忽略的点免费池的响应速度不稳定。高峰期可能要等十几秒才出结果这在交互式编程里体验很差。如果你追求流畅度还是得走另外两条路。3. OpenRouter 免费模型灵活但要会挑3.1 OpenRouter 是什么为什么值得用OpenRouter 是一个模型聚合平台它把市面上主流的模型服务整合到一个统一的 API 接口下。你只需要一个 OpenRouter 的密钥就能调用它上面挂载的各种模型包括不少免费额度的模型。对 OpenCode 用户来说OpenRouter 的价值在于你可以用同一个配置随时切换不同厂商的模型对比哪个更适合你的任务。而且它上面有一些免费模型额度给得还算大方适合中等强度的日常使用。但这里有个前提你得先拿到 OpenRouter 的 API key。获取流程不复杂注册账号后在后台生成即可。需要注意的是部分免费模型需要你账户里有最低充值记录才能解锁这个规则经常变用之前最好去官网确认当前政策。3.2 配置 OpenRouter 接入的完整步骤第一步拿到 API key。登录 OpenRouter 后台在密钥管理页面创建一个新的 key复制保存好。这个 key 只显示一次丢了就得重新建。第二步在项目根目录创建opencode.json写入以下配置{ provider: { openrouter: { npm: openrouter/ai-sdk-provider, options: { apiKey: sk-or-v1-你的密钥 } } }, model: openrouter/google/gemini-2.0-flash-exp:free }注意 model 字段的格式是openrouter/厂商/模型名。带:free后缀的是免费版本不带的就是付费的。选模型的时候一定要看清楚后缀不然可能产生费用。第三步保存文件后在终端启动 OpenCode它会读取这个配置并连接到 OpenRouter。如果报认证错误检查 key 有没有复制完整或者有没有多余的空格。3.3 免费模型的挑选和限流应对OpenRouter 上的免费模型不是无限用的通常有每分钟请求数和每天总量的限制。我实测下来免费模型在高峰期经常返回 429 错误也就是限流。应对办法有几个。一是错峰使用避开欧美时区的白天。二是在配置里设置重试逻辑OpenCode 本身支持一定程度的自动重试但效果有限。三是准备多个免费模型作为备选一个限流了就换另一个。我常用的几个免费模型包括 Gemini 的 flash 系列和一些开源模型的托管版本。具体哪个好用建议你自己跑几个任务对比一下因为模型更新很快我今天的推荐下个月可能就过时了。提示OpenRouter 的免费额度政策变动频繁如果你打算长期依赖它建议定期查看官网的模型列表和额度说明不要假设今天的配置明天还能用。3.4 充值相关的实际问题如果你发现免费模型不够用想充值升级OpenRouter 支持多种支付方式。充值后可以解锁更多模型和更高的调用额度。但这里要提醒一点充值时注意区分 credits 和订阅两者计费方式不同。credits 是按量扣费用多少扣多少订阅是固定周期收费。根据你的使用频率选合适的。另外充值后你的免费模型额度通常也会提升但不是所有模型都适用。具体规则以官网为准。4. 本地 Ollama最可控但配置最繁琐4.1 为什么值得折腾本地部署本地 Ollama 的最大优势是数据不出本机。你让模型读的代码、改的文件全程在本地处理不经过任何外部服务。对于处理公司内部代码或者有隐私要求的项目这是唯一可行的方案。第二个优势是稳定。不受网络波动影响不受平台限流影响只要你的机器能跑它就一直在。第三个优势是免费跑本地模型不产生任何 API 费用电费除外。代价是硬件门槛和配置复杂度。模型越大对显存和内存的要求越高。而且 Ollama 的下载和安装在国内网络环境下有一些需要注意的地方。4.2 Ollama 安装与模型下载的避坑要点安装 Ollama 本身不复杂官网有各平台的安装包。但下载模型这一步是大多数人卡住的地方。默认的模型仓库在国内访问速度很慢一个几 GB 的模型可能下几个小时还断。解决办法是配置镜像源。Ollama 支持通过环境变量指定模型下载的镜像地址。具体做法是在启动 Ollama 服务前设置对应的环境变量指向国内的镜像站点。不同操作系统的设置方式不同Linux 和 macOS 用 exportWindows 用系统环境变量界面或者 PowerShell 的 $env 语法。设置好镜像源之后下载速度会有明显提升。我实测同一个模型默认源下了四十分钟还没完换镜像源之后几分钟就搞定了。还有一个坑是模型名称的写法。Ollama 的模型命名有固定格式比如qwen2.5:7b表示通义千问 2.5 版本的 7B 参数模型。写错了会报找不到模型。建议先用ollama list看看本地已经有哪些模型再用ollama pull 模型名下载新的。4.3 把 Ollama 接进 OpenCode 的配置细节Ollama 默认在本地的 11434 端口提供服务。OpenCode 要连它需要在opencode.json里配置对应的 provider。配置大概长这样{ provider: { ollama: { npm: ai-sdk/openai-compatible, options: { baseURL: http://localhost:11434/v1 } } }, model: ollama/qwen2.5:7b }这里的关键是 baseURL 要指向 Ollama 的 OpenAI 兼容接口也就是带/v1后缀的那个地址。很多人只写http://localhost:11434结果连不上就是因为少了这个后缀。model 字段里的模型名必须和你本地通过ollama list看到的名称完全一致。大小写、冒号、版本号都不能错。4.4 本地模型的性能调优和常见报错本地跑模型最常见的报错是显存不足。表现是模型加载到一半就失败或者运行中突然崩溃。解决办法是换更小的模型比如从 7B 降到 3B或者用量化版本。量化版本用更低的精度存储模型参数显存占用能降不少代价是输出质量略有下降。另一个常见问题是响应速度慢。如果你用的是 CPU 推理而不是 GPU速度会差一个数量级。检查 Ollama 有没有正确识别到你的显卡可以在启动日志里看到相关信息。还有一个报错是500 internal server error: llama-server process这通常是模型文件损坏或者版本不兼容导致的。解决办法是删掉重新下载或者换一个模型版本试试。注意本地模型的上下文长度通常比云端模型短处理大文件时可能被截断。如果你的项目文件很大要么换支持长上下文的模型要么把任务拆小。5. 三条路径的切换与组合使用5.1 用多个配置文件快速切换实际使用中你不太可能只固定用一条路径。我的做法是准备多个配置文件比如opencode.zen.json、opencode.openrouter.json、opencode.ollama.json需要哪个就把哪个复制成opencode.json。这样切换的好处是不用每次手动改配置内容减少出错概率。你可以写一个简单的 shell 脚本或者 alias 来一键切换比如alias oc-zencp opencode.zen.json opencode.json opencode alias oc-orcp opencode.openrouter.json opencode.json opencode alias oc-localcp opencode.ollama.json opencode.json opencode这样在终端里敲oc-local就直接用本地模型启动非常方便。5.2 什么任务用哪条路径根据我的经验可以按任务类型来分配。快速验证想法、写个简单脚本用 Zen 免费池启动最快。需要对比不同模型效果、或者免费池限流了切 OpenRouter。处理敏感代码、或者网络不好的时候用本地 Ollama。还有一个小技巧把 OpenCode 的默认模型设成免费池然后在具体任务里临时切换到更强的模型。这样日常轻量使用不花钱遇到难题再上重武器。5.3 配置文件的版本管理建议opencode.json里可能包含 API key所以不建议直接提交到公开的代码仓库。我的做法是把真正的配置文件加入.gitignore然后提交一个opencode.example.json作为模板里面用占位符代替真实密钥。这样团队协作时每个人复制模板填自己的 key既方便又安全。如果你用的是本地 Ollama没有密钥问题但模型名称可能因机器而异模板里也可以标注清楚。6. 我踩过的几个典型坑和解决过程6.1 免费池报错的完整排查链路第一次遇到opencodes free tier can only be used from within opencode的时候我以为是网络问题折腾了半天网络设置。后来才意识到这个报错的字面意思就是答案免费额度只能在 OpenCode 内部用。我当时是在一个脚本里直接调用了 OpenCode 的底层接口绕过了客户端所以被拒绝了。排查这类问题的思路是先看报错信息的字面含义不要急着往复杂方向想。大多数报错其实说得很清楚只是我们习惯性地忽略。然后再检查配置文件有没有覆盖默认行为最后才考虑网络和服务端问题。6.2 OpenRouter 密钥无效的几种原因OpenRouter 的密钥报无效常见原因有三个。一是复制的时候带了空格或者换行这个最容易被忽略。二是密钥被禁用或者删除了去后台确认一下状态。三是账户余额或者信用问题导致密钥被临时冻结。我遇到过一次是密钥复制时末尾多了一个空格肉眼完全看不出来排查了半小时。后来养成习惯粘贴密钥后先用echo打印出来检查一遍长度和首尾字符。6.3 Ollama 模型下载中断的处理Ollama 下载模型中断后重新执行ollama pull通常会断点续传但有时候会卡住不动。这时候可以先把那个模型删掉用ollama rm 模型名然后重新下载。虽然要从头开始但比卡着不动强。如果反复下载失败检查镜像源配置有没有生效。可以在下载时观察速度如果一直是几百 KB 每秒说明镜像源没起作用或者镜像源本身也慢。换一个镜像源再试。6.4 配置文件格式错误的快速定位JSON 格式对逗号和引号非常敏感多一个少一个都会导致解析失败。OpenCode 启动时报配置文件错误但不会告诉你具体哪一行有问题。我的办法是用在线的 JSON 校验工具先验证一遍或者用编辑器的 JSON 格式化功能它会自动标出语法错误的位置。还有一个隐蔽的问题是注释。标准 JSON 不支持注释但有些人习惯性加//说明导致解析失败。如果你需要写说明用单独的文档文件不要写在 JSON 里。7. 关于模型选择和长期使用的几点体会7.1 不要迷信大模型合适最重要我用过各种参数规模的模型最后发现对于 OpenCode 这种编程辅助场景模型大小不是唯一决定因素。一个 7B 的代码专用模型在代码任务上可能比一个 70B 的通用模型表现更好。关键是看模型有没有针对代码场景做优化。选模型的时候先明确你的主要任务是什么。如果主要是代码补全和修改优先选代码专用模型。如果需要模型理解自然语言需求并做规划选通用能力强的。如果两者都要那就准备两个模型按需切换。7.2 本地模型的硬件投入要算清楚本地部署听起来免费但硬件成本是实打实的。要流畅跑 7B 模型至少需要 8GB 以上的显存。要跑 13B 以上16GB 显存起步。如果你的机器达不到要么升级硬件要么接受慢速推理要么回到云端方案。我的建议是先用云端方案验证 OpenCode 对你的价值。如果确实能提升效率再考虑投入硬件做本地部署。不要一上来就为了本地部署买显卡结果发现用不上。7.3 保持配置的可维护性三条路径的配置会随着官方政策、模型更新、本地环境变化而需要调整。我的做法是给每个配置文件加一个简短的说明文档记录这个配置对应的模型、获取密钥的方式、以及上次验证可用的日期。这样过几个月回头看能快速回忆起当时的配置逻辑不用重新摸索。另外定期检查官方文档和社区讨论了解有没有新的免费模型或者配置方式。这个领域变化很快今天好用的方案下个月可能就有更好的替代。7.4 一个实用的小习惯每次切换配置或者更新模型后先用一个简单任务测试一下比如让 OpenCode 解释一段代码或者改一个明显的 bug。确认能正常工作再投入到正式任务里。这样能避免在关键时刻发现配置有问题浪费大量时间排查。我一般会准备一个test.py文件里面放几个故意写错的小函数用来快速验证模型能不能正确识别和修复。这个习惯帮我省了很多次在正式项目里才发现配置错误的尴尬。