老早就想聊聊这个话题了。之前一直在命令行里折腾各种 AI 编码代理工具,后来换到 Windows 环境,总感觉配置这条路比预想中坎坷,尤其是想把 Opencode 接到自定义模型上,官方文档写得倒是简洁,但实际操作里暗坑不少。这篇文章就把我在 Windows 下从零配置 Opencode 自定义模型的完整过程、踩过的坑、以及最终跑通的参数组合整理出来,给同样在这条路上折腾的朋友做个参考。
先说清楚一个概念:Opencode 是什么。简单讲,它是一个运行在终端里的 AI 编码代理,你可以在终端里直接跟某个大模型对话,让它帮你写代码、改 bug、做代码审查,甚至自动执行终端命令来完成一个相对完整的开发任务。它本身不自带模型能力,而是通过配置对接各种模型服务——OpenAI 系的、Anthropic 系的、本地 Ollama 部署的,以及其他兼容 OpenAI 协议的服务。所以“自定义模型”这件事,在 Opencode 里本质上就是配置 provider 和 model 两个层次的问题。
我为什么非要折腾自定义模型,而不是直接用某个商业模型的官方 CLI?原因很简单:数据隐私和成本。在某些公司环境里,代码片段不能随便外发到第三方平台,这时候本地模型就成了仅有的选择;另外,团队内部往往有一套已经接入好的模型网关或私有化部署服务,统一走自定义模型配置能复用现有的 key 和计费体系。从实际经验看,Opencode 的自定义模型配置能力相当灵活,只要你理解了它的配置模型,几乎任何兼容 OpenAI 或 Anthropic 协议的端点都能接上。
1. Opencode 的架构与自定义模型的核心逻辑
1.1 先搞清楚 Provider、Model、Profile 三者的关系
Opencode 的配置思路跟很多 AI 应用不太一样。它不是简单填一个 API Key 就行,而是把“谁能提供模型服务”和“具体用哪个模型”分开管理。前者叫 Provider(模型提供方),后者叫 Model(模型实例)。
举个例子,你配置了一个 Provider 叫 mycompany,地址指向你们公司内部的模型网关,然后你在这个 Provider 下面注册两个 Model,一个叫 gpt-4-family(映射到公司网关的某个模型别名),一个叫 code-model-small(映射到另一个轻量模型)。实际使用的时候,你可以通过启动参数 --model mycompany/code-model-small 直接选中某个模型,也可以在交互式会话里用 /model 命令临时切换。如果不指定,Opencode 会使用顶部配置里的默认模型。
这就带来一个好处:你能在不同模型之间切换,还不用修改 Provider 配置。对于我这种经常要在“大而全”和“快而省”的模型之间切换的开发者,这种设计非常顺手。还有个容易忽略的概念是 Profile(配置档)。Opencode 允许多个 Profile,每个 Profile 是一整套独立的配置,包括自己的 Provider、Model、系统提示词、权限设置。比如你日常开发用一个 Profile,写文档用另一个 Profile,各自的模型和提示词互不干扰。这个机制在后面配置自定义模型时非常有用。
1.2 Windows 环境与 Linux/macOS 的差异点
很多人以为 Opencode 在 Windows 下的配置就是装完直接 opencode 回车,但实际遇到的第一个坑就是运行环境。Opencode 官方推荐在 Linux 和 macOS 上运行,Windows 属于“能用但没那么顺”的状态。它在 Windows 下需要依赖一些类 Unix 工具,所以你先得装一套 Git for Windows(提供 bash.exe、sh.exe)和 Windows Terminal,否则很多工具链根本跑不起来。
另一个差异是路径分隔符。Windows 下你写配置里的模型路径时,经常要处理反斜杠转义问题。配置文件里 JSON 的路径如果写 C:\Users\xxx,不转义的话 JSON 解析直接报错。我后来统一用正向斜杠 C:/Users/xxx 或者双反斜杠,问题就消失了。
还有一个很隐蔽的坑:Windows 的控制台编码。如果模型返回的中文内容在终端里显示乱码,十有八九是代码页问题。在 PowerShell 里执行 chcp 65001 切到 UTF-8 可以解决大部分情况,或者在 Windows Terminal 的设置里把默认编码改成 UTF-8。这些前置问题不解决,你后面无论怎么配置模型都会觉得哪哪都不对劲。
1.3 配置文件的加载顺序与优先级
Opencode 配置文件的加载顺序属于那种“不看文档就很容易怀疑人生”的部分。整个配置体系从全局到局部有明确的优先级,层级越往下,优先级越高。我先梳理一下:
- 全局配置:位于
%USERPROFILE%\.config\opencode\或通过OPENCODE_CONFIG环境变量指定的目录 - 项目级配置:位于当前项目根目录的
.opencode/目录下 - 命令行运行目录下的
.config/opencode目录
当存在多个配置文件时,更深层级的配置会覆盖更全局的配置。这也就解释了为什么你在全局配好的 provider,到了某个特定项目里突然不生效了——极有可能是那个项目里有自己的 .opencode 配置,把全局配置覆盖了。
我在某公司做顾问时,经常发现 A 同事在全局配好的模型,拿给 B 同事用,B 在自己项目里却一直启动不了。排查到最后,就是项目里一个陈旧的 .opencode/config.json 在作祟。如果你想强制忽略项目级配置,可以用 --no-project-config 启动参数,这个参数在排查问题的时候非常管用。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Windows 环境准备:基础依赖与可选的本地模型运行时
2.1 Node.js 版本与安装方式
Opencode 本质上是 Node.js 编写的 CLI 工具,所以 Node.js 是硬依赖。这里要特别注意版本问题:如果你 Node.js 版本偏低,装是能装上,但运行后各种 API 报错,光看报错信息根本想不到是运行时版本太老。我建议 Node.js 20 或以上,这是亲测最稳的。
安装方式推荐用官方安装包或者在 PowerShell 里用 winget install OpenJS.NodeJS.LTS,二选一都行。装
