Windows下Opencode自定义模型配置实战：从provider到Ollama接入全指南

最近需要在Windows机器上给Opencode配置自定义模型，折腾完一圈发现网上资料比较零散，很多还停留在直接选个内置模型名就完事的阶段，一旦要接公司内部API或者本地Ollama就不知道怎么填字段了。这篇把我在Windows下的完整配置过程、每个配置项的含义、以及实际踩过的坑一次性整理出来，属于面向动手党的实操记录，新手可以直接照着敲，老手也可以翻一翻排查思路。

Opencode这类终端AI编程助手，默认带了不少主流模型服务商，但真正落地到团队或个人工作流时，往往要接的是自己的模型端点。我遇到的需求无非三类：一是公司内部部署了API网关，提供OpenAI兼容格式的接口；二是本机跑着Ollama，想用开源模型做日常任务；三是用了某个第三方聚合平台，但不希望每次都在界面里手动切来切去。这三类场景本质上都是同一个动作——在Opencode配置里声明一个自定义provider，再挂上对应的模型ID。下面从配置机制开始讲。

1. 先把Opencode的模型接入逻辑搞明白

1.1 provider、model和npm包三者是什么关系

Opencode接入自定义模型，核心就三个概念：provider（服务提供方）、model（模型标识）、npm包（协议适配器）。很多人一开始就把provider理解成OpenAI、Anthropic这类具体厂商，其实不太准确。在Opencode的配置文件里，provider代表的是一类“可以通过某种协议访问到的API端点”。

打个比方，你公司内部搭了一个网关，地址是 http://内网地址:8080/v1，返回的接口格式和OpenAI完全一致。那你可以把这个网关声明成一个叫 internal 的provider，然后在它下面挂上你想用的模型名。模型归属于provider，同一个provider下可以挂多个模型，比如网关同时转发7B和70B两个模型，就都在models字段里列出来。

npm包是被大部分人忽略但非常关键的一个字段。Opencode本身并不内置所有API协议的实现，它依赖某个AI SDK生态来处理模型请求，每个provider对应一个npm包。OpenAI官方接口就用 @ai-sdk/openai，只要接口格式是OpenAI兼容的第三方服务或者内部网关，用 @ai-sdk/openai-compatible，Anthropic格式的接口用 @ai-sdk/anthropic。配置自定义模型的时候，本质上就是选择一个合适的适配包，再把baseURL和API Key告诉它。

1.2 全局配置和项目配置的优先级关系

Opencode的配置有两种位置：全局配置和项目配置。全局配置在Windows下位于 %USERPROFILE%\.config\opencode\opencode.json，所有项目启动时都会读取；项目配置就在项目根目录下的 opencode.json，只对当前项目生效，优先级比全局高。

这个设计很实用。我平时会把公司内部API、Ollama这类“基础设施”写在全局配置里，不管进哪个项目都能用；个人项目里需要换模型时，再在项目配置里覆盖默认模型选择。优先级高的项目配置会合并到全局配置之上，字段互相补充，不是整文件替换。

有个容易踩的坑：如果你在项目配置里只写了 model 字段去指定某个provider下的模型，但该provider只定义在另一个项目的配置中，Opencode启动后找不到这个provider，模型列表就会是空的。所以我的建议是provider定义放全局，项目级只做模型选择或参数覆盖，逻辑清晰也好排查。

配置文件的格式支持JSON也支持TOML。我自己用下来更推荐JSON，因为第一行加上 $schema 字段后，编辑器能自动补全和校验配置项，写错字段当场就能发现。

2. Windows环境准备与基础安装

2.1 确认Node.js版本

Opencode是Node.js写的命令行工具，Windows下先确认Node环境是第一步。打开PowerShell执行 node -v，如果提示找不到命令，说明没装或者没加环境变量。建议使用LTS版本，实际体验中Node 18以下跑Opencode会有兼容性问题，装Node 20或更高版本要省心很多。

版本管理工具在Windows下可以用nvm-windows，它和macOS上的nvm用法类似，支持随时切换Node版本。如果你电脑里同时有多个Node项目，强烈建议用这种方式，别直接拿官方安装包覆盖升级，容易把全局依赖搞乱。

装完Node之后顺手确认一下npm版本：npm -v。如果npm源在国内下载opencode特别慢，可以临时把registry切换成国内镜像源，装完再切回来，这个看个人网络环境，不强制。

2.2 安装Opencode本体

Opencode的安装命令很简单：

bash复制npm install -g opencode-ai

全局安装后，终端里执行 opencode 就能启动交互界面。Windows下如果出现“opencode不是内部或外部命令”的报错，多半是npm全局目录没有加到PATH。可以先执行 npm config get prefix 拿到全局安装路径，再把该路径下的目录追加到系统PATH环境变量里。

安装完之后可以先跑一下 opencode --version，确认版本正常。这一步值得多花十秒钟，因为后面排查配置问题时要分清楚到底是工具版本太旧导致的字段不兼容，还是你自己写错了配置。

2.3 配置文件目录和编码检查

Windows下Opencode的全局配置目录是 %USERPROFILE%\.config\opencode\，如果不存在就手动创建。打开资源管理器，在地址栏输入 %USERPROFILE%\.config\opencode，按回车就能直接进入。

这个目录下默认可能还没有 opencode.json，第一次配置时需要新建。新建文件时最容易踩的坑是编码问题：Windows记事本保存文件时可能带BOM头，而JSON解析器对BOM很敏感，轻则报错重则静默失败。我建议配置编辑器用VS Code，右下角确认编码显示为UTF-8，不要选“UTF-8 with BOM”。

另外JSON文件不支持注释，网上有些帖子会给出带 // 注释的示例，复制到配置文件里会直接解析失败。所有示例都要保证是纯JSON。

3. Windows下自定义模型配置实战

3.1 最小可用配置：对接OpenAI兼容API

先给一个最小可用的完整示例。假设你有一个第三方API或内部网关，接口是OpenAI兼容格式，请求地址是 https://api.example.com/v1，API Key存在环境变量 MY_API_KEY 里：

json复制{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "my-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Gateway",
      "options": {
        "baseURL": "https://api.example.com/v1",
        "apiKey": "{env:MY_API_KEY}"
      },
      "models": {
        "custom-chat": {
          "name": "Custom Chat Model"
        }
      }
    }
  }
}

配置保存后，在终端执行 opencode models，如果能看到 my-gateway/custom-chat 这个模型，说明配置文件已经正常加载。启动 opencode 后在交互界面输入 /models，也可以手动切换到刚配置的自定义模型。

这个示例里最值得说的是 apiKey 的写法：{env:MY_API_KEY} 表示Opencode运行时从环境变量里读取 MY_API_KEY 的值。不要直接把密钥明文写在配置文件里，尤其是团队协作时配置文件会被同步共享，密钥一旦提交到版本库就等于泄露了。

3.2 接入本地Ollama模型

本地Ollama模型的接入方式和上面几乎一样，Ollama本身提供了OpenAI兼容的接口，地址是 http://localhost:11434/v1。先确保Ollama服务已经在运行，然后在浏览器或PowerShell里访问一下这个地址，能返回JSON就说明服务正常。

Ollama不需要API Key，配置时可以直接省略 apiKey 字段，也可以留空字符串。示例配置如下：

json复制{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama-local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama Local",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:14b": {
          "name": "Qwen Coder 14B"
        }
      }
    }
  }
}

这里的坑在于模型ID必须和Ollama里面 ollama list 展示的完全一致，包括冒号后面的标签。如果你写成 qwen2.5-coder，而实际本地标签是 qwen2.5-coder:14b，请求就会报模型不存在。model的key就是发送给服务端的模型参数，这一点对任何provider都成立。

3.3 给模型配置合理的上下文窗口

自定义模型最常见的问题之一，就是没有配置 limit 字段。Opencode默认会按内置模型的已知参数去计算上下文窗口，但自定义模型它不知道，所以我们需要手动声明。继续用上面的Ollama示例，补充完整版：

json复制{
  "provider": {
    "ollama-local": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama Local",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen2.5-coder:14b": {
          "name": "Qwen Coder 14B",
          "limit": {
            "context": 32000,
            "output": 4096
          }
        }
      }
    }
  }
}

limit.context 表示模型能处理的上下文总token数，limit.output 表示单次最多生成多少token。这里给出的数值是按常见模型参数写的，实际要以你用的模型官方说明为准。宁可设置得保守一点，也不要往大了填——填大了Opencode会认为模型能接收很长的上下文，把大量内容一次性塞过去，结果服务端直接报超长错误。

补充一个估算方法：英文场景下大约4个字符算1个token，中文场景下一个汉字大约1到2个token。如果你的代码库里有大量中文注释，那么同样字符数消耗的token会比纯英文多不少。

4. 配置字段深度拆解

4.1 provider字段的完整结构

一个provider在配置文件中由几个子字段组成，下面把每个字段的作用说清楚：

npm 字段最容易被忽视。如果你的服务端实际上是Anthropic格式，却用了 @ai-sdk/openai-compatible，请求格式对不上，通常会收到400或422错误。反过来，OpenAI兼容的服务用 @ai-sdk/anthropic 也一样不行。选定协议适配包之前，先确认服务端文档说的接口格式。

4.2 baseURL和apiKey的细节

baseURL 的常见问题是结尾路径到底要不要带 /v1。这没有统一答案，完全取决于服务端。OpenAI官方以及绝大多数兼容网关，请求路径是 /v1/chat/completions，所以baseURL写成 https://api.example.com/v1 是正确的；但也有的内部网关自定义了路径前缀，可能不需要 /v1。最稳妥的做法是直接看服务端文档，或者用PowerShell实测：

powershell复制Invoke-RestMethod -Uri "https://api.example.com/v1/models" -Headers @{ Authorization = "Bearer $env:MY_API_KEY" } -Method Get

这段命令会直接列出该API端点下可用的模型。如果返回正常，说明URL路径和Key都没问题；如果404，把 /v1 去掉再试一次。

apiKey 的推荐写法是 {env:变量名}，Windows下设置环境变量有两种方式：临时生效用 $env:MY_API_KEY="sk-xxx"，只对当前PowerShell窗口有效；永久生效用 setx MY_API_KEY "sk-xxx"，设置后需要新开一个终端窗口才生效。这里有个细节：setx设置完当前窗口读不到新值，必须重开窗口，很多人改了环境变量后Opencode读不到Key，就是忘了这一步。

4.3 模型下的options参数

模型配置里还可以放 options 字段，用来覆盖采样参数。比如：

json复制"models": {
  "custom-chat": {
    "name": "Custom Chat Model",
    "options": {
      "temperature": 0.2,
      "topP": 0.9
    }
  }
}

temperature 控制随机性，写代码场景推荐0.2到0.4，太低会显得死板，太高容易编造接口。topP 是核采样参数，不是所有API都支持，有些服务端不支持 topP 时，带着这个参数请求会直接报错。所以我的建议是：先只配置 temperature，如果本地验证没问题再考虑要不要加其他参数。这样能减少一个排查变量。

对于代码生成场景，还有一个可选字段 options.tools 或模型是否具备工具调用能力，但这属于进阶范畴，大部分OpenAI兼容模型默认支持，不用特意配置。如果你的模型列表里工具调用不可用，Opencode在自然语言对话时会有感知，不影响普通代码问答。

5. Windows下的常见问题与排查实录

5.1 高频问题速查表

以下问题都是我实际遇到或者被朋友问过的，按出现频率排个序：

5.2 一条完整的排查链路

先把最基础的问题说在前面：任何时候配置了自定义模型不生效，第一步不是看配置，而是验证你的API端点本身能不能通。Windows下这个验证成本极低，开个PowerShell窗口直接请求一次。

比如对接远程兼容API：

powershell复制$headers = @{ Authorization = "Bearer $env:MY_API_KEY" }
Invoke-WebRequest -Uri "https://api.example.com/v1/models" -Headers $headers

如果这一步就报错，那配置写什么都没用，问题在网络或服务端，不在Opencode。如果这一步正常，再回到Opencode这边看日志。终端里启动Opencode时，错误信息通常会直接打印出来，比如 provider error 后面跟着HTTP状态码。根据状态码去速查表里找对应原因就行。

还有一个Windows特有的小坑：PowerShell里复制JSON配置时，如果用双引号包裹JSON字符串并直接传给命令，内部的双引号会全部被吃掉。比如某些教程会让你用 echo "{"provider": ...}" > opencode.json，这在PowerShell里一定会出错。正确做法是用VS Code直接新建文件再写入内容，或者用单引号包裹整段字符串再重定向：

powershell复制'{"provider":{"my-gateway":{"npm":"@ai-sdk/openai-compatible"}}}' | Out-File -Encoding utf8 opencode.json

这个细节能帮你节省至少十分钟的排查时间。

6. 一些Windows实测后的经验总结

6.1 多套配置环境的切换思路

Windows下没有Linux那种软链接便利，但配置文件本身支持JSON合并，所以多环境切换完全可以用“全局放基础provider，项目文件放覆盖项”的思路来做。我在本机维护了一套固定的全局配置：公司内部网关、Ollama、一个通用兼容端点，全部定义好。然后在不同项目里只写 model 字段或临时覆盖某个provider，不需要改全局文件。

如果项目之间参数差异过大，也可以手动备份几个 opencode.json.example 模板放在项目仓库里，需要时复制成 opencode.json。注意模板文件不要包含真实Key，Key永远走环境变量。

6.2 团队共享配置时的纪律

团队协作时，配置文件可以提交到仓库，但有几条红线必须守住：配置文件里禁止出现真实API Key；不要在配置里写个人专属的baseURL；模型参数的选择尽量固定，避免每个人提交一版不同的temperature。我们团队的做法是只提交 opencode.json.example，由各自复制成 opencode.json，环境变量名提前约定好并写进README。

6.3 最后说点个人体会

在Windows下把Ollama和Opencode配好之后，我个人的使用频率反而超过了很多远程API。本机模型没有网络延迟，断网也能用，配合较小的context窗口，日常代码补全和单文件解释完全够用。远程模型则留给需要大上下文或复杂重构的场景。配置自定义模型这件事，本质上就是让工具贴合你的实际环境，而不是反向迁就工具默认值。

踩过几次配置文件解析失败的坑之后，我现在每次修改完配置都会先跑一次 opencode models 确认模型列表，再进交互界面跑一条最简单的对话，确认通了才继续干活。这套流程看起来多花几秒，实际上比出了问题再翻日志高效得多。如果你也在Windows下用Opencode，按上面的步骤配置一遍，应该能少走不少弯路。