先说一个比较现实的问题最近很多 AI 编程工具都开始调整收费策略OpenCode 也不例外。如果你之前一直习惯白嫖官方渠道的高频模型确实会感受到“额度不够用”“免费的时代结束了”的落差。但我的建议是先别急着交钱因为 OpenCode 本身是一个高度开放的终端 AI 编程助手它的供应商、模型、路由全部可以自己定义。换句话说官方怎么定价是一回事你本地怎么组路是另一回事。这篇文章我会围绕 OpenCode 的安装、基础配置、免费模型接入、供应商路由切换这些内容写一套完整的实操笔记重点会放在“免费路由”上本地模型路由怎么配多供应商怎么切ccswitch 这类工具在什么场景下才需要。内容更适合已经用过类似 Cursor、Codex、Continue 等工具、现在想迁移到 OpenCode 的开发者纯新手也可以照着一步步来只是需要先熟悉终端基本操作。1. OpenCode 是什么为什么大家都在聊“免费路由”1.1 OpenCode 的核心定位OpenCode 是一个运行在终端里的 AI 编程代理AI coding agent它不像 IDE 插件那样只是给代码补全建议而是可以在你给出的任务描述下自己读取项目文件、分析报错、生成 diff、执行命令把一次“帮我实现某个功能”的指令变成一个完整的编码工作流。它的工作方式比较像 Codex CLI 和 Claude Code但 OpenCode 的差异点在于开源配置完全在本地数据默认不出本机不绑定某个厂商支持多种模型供应商没有把路由逻辑写死你可以自己决定不同场景走哪个模型终端优先轻量、启动快适合习惯键盘操作的开发者。从这个角度看OpenCode 本质上是一个“客户端”模型只是它背后的一个可替换零件。这也就引出了大家都关心的免费路由问题既然模型可以换那完全没有必要只盯着官方默认渠道本地模型、免费额度、自建代理都可以纳入路由池。1.2 “涨价”背景下的路由思路先说清楚一个事实不同时间点、不同地区、不同套餐下AI 工具的价格策略变化很快我今天写具体价格明天可能就失效。所以我不打算给你抄一堆数字建议你以官方订阅页为准。真正需要关注的是当一个工具的默认渠道不再便宜时你的替代方案是什么。OpenCode 的设计恰好适合做这件事。它把“模型供应商”抽象成了独立的配置项你可以维护多个供应商配置然后按需切换。常见的免费或低成本路线有使用本地模型比如通过 Ollama 跑 Qwen、Llama 3 等开源模型完全不依赖网络额度使用各云平台提供的免费试用额度注册后拿额度走标准 API使用开源模型的托管 API部分服务对低频用户比较友好自己有多余硬件的可以直接在局域网部署一个模型服务OpenCode 通过自定义 provider 接入。这就是我标题里说的“免费路由”不把鸡蛋放在一个篮子里通过配置路由让 OpenCode 在本地模型、免费额度、付费 API 之间自由切换。用得好你甚至可以做到日常开发完全不花钱。1.3 阅读本文你能得到什么读完这篇文章你可以做到在自己的电脑上安装 OpenCode从零跑通第一次对话理解 OpenCode 中 Provider、Model、API Key、Base URL 这几个关键概念把 Ollama 本地模型接入 OpenCode实现断网也能用的编码助手配置多供应商路由在不同模型之间切换不再被单一服务商绑定排查“切换路由状态失败”“当前供应商不存在”“无法识别 opencode 命令”等高频问题。2. 环境准备与核心概念2.1 本地环境要求OpenCode 是终端应用跨平台支持不错但要求你的机器能跑 Node.js 生态。以我常用的环境为例操作系统Windows 10/11、Ubuntu 20.04 或 macOS终端工具Windows 推荐 Windows TerminalLinux/macOS 直接使用自带终端即可Node.js建议使用 18 及以上版本部分新功能可能要求更高版本包管理器npm、pnpm、bun 任选一种。这里特别说明版本情况变化比较快建议安装前先执行node -v确认一下本机 Node 环境。如果你的 Node 版本太老先升级 Node再装 OpenCode否则可能出现运行时错误。2.2 路由在 AI 工具里到底指什么网络里的路由大家听得比较多什么静态路由、策略路由、BGP、OSPF核心都是“决定数据从哪条路径走”。OpenCode 里的路由概念其实和它很相似只不过路径不是物理链路而是“请求应该发往哪个模型供应商”。举个例子用户输入 | v OpenCode 路由判断 | ├── 简单补全 - 本地 Ollama 模型延迟低不花钱 ├── 长任务分析 - 云端免费额度 API速度一般但能处理复杂逻辑 └── 敏感代码审查 - 自建模型服务完全不出内网这种路由策略的好处很明显成本、速度、隐私可以在同一套工作流里共存。2.3 Provider、Model、API Key、Base URL 四要素在没有图形界面配置的终端工具里理解这几个概念特别重要因为它们就是路由的构成单元。概念含义类比Provider模型供应商比如 OpenAI、Anthropic、Ollama、其他兼容 API运营商Model具体模型名比如 gpt-4o、qwen2.5、llama3套餐API Key访问供应商 API 的凭证SIM 卡Base URLAPI 服务地址默认指向官方也可以指向自建服务访问网关OpenCode 的配置本质就是维护一组这样的映射关系。你告诉它“这家供应商叫什么、API 地址在哪、Key 是多少、有哪些模型可用”它就能把请求路由过去。3. OpenCode 安装与基础配置3.1 使用 npm 全局安装如果你本机已经有 Node.js最简单的方式是通过 npm 安装npm install -g opencode-ai安装完成后在终端里执行opencode --version如果正常输出版本号说明安装成功。之所以建议-g是因为 OpenCode 是一个全局命令行工具只有全局安装后你才能在任意目录直接调用它。3.2 在 Linux 环境下安装Ubuntu 20.04 上安装 OpenCode 的思路和 Windows 类似先准备 Node.js 环境sudo apt update sudo apt install -y nodejs npm sudo npm install -g opencode-ai如果你的 npm 因为权限问题报错可以使用 nvm 管理 Node 版本这种方式更干净也方便以后切换 Node 版本。3.3 通过其他方式安装有些开发者习惯使用 bun 或 pnpm命令如下bun add -g opencode-ai或者pnpm add -g opencode-ai无论使用哪种方式安装完成后都要先执行一次版本校验。如果遇到opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名这种报错常见原因是全局 bin 目录没有加入 PATH。Windows 下可以检查 npm 全局安装路径把对应目录加到系统环境变量中Linux 下可以检查/usr/local/bin或 nvm 的 bin 路径。3.4 初始化配置目录OpenCode 的配置目录和大多数终端工具一样位于用户目录下的隐藏文件夹中。以 Linux/macOS 为例通常是~/.config/opencode/Windows 下则在用户目录的.config或对应 AppData 路径中。你可以先执行opencode打开交互界面程序会自动创建默认配置。我们需要关注的核心文件是opencode.json多数供应商和模型配置都会写在这个文件里。第一次运行时OpenCode 可能会提示你选择默认 Provider 并填写 API Key。如果不确定怎么填可以直接跳过后续我们再手动修改配置文件。4. 用 OpenCode 跑通第一次对话4.1 选择 Provider 的思路在没有配置任何供应商的情况下OpenCode 默认是没法直接对话的因为它需要一个可用的 Provider。对于刚开始使用的人我建议先选择一个你已经有 API Key 的云厂商哪怕是付费的也行先跑通流程再逐步替换成免费路由。如果你一个云平台的 Key 都没有可以直接跳到第 5 节先把本地模型接入这样一分钱不花也能完成首轮验证。4.2 修改 opencode.json假设你想接入一个兼容 OpenAI 接口的服务配置文件可以这样写。下面的内容是核心思路不同版本的字段名可能略有差异需要以你实际安装版本的文档为准{ $schema: https://opencode.ai/config.json, provider: { my-free-provider: { npm: ai-sdk/openai-compatible, name: My Free Provider, options: { baseURL: https://api.example.com/v1, apiKey: {env:MY_FREE_API_KEY} }, models: { free-model: { name: Free Model } } } } }几个关键点的解释npm字段指定了这个 Provider 使用的 AI SDK 适配包ai-sdk/openai-compatible通常用于兼容 OpenAI 格式的服务baseURL是 API 地址不同服务差异很大apiKey建议不要明文写在配置文件里通过环境变量引用会更安全models下面列出该 Provider 可用的模型 ID。配置完成后在终端执行opencode进入交互界面按快捷键切换 Provider选择刚才定义的my-free-provider再选择具体模型即可。4.3 环境变量管理 API Key我强烈建议不要把 API Key 写死在配置文件里。在 Linux/macOS 下可以临时导出export MY_FREE_API_KEYsk-xxxxxxxxWindows PowerShell 下使用$env:MY_FREE_API_KEYsk-xxxxxxxx然后在同一个终端窗口启动opencode。这样做的好处是不管配置文件会不会被分享、提交到 Git你的密钥都不至于泄露。4.4 验证流程进入 OpenCode 后输入一句最简单的指令你好请介绍一下 OpenCode 的功能。如果配置正确模型会返回一段介绍文本。这一步通过后再尝试让它读取当前目录下的文件列表确认它已经具备基本的文件系统访问能力。5. 本地免费模型路由Ollama OpenCode5.1 为什么要用本地模型本地模型最大的优势不是“免费”而是不受网络和额度影响。你在调试代码的过程中经常会遇到上下文长度大、请求频率高的场景云 API 很容易触发限流而本地模型是纯算力消耗对你来说没有边际成本。当然本地模型也有比较明显的短板效果不如顶级云端模型、占用显存和内存、需要自己维护模型版本。所以比较合理的策略不是“本地模型替代一切”而是把本地模型作为默认补全和简单任务的路由把复杂推理任务留给云端模型。5.2 安装 OllamaOllama 是一个专门用来在本地运行开源大模型的工具支持 Windows、Linux、macOS。安装方式很直接curl -fsSL https://ollama.com/install.sh | shWindows 用户可以到官网下载安装包。安装完成后在终端执行ollama --version确认安装成功。5.3 拉取模型以 Qwen2.5 为例拉取并运行ollama pull qwen2.5 ollama run qwen2.5运行成功后你会进入 Ollama 自己的对话界面说明模型已经正常加载。如果要退出输入/bye。先保证这一步没问题再去做 OpenCode 的对接。5.4 在 OpenCode 中配置 OllamaOllama 默认会启动一个本地 HTTP 服务地址通常是http://localhost:11434。因为 Ollama 提供了 OpenAI 兼容的接口我们可以直接把它当成一个 Provider 配置进 OpenCode。在opencode.json中新增如下配置{ provider: { ollama: { npm: ai-sdk/openai-compatible, name: Ollama Local, options: { baseURL: http://localhost:11434/v1 }, models: { qwen2.5: { name: Qwen 2.5 } } } } }这里不需要配置apiKey因为 Ollama 在本地默认不校验密钥但字段也可以保留为空字符串。配置完成后重进 OpenCode切换到ollama这个 Provider再选择qwen2.5就可以在完全离线的状态下使用 AI 编码助手了。如果你拉取了其他模型在models下继续添加即可比如models: { qwen2.5: { name: Qwen 2.5 }, llama3.1: { name: Llama 3.1 } }5.5 本地路由的适用场景我一般在下面这些场景会优先走 Ollama 路由简单的代码补全、函数生成不需要太多推理能力处理一些敏感代码不希望离开本地环境云端 API 限流或者网络不稳定的时候作为降级方案想快速验证某个开源模型在项目中的表现不想通过网页端切换。如果是大型项目的架构设计、复杂 Bug 定位、长文档分析我还是更倾向交给更强力的云端模型处理。这就是“路由”的意义不是选最好的一个而是让合适的任务走合适的渠道。6. 多供应商路由与 ccswitch 的玩法6.1 什么时候需要切换路由当你同时维护了 Cloud 模型、本地模型、免费额度模型之后就会面临一个很实际的问题每次手动改配置太麻烦了。OpenCode 提供了在交互界面里切换 Provider 的能力但如果你有多个项目、多个工作目录每次都切来切去会消耗不少精力。更常见的场景是某种供应商在某个时间段不可用或者限流比如切换时提示“当前供应商不存在”或者“无法接管 live 配置”这就需要你在多个配置之间快速切换而不影响正在进行的任务。6.2 ccswitch 是做什么的ccswitch 是社区里常见的一个配置切换工具它做的事情可以简单理解成“管理多份供应商配置一键切换”。有些版本叫 ccswitch有些版本是独立脚本不同作者的实现方式也不太一样。从使用思路上看这类工具的逻辑一般是你预先定义好多个配置比如cloud-paid、ollama-local、free-quota使用命令把指定配置写入 OpenCode 的配置目录重启或重载后OpenCode 就使用新的供应商配置。网络上关于 ccswitch 的配置方法差异很大而且它更多是社区化工具我不建议你照抄某条命令。正确做法是阅读你安装版本自带的 README或者先备份opencode.json再执行切换命令。比如ccswitch switch ollama-local ccswitch switch cloud-paid具体命令以你下载的工具说明为准但思路都是类似的备份、切换、验证。6.3 “需要路由”怎么解决很多刚接触 OpenCode 的人会问ccswitch 到底什么时候需要开路由其实关键是看你的使用场景如果你只有一个云厂商 API那你不需要任何路由工具直接配一个 Provider 就行如果你有本地模型和一个云 API手动切换也能忍受基本也不需要如果你有多个项目、多个团队成员、多个供应商且经常在付费和免费方案之间切换那路由切换工具就非常有用。另外路由配置要遵循最小权限原则不要把无关供应商的 Key 暴露给不相关的项目。比如某个项目只允许访问本地 Ollama那么团队配置文件里就不要把云端付费 Key 写进去。6.4 路由策略的工程建议以下是我在项目里实际使用的路由策略供你参考任务类型路由目标原因行内补全、函数生成本地 Ollama 小模型延迟低免费修改多个文件、跨文件重构云端付费强模型效果稳定读取日志、排查报错免费额度 API频率不高够用分析敏感业务代码本地模型或内网自建 API数据不出内网路由策略不是一成不变的。项目的不同阶段、云平台额度的剩余情况、本地硬件负载都会影响最优路由。建议你在配置文件里留好注释方便以后调整。7. 常见问题与排查思路7.1 高频问题排查表问题现象常见原因解决思路无法将“opencode”项识别为 cmdlet全局 bin 目录未加入 PATH重新安装检查 npm 全局路径并加入 PATH启动后无法选择模型Provider 配置缺失或模型名写错检查 opencode.json 中 models 字段切换路由失败提示当前供应商不存在配置文件里的 provider 名称与切换命令不一致确认 provider 标识符是否完全匹配提示无法接管 live 配置正在使用的配置被外部修改版本不一致备份当前配置重新加载或重启 OpenCodeAPI Key 无效环境变量未生效或 Key 过期在当前终端重新 export并确认 Key 的状态本地模型可以跑但无法连接 OpenCodeOllama 服务未启动或端口不对执行 ollama serve确认 11434 端口可访问模型返回内容为空模型被截断或路由配置了不存在的模型查看终端日志切换到小模型测试7.2 OpenCode 安装后无法识别这个报错在 Windows 上尤其常见。如果你的 npm 是随 Node.js 安装的全局包通常会装到C:\Users\你的用户名\AppData\Roaming\npm。你需要把这个路径加到系统 PATH 中然后重新打开终端。也可以先用npm config get prefix查看全局路径再把输出路径加到 PATH。之后执行opencode --version验证。7.3 切换路由失败如果你切换路由时提示“当前供应商不存在”不要急着重装工具先打开opencode.json确认provider下的标识符是否和切换命令里的名称完全一致。注意大小写、空格、连字符这些都会导致匹配失败。如果提示“无法接管 live 配置”通常是因为 OpenCode 正在运行时配置文件已经被外部修改进程持有的配置和磁盘上的配置不一致。解决方法是备份当前正在使用的配置退出 OpenCode重新启动加载新的配置。7.4 Linux 下 OpenCode 安装后的权限问题Ubuntu 上使用 npm 全局安装时有时会遇到 EACCES 权限报错。最简单的解决思路是使用 nvm 安装 Node而不是直接使用系统级 npm。nvm 会把 Node 和全局包安装在用户目录下不需要 sudo也不会遇到权限问题。7.5 Ollama 模型拉取慢这主要取决于你的网络环境和模型大小。可以换一个更小的模型试试比如qwen2.5:1.5b参数更少下载更快跑起来占用的显存也更低。等流程完全跑通之后再决定要不要拉取更大的模型。8. 最佳实践与避坑建议8.1 配置文件版本管理opencode.json是纯文本配置文件适合纳入 Git 仓库方便团队成员共享路由策略。但有个前提条件不要把 API Key 写入这个文件。建议在项目里维护一个.env.example只写变量名不放真实值。真实的环境变量在本地单独配置。8.2 保留一份可回滚的配置在尝试新的路由策略或切换工具之前先把当前可用的配置备份一份cp ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak这样不管怎么折腾随时都能回到上一份稳定配置。任何涉及配置变更的操作都应该遵循“先备份再变更后验证”的顺序。8.3 合理命名 Provider 标识符Provider 的标识符会出现在切换命令和日志里建议使用简短、清晰、不含空格的名称。比如ollama-local cloud-paid cloud-free-quota不要在配置里用“最后”“最终”“新配置 2”这种混乱的命名时间一长你自己都会忘记每个配置是干什么的。8.4 遵守模型供应商的使用规则免费额度有它的使用边界不要为了跑测试一次性发大量并发请求否则很容易被服务商限制。如果你在团队里共享某个 API 账号收到限流或封禁提示后先检查是不是有人把 Key 泄漏到了公开仓库。8.5 谨慎处理生产环境变更如果你把 OpenCode 的配置用到了公司内部项目或者是团队统一路由任何修改都要走正常的变更流程。不要趁同事不注意直接改共享配置否则会导致所有人的路由突然失效。生产环境里的配置变更应该走测试、评审、发布而不是直接改线上文件。8.6 不要过度追求“全部免费”免费路由的核心价值是降低成本和增加灵活性但不要为了省钱而牺牲效率。如果你的日常工作大量依赖 AI 编码助手付费强模型带来的效率提升往往能覆盖成本。我个人的建议是本地免费模型适合通用补全和隐私敏感场景复杂任务该用付费模型还是用付费模型两者互补才是最优解。9. 总结与后续建议这篇文章从 OpenCode 的定位讲起梳理了安装、Provider 配置、Ollama 本地模型接入、多供应商路由切换和 ccswitch 的使用思路也给出了常见报错的排查方法。核心想表达一个观点OpenCode 这类终端 AI 工具最强的不是它默认绑定了哪家模型而是它把路由的选择权交还给了用户。官方涨价不可怕可怕的是你不知道自己还有其他路径可选。下一步你可以按这个顺序继续深入先装好 Ollama跑通本地模型感受一下无网络依赖的编码体验再找一个免费或低价的云 API配置成第二路由然后尝试用路由切换工具在两条路由之间来回切换最后根据自己的项目场景完善 Provider 的命名和配置管理。如果你在配置过程中遇到其他报错建议先把终端里的完整错误信息复制下来再打开配置文件逐行检查。大多数问题都集中在 API Key 没生效、Provider 名称对不上、模型名写错这几个地方。只要备份做得好基本不会把环境搞坏。希望这篇文章能帮你少走一些弯路。如果你觉得有用可以收藏备用后续有新的 OpenCode 路由配置经验我也会继续更新。