OpenCode 是一个开源的终端 AI 编程助手它把“在终端里完成代码生成、解释、重构和审查”这件事做得非常直接你在命令行里发起任务它负责组织上下文、调用模型并回填结果。很多人第一次听到“Opencode 涨价”时会误以为是这个工具开始收费其实 OpenCode 本身是开源且免费的真正产生费用的是它背后调用的模型 API。当模型 API 价格调整之后最合理的应对不是立刻换工具而是调整“路由策略”把不同类型的请求转发给不同来源的模型包括免费模型和本地模型。这篇文章就围绕这条主线展开会依次讲清楚 OpenCode 的请求链路、安装方式、免费路由配置、个性化规则以及常见报错的排查路径。读完你可以搭建一套“费用可控、越用越贴合自己习惯”的终端 AI 工作流。1. 先把“OpenCode 涨价”和“免费路由”这两件事拆开1.1 OpenCode 不收钱收钱的是模型 APIOpenCode 是一个运行在终端里的 AI 编码助手功能上类似在命令行里多了一个懂代码的结对开发者。它本身是开源项目安装后可以直接运行不需要为“使用 OpenCode 这个工具”付费。真正的成本来自它调用的模型服务当你选择某个云厂商的大模型 API供应商会按输入 token 和输出 token 计费当供应商调整价格或者你每天的使用量变大账面上的开销就会明显上涨。所以“Opencode 涨价”这种说法准确理解应该是“OpenCode 背后接的模型 API 涨价导致使用成本上升”。工具没有变贵变贵的是令牌数量乘以单价。这个区分很重要因为它决定了省钱的方向不是找一个更便宜的“OpenCode 替代品”而是给同一个 OpenCode 配上更便宜的模型来源或者让不同任务走不同价位的模型。另一个常见的误解是把“免费路由”理解成网络层的路由器。其实这里说的“路由”是从请求转发的角度借用的概念OpenCode 收到你的指令后需要决定把请求发给哪个供应商、哪个模型这个决定过程就是一次“路由选择”。“免费路由”指的是我们手动配置一套分流规则让日常任务优先走免费模型敏感或本地任务走本地模型只有少数高难度任务才调用付费的强模型。1.2 “路由”在 AI 编程工具里的含义在计算机网络里路由器会根据目的 IP 和路由表选择下一跳在 OpenCode 里配置系统会根据模型标识和供应商配置决定把请求发送到哪个 API 端点。我们可以把 OpenCode 的配置理解成一张简化版的“路由表”输入条件路由结果用户没有特别指定模型走配置里的默认模型用户在交互界面手动切模型走当前会话选中的模型项目规则文件要求使用本地模型按规则里的模型标识走本地服务请求的模型标识以ollama/开头走本机 Ollama 服务这张表里的每一行背后都对应一份配置或一次用户操作。免费路由的核心工作就是把你最常使用的几条路径改成免费或几乎免费的来源同时保证质量下降在可接受范围内。这套思路的优点是工具链不换记忆和规则不丢只是把“出口”换掉了。缺点是免费模型在推理能力、上下文长度和限流策略上通常弱于付费模型所以不能无脑全量切换要先明确哪些任务可以接受较弱模型。1.3 免费路由方案适合谁、不适合谁免费路由并不是放之四海皆准的银弹。它更适合以下场景个人学习和技术探索回答本身就是过程价值不追求最强推理。日常代码解释、命名建议、小范围重构、写单元测试。涉及私有代码、不方便外发的项目适合走本地模型。预算有限的独立开发者或学生希望把模型费用压到接近零。不适合的场景也要说清楚企业生产环境对安全合规、可审计性要求高使用免费模型要评估数据出域边界。复杂架构设计、大规模重构、深度调试等问题免费小模型容易一本正经地给出错误答案。对延迟敏感的场景本地模型在低配置机器上可能比云 API 慢得多。一句话总结免费路由是先想清楚“哪些任务便宜也能做好”再动手配置而不是把所有任务都塞给同一个免费模型。2. 安装 OpenCode先跑起来再谈省钱2.1 推荐安装方式和版本确认OpenCode 的常见安装方式有两种一种是 npm 全局安装另一种是通过官方安装脚本安装。两者效果接近选择你更熟悉的方式即可。npm install -g opencode-ai opencode --version如果你的环境已经有 Node.js 和 npm这种安装方式最直接。安装后的命令名是opencode注意 npm 包名是opencode-ai不要写成opencode否则可能装到一个无关包。不使用 Node.js 的环境可以用官方安装脚本curl -fsSL https://opencode.ai/install | bash安装完成后第一步永远先确认版本再去看配置文档。不同版本的配置字段、默认行为可能有差异尤其是你看到版本号已经是 2.x 的时候不要直接照抄网上的旧配置先跑一次opencode --help和opencode --version确认当前版本支持哪些参数。2.2 安装后提示“无法识别”怎么排查Windows 上最常见的安装报错长这样opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个报错的原因非常单一npm 全局安装目录不在系统 PATH 环境变量里终端找不到可执行文件。检查方式如下npm config get prefix npm root -g拿到 npm 的全局目录后把bin子目录加入 PATH。以 macOS 和 Linux 为例如果 npm 的 prefix 是$HOME/.npm-global可以这样配置npm config set prefix $HOME/.npm-global echo export PATH$HOME/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrcWindows 用户在 PowerShell 里检查npm config get prefix $env:Path然后把%APPDATA%\npm添加到用户 PATH。添加后要新开一个终端窗口让环境变量重新加载。注意即使 PATH 修好了旧终端也未必能立刻识别最省事的方法是重启终端。还有一类情况是使用第三方脚本或某个“一键配置”项目安装这类脚本可能修改了 PATH、配置目录或环境变量排除问题时先把配置文件备份再用官方安装方式覆盖安装能减少很多干扰。2.3 完成第一次模型供应商登录OpenCode 不会帮你免费“变出”模型它需要读取某个供应商的认证信息才能发起请求。对于云厂商最快捷的方式是执行登录命令在交互界面里选择供应商并粘贴密钥opencode auth login密钥会被写入本机的认证配置文件不需要手工维护在项目里。对于本地 Ollama则连认证都不需要直接配置地址即可。生产环境里更推荐通过环境变量注入密钥例如export OPENAI_API_KEY你的密钥不要把密钥写进opencode.json尤其不要把包含密钥的配置文件提交到 Git 仓库。3. 配置“免费路由”把请求导向免费模型和本地模型3.1 OpenCode 的模型来源有哪几类从成本和部署方式上看可以把模型来源分成四类来源类型典型示例费用特点云厂商付费模型OpenAI、Anthropic、DeepSeek 等按 token 计费能力强延迟低需要密钥免费模型或免费额度供应商不定期开放的免费模型通常免费有限流、有隐私边界服务等级不稳定本地模型通过 Ollama 运行的 Qwen、Llama 等免费依赖本机 CPU/GPU 和内存完全离线自建 OpenAI 兼容端点团队内部服务取决于基础设施可控性强适合企业“免费路由”并不是某一个固定模型而是一套组合策略。日常问答和简单代码任务走免费模型或本地小模型高难度任务保留付费模型兜底。这样即使模型 API 涨价你的基础使用成本也不会被甩到天上。需要特别注意免费模型和免费额度通常伴随速率限制、数据使用条款和可用性风险。项目落地前要确认这些边界自己能否接受不要默认“免费等于无限制”。3.2 用 opencode.json 自定义模型路由OpenCode 的配置文件在不同操作系统上的常见路径是macOS~/Library/Application Support/opencode/opencode.jsonLinux~/.config/opencode/opencode.jsonWindows%APPDATA%\opencode\opencode.json如果文件不存在先创建目录和文件。下面是一个把默认模型指向本地 Ollama 的示例文件结构用于说明思路实际字段要以你安装版本的 schema 为准{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/ollama, options: { baseURL: http://127.0.0.1:11434 }, models: { qwen2.5-coder:7b: { name: Qwen2.5 Coder 7B } } } }, model: ollama/qwen2.5-coder:7b }解释几个关键字段provider定义一个新的供应商条目ollama是供应商标识后面写模型时会用ollama/模型名引用。npm字段指定这个供应商对应的模型访问 SDK 包OpenCode 会按需加载。options.baseURL是本地模型服务的地址Ollama 默认监听11434端口。models是你能使用的模型清单键名要和服务端真正存在的模型标签一致。model字段决定默认模型也就是你不手动切换时使用的路由目标。如果某个免费模型提供的是 OpenAI 兼容接口配置思路类似只是把baseURL换成对方提供的地址并通过环境变量注入认证信息。这里要警惕不要复制来历不明的配置模板尤其是要求你配置高风险密钥或关闭校验的模板。3.3 按任务切换模型而不是一个模型走到黑配置好默认模型后还应该养成“按任务切换”的习惯。在 OpenCode 的交互界面里通常可以使用斜杠命令打开模型列表并选择当前会话使用的模型。比如解释代码、取变量名、写 git 提交信息用免费模型或本地小模型。设计模块结构、梳理复杂数据流切换到付费强模型。处理隐私代码切到本地模型保证数据不出本机。这样做的原因是模型越大单次请求成本越高。大多数开发场景里真正需要顶级推理的请求只占一小部分。把简单请求分流到便宜模型上成本下降最明显且对日常体验影响很小。如果你需要为不同项目准备完全不同的模型策略可以考虑为每个项目放置独立的配置片段并用环境变量或启动参数指定配置目录。具体参数以opencode --help的输出为准不同版本支持程度不同。4. 让 OpenCode“越用越懂我”规则、技能与上下文4.1 用项目规则文件沉淀你的偏好“越用越懂我”不是玄学而是 OpenCode 会持续读取你定义的项目规则让每次会话都站在相同的基础上理解你的代码。最常用的载体是项目根目录下的AGENTS.md或规则文件。OpenCode 在开始任务时会读取这些文件把它们作为系统上下文的一部分。下面是一个项目规则文件示例内容可以根据团队规范自由扩展# 项目约定 - 后端代码位于 server/ 目录使用 Java 17 和 Spring Boot 3。 - 修改数据库字段时必须同时更新数据库迁移脚本。 - 新增接口前先补充 Controller 层测试。 - 不要修改自动生成的代码。 - 接口返回格式统一为 { code: 0, data: ..., message: ok }。规则文件的价值在于一致性。团队里所有成员使用同一个 OpenCode读到的也是同一套规则生成代码的风格就不会太散。个人使用时规则文件相当于把你的编码习惯写进了工具的长期记忆里比每次在提示词里重复一遍高效得多。4.2 把可复用操作封装成技能除了被动读取规则OpenCode 还支持把常见的操作封装成技能被触发时按固定流程执行。技能的常见形式是一组 Markdown 指令文件放在配置目录或项目目录的 skills 目录下。例如写一个“生成提交信息”的技能# 生成提交信息 当用户要求生成提交信息时 1. 先运行 git diff --stat 查看改动范围。 2. 运行 git diff 查看具体变更内容。 3. 按 Conventional Commits 格式生成提交信息。 4. 使用中文描述标题不超过 50 个字符。 5. 不要包含任何个人信息。技能目录的具体路径和触发方式在不同版本里可能不一样配置前先通过/help或官方文档确认。技能的本质是把“你经常反复描述的诉求”固化成文件减少每次开场白里重复交代背景的成本。当你发现自己的提示词里有一段话每次都要写时就意味着它应该被提炼成技能。4.3 会话记忆与上下文管理OpenCode 的交互会话是可以在终端里延续的。你可以回顾历史对话、继续上一次任务这会给人一种“它记住了我”的感觉。但要清楚会话记忆只在上下文窗口内有效过长的历史反而会占用 token 配额推高成本也会让模型抓不住重点。更稳健的做法是把重要结论写进项目文件。比如分析完某个模块后把结论追加到docs/decisions.md确定了新的编码约定就更新AGENTS.md。这样跨会话的“懂你”依赖的是文件系统里的持久信息而不是一次聊天记录。也就是说真正让 OpenCode 越用越懂你的是规则文件、技能配置和项目文档组成的体系而不是某个模型的记忆能力。5. 运行验证确认请求真的走了你想要的路线5.1 启动会话、查看模型列表、切换模型配置完成后的第一步是启动会话验证opencode进入交互界面后可以按/打开命令输入框输入models查看当前可用的模型列表。列表里应该能看到你在配置文件中定义的本地模型或免费模型也能看到默认模型标记。选择模型只在当前会话生效适合临时切换。如果你只想执行一次性任务而不进入交互界面可以使用run子命令opencode run 解释一下这个项目的目录结构这个模式适合脚本化调用比如在 CI 流程里做代码审查或生成文档草稿。注意run模式同样会消耗模型配额批量调用前先想清楚成本。5.2 从模型回复和用量判断路由是否生效验证“路由是否生效”最简单的方法是看回复来自哪个模型。你可以在提问时直接要求模型自我介绍也可以观察回复的写作风格、速度以及是否消耗了本地资源。本地模型的特征比较明显离线也能工作、响应速度受机器负载影响、模型通常偏小。更可靠的验证方式是查看供应商后台的调用记录。付费模型供应商通常会提供用量面板每一次请求对应哪个模型、消耗多少 token 都一目了然。如果免费路由配置成功付费模型的调用量应该明显下降而免费或本地模型的调用量上升。这个数据是评估省钱效果的最硬指标。如果版本支持日志输出也可以通过启动参数打开日志观察请求实际命中的供应商标识和模型标识。以你安装版本opencode --help列出的参数为准不同版本差异较大。5.3 “供应商不存在、无法接管 live 配置”这类报错的排查有人会把 OpenCode 和其他 AI 编程工具、第三方配置切换工具一起使用这时容易出现两类报错报错现象常见原因处理思路切换路由状态失败提示当前供应商不存在配置里的供应商标识拼写错误或对应 SDK 没有安装检查opencode.json中provider的键名再通过/models列表核对无法接管 live 配置多个工具写入同一个配置文件或旧进程缓存了配置关闭正在运行的会话重新加载配置确认配置文件归属哪个工具模型不存在或模型标识无效模型名格式错误或服务端没有下载对应模型在 Ollama 里执行ollama list核对模型标签后修改配置排查这类问题有一个固定顺序先看错误信息里的实体名称再对照配置文件里实际的键名最后看列表命令返回的真实模型标识。绝大多数“供应商不存在”都是字符串不一致造成的而不是工具坏了。6. 常见问题排查安装、配置、免费模型6.1 配置修改后不生效现象明明修改了opencode.json重新提问后模型还是老的或者行为没变化。原因通常是三类改错了路径配置文件没有放在 OpenCode 实际读取的目录。修改后没有重启会话运行中的进程还持有旧配置。配置字段版本不对当前版本忽略了你写的字段。检查方式先确认配置文件路径再关掉 OpenCode 重新启动最后用/models列表确认是否出现新配置的模型。如果你不确定字段是否正确可以把$schema字段保留编辑器通常能基于 schema 提供自动补全和校验。6.2 免费模型限流和超时现象请求返回 429、超时或响应明显变慢。免费模型和免费额度通常有速率限制短时间高频请求很容易触发限流。处理方式有几种降低并发和请求频率批量任务改成串行。把简单任务切到本地模型减轻免费服务端的压力。设置更短的上下文长度减少单次请求体积。注意不要把免费模型的限流理解成“配置错误”这是服务提供方的正常保护策略。持续高频调用免费接口还可能影响账号在服务方的信誉。6.3 本地模型加载慢、显存不足现象启动后模型加载几分钟或者运行时报内存不足、显存不足。原因模型文件体积超过机器可用内存或者量化精度太高。处理方式ollama list ollama ps先确认当前加载了哪些模型再选择更小的模型或更低精度的量化版本。关闭无关应用释放内存也可以减小上下文长度。对于老机器7B 模型的低量化版本往往比 13B 模型体验好得多因为响应速度快才能形成可用工作流。6.4 多个工具共用配置文件导致互相覆盖如果你同时使用多个 AI 编程工具又安装了第三方切换配置工具它们可能会读写同一个配置文件。现象是你刚配好的免费路由下一次启动时又被切换回原来的付费模型。处理思路为每个工具维护独立的配置不要共用同一个 JSON 文件。把密钥放到环境变量里避免切换工具时把认证信息一起改掉。修改配置前先备份旧文件cp opencode.json opencode.json.bak。这类问题的核心是“配置归属权不清晰”。谁拥有这个文件谁修改这个文件必须明确清楚否则每次路由调整都可能被其他工具悄悄覆盖。7. 从“免费路由”到稳定日常最佳实践与扩展方向7.1 迁移到免费路由前的检查清单在把整个工作流切到免费路由之前建议先按下面的清单过一遍[ ] 确认 OpenCode 版本阅读对应版本的配置说明。[ ] 备份现有opencode.json和认证配置文件。[ ] 确认本地模型服务能访问例如执行curl http://127.0.0.1:11434/api/tags。[ ] 确认免费模型的速率限制、隐私边界和可用性说明。[ ] 确认付费模型密钥仍通过环境变量或登录命令保留用于兜底。[ ] 先跑三次典型任务对比免费模型和付费模型的输出质量。[ ] 查看供应商用量面板确认付费调用量确实下降。这份清单的价值在于防止“切一半回不去”。免费路由不是删除付费模型而是把付费模型降级为兜底方案切换过程应该可回滚。7.2 学习环境与生产环境的使用差异同一套 OpenCode 配置在个人电脑和团队生产环境里的使用方式要有区别维度个人学习环境团队生产环境模型选择免费模型和本地模型为主按任务分级核心任务用付费强模型数据边界私密项目用本地模型遵守团队数据合规要求配置管理本地文件即可配置入库通过环境变量注入密钥日志与监控偶尔查看需要记录 token 用量和调用成功率回滚方案备份配置文件配置版本化支持快速回滚生产环境还要考虑权限控制不是所有人都应该在同一个配置文件里写入生产密钥密钥应该通过密钥管理服务或 CI/CD 变量注入而不是直接在开发机里共享。7.3 下一步扩展方向完成免费路由配置后可以继续向几个方向扩展把项目规则文件从个人习惯升级为团队规范让整个团队生成的代码风格一致。把常用技能做成公共仓库例如代码审查技能、提交信息技能、接口文档生成技能。接入更专业的本地模型运行时根据本机显存选择合适的模型量化版本。关注 OpenCode 的编辑器扩展和桌面版形态把终端里的规则和技能复用到图形界面里。在 CI 流水线里用opencode run执行固定的代码检查任务但要注意批量调用的成本控制。最后想强调一个判断OpenCode 这类工具的开销高低不取决于工具本身而取决于模型路由策略是否合理。把简单任务分流到免费模型和本地模型把复杂任务留给付费强模型再把个人偏好沉淀到规则文件和技能里这套组合才是“越用越懂我且费用可控”的答案。下一步最值得做的不是继续对比更多工具而是先给手头项目写一份合格的AGENTS.md然后打开 OpenCode 跑通一条真实任务链路。