WorkBuddy 自定义模型配置踩坑记录：models.json、/v1、API Key 一次讲清楚

这篇不是官方文档，而是一篇偏实战的踩坑整理。

我在配置 WorkBuddy 自定义模型时，发现真正容易出问题的地方不是"能不能接入第三方模型"，而是一些很小的配置细节：

models.json 路径找错；
JSON 少一个逗号；
base_url 少了 /v1；
API Key 写错；
WorkBuddy 没有完全重启；
模型 ID 写了，但服务端并不存在；
重复添加模型，列表越来越乱；
改坏配置后没有备份。

这些问题都不复杂，但一个个排查很浪费时间。

所以这篇文章按"问题 → 原因 → 解决办法"的方式，把 WorkBuddy 自定义模型配置里常见坑整理一下。文末也放一个 PowerShell 一键配置脚本，方便不想手动改 JSON 的同学使用。

脚本仓库：

text 复制代码

https://github.com/xujfcn/workbuddy-crazyrouter

坑 1：找不到 models.json

WorkBuddy 的用户级模型配置一般在：

text 复制代码

%USERPROFILE%\.workbuddy\models.json

例如：

text 复制代码

C:\Users\你的用户名\.workbuddy\models.json

PowerShell 里可以这样查看：

powershell 复制代码

$ConfigPath = Join-Path $HOME ".workbuddy\models.json"
Write-Host $ConfigPath
Test-Path $ConfigPath

如果返回 False，说明文件不存在。

这种情况不用慌，可能是 WorkBuddy 还没生成用户级配置，也可能是你之前没有配置过自定义模型。

解决办法：

手动创建 .workbuddy 目录；
手动创建 models.json；
或者用脚本自动创建。

一键脚本会自动处理目录不存在的问题。

坑 2：JSON 格式写坏

这是手动编辑最常见的问题。

比如少一个逗号：

json 复制代码

{
  "id": "model-a"
  "name": "model-a"
}

这不是合法 JSON。

正确写法：

json 复制代码

{
  "id": "model-a",
  "name": "model-a"
}

再比如最后多一个逗号：

json 复制代码

[
  {"id": "model-a"},
]

标准 JSON 也不允许这样写。

检查方法：

powershell 复制代码

Get-Content $HOME\.workbuddy\models.json -Raw | ConvertFrom-Json

如果这里报错，WorkBuddy 大概率也读不出来。

解决办法：

用编辑器格式化 JSON；
修改前先备份；
尽量用脚本生成 JSON，减少手写错误。

坑 3：models.json 结构写错

有些配置文件要求是数组结构，例如：

json 复制代码

[
  {
    "id": "example-model",
    "name": "example-model",
    "vendor": "Custom",
    "url": "https://cn.crazyrouter.com/v1",
    "apiKey": "sk-xxx"
  }
]

如果你写成单个对象：

json 复制代码

{
  "id": "example-model",
  "name": "example-model"
}

可能就无法按预期读取。

排查时先确认：

powershell 复制代码

$models = Get-Content $HOME\.workbuddy\models.json -Raw | ConvertFrom-Json
$models.GetType().FullName

如果不是数组，就要检查配置结构。

坑 4：base_url 少了 `/v1`

这是最容易忽略的坑。

很多 OpenAI-compatible API 的基础地址需要带 /v1。

正确示例：

text 复制代码

https://cn.crazyrouter.com/v1

容易写错成：

text 复制代码

https://cn.crazyrouter.com

或者重复写成：

text 复制代码

https://cn.crazyrouter.com/v1/v1

这两种都可能导致调用失败。

推荐规则：

先去掉末尾 /；
如果没有 /v1，补上 /v1；
不要重复补。

PowerShell 里可以这么处理：

powershell 复制代码

$normalized = $BaseUrl.Trim().TrimEnd("/")
if ($normalized -notmatch "/v1$") {
    $normalized = "$normalized/v1"
}

workbuddy-crazyrouter 脚本已经内置了这个逻辑。

所以你传：

text 复制代码

https://cn.crazyrouter.com

它会写入：

text 复制代码

https://cn.crazyrouter.com/v1

坑 5：API Key 写错或没写进去

API Key 有问题时，常见表现是：

401 Unauthorized；
403 Forbidden；
模型能显示，但无法调用；
WorkBuddy 里请求失败。

如果你用环境变量方式：

powershell 复制代码

$env:CRAZYROUTER_API_KEY="sk-你的CrazyrouterKey"

要注意：这个变量只在当前 PowerShell 窗口有效。

如果你开了一个新窗口，变量就没了。

可以检查一下：

powershell 复制代码

$env:CRAZYROUTER_API_KEY

如果没有输出，说明当前窗口没有设置。

一键脚本如果检测不到环境变量，会提示你输入 API Key。

坑 6：WorkBuddy 没有完全重启

配置写完后，一定要完全退出并重新打开 WorkBuddy。

很多桌面程序关闭窗口后，后台进程还在。

建议：

关闭 WorkBuddy；
打开任务管理器；
确认 WorkBuddy 进程不存在；
再重新打开。

如果只是关窗口，配置可能不会重新读取。

坑 7：模型 ID 写错

模型 ID 不是随便写的。

比如：

text 复制代码

claude-opus-4-8

这个 ID 必须是接口服务端真实支持的模型名。

如果模型 ID 写错，可能会出现：

model not found；
404；
权限不足；
WorkBuddy 显示模型，但调用失败。

建议先用默认模型列表测试：

text 复制代码

claude-opus-4-8
claude-opus-4-7
claude-sonnet-4-6
gpt-5.5
gpt-5.4

确认能正常使用后，再自己改模型列表。

坑 8：重复添加模型

手动编辑 JSON 时，很容易把同一个模型复制多次。

比如：

json 复制代码

[
  {"id": "gpt-5.5"},
  {"id": "gpt-5.5"},
  {"id": "gpt-5.5"}
]

模型列表一多，后面排查就很麻烦。

可以用 PowerShell 查重复：

powershell 复制代码

$models = Get-Content $HOME\.workbuddy\models.json -Raw | ConvertFrom-Json
$models | Group-Object id | Where-Object { $_.Count -gt 1 }

一键脚本会按模型 ID 去重，重复执行也不会一直追加同名模型。

坑 9：没有备份，改坏后不知道怎么恢复

这是最麻烦的情况。

如果你手动改配置，建议第一步就备份：

powershell 复制代码

Copy-Item $HOME\.workbuddy\models.json $HOME\.workbuddy\models.json.bak

一键脚本默认会自动备份，备份文件类似：

text 复制代码

models.json.bak.20260605-140000

恢复方法：

关闭 WorkBuddy；
删除当前 models.json；
把备份文件改名为 models.json；
重启 WorkBuddy。

一键配置方式

如果你不想手动排这些坑，可以直接使用脚本。

打开 PowerShell：

powershell 复制代码

iwr https://raw.githubusercontent.com/xujfcn/workbuddy-crazyrouter/main/setup-workbuddy-crazyrouter.ps1 -UseB | iex

或者先设置 API Key：

powershell 复制代码

$env:CRAZYROUTER_API_KEY="sk-你的CrazyrouterKey"
iwr https://raw.githubusercontent.com/xujfcn/workbuddy-crazyrouter/main/setup-workbuddy-crazyrouter.ps1 -UseB | iex

脚本会写入：

text 复制代码

%USERPROFILE%\.workbuddy\models.json

接口地址：

text 复制代码

https://cn.crazyrouter.com/v1

默认模型：

text 复制代码

claude-opus-4-8
claude-opus-4-7
claude-sonnet-4-6
gpt-5.5
gpt-5.4

更稳妥的本地执行方式

如果你不想直接执行远程脚本，可以先下载：

powershell 复制代码

iwr https://raw.githubusercontent.com/xujfcn/workbuddy-crazyrouter/main/setup-workbuddy-crazyrouter.ps1 -OutFile setup-workbuddy-crazyrouter.ps1

打开脚本看一遍，确认没问题后执行：

powershell 复制代码

.\setup-workbuddy-crazyrouter.ps1 -BaseUrl "https://cn.crazyrouter.com"

如果想清理旧配置：

powershell 复制代码

.\setup-workbuddy-crazyrouter.ps1 -BaseUrl "https://cn.crazyrouter.com" -ReplaceCrazyrouter

如果想自定义模型：

powershell 复制代码

.\setup-workbuddy-crazyrouter.ps1 `
  -BaseUrl "https://cn.crazyrouter.com" `
  -Models "claude-sonnet-4-6", "gpt-5.5"

最小可用配置参考

如果你想手动配置，可以参考这个结构：

json 复制代码

[
  {
    "id": "gpt-5.5",
    "name": "gpt-5.5",
    "vendor": "Custom",
    "url": "https://cn.crazyrouter.com/v1",
    "apiKey": "sk-xxx",
    "supportsToolCall": true,
    "supportsImages": false,
    "supportsReasoning": false,
    "useCustomProtocol": false
  }
]

重点检查：

外层是不是数组；
url 是否是 https://cn.crazyrouter.com/v1；
apiKey 是否正确；
id 是否是真实模型 ID；
JSON 格式是否正确。

总结

WorkBuddy 自定义模型配置失败，大多数不是大问题，而是小细节：

配置文件路径不对；
JSON 写坏；
URL 少了 /v1；
API Key 没写对；
模型 ID 不存在；
WorkBuddy 没重启；
重复模型太多；
没有备份。

如果你想省掉这些排查步骤，可以用这个脚本：

text 复制代码

https://github.com/xujfcn/workbuddy-crazyrouter

它的核心价值不是"多复杂"，而是把容易出错的配置动作自动化：

自动创建配置文件；
自动备份；
自动补 /v1；
自动去重；
默认写入常用模型；
支持恢复旧配置。

对新手来说，这比手动改 models.json 稳很多。

WorkBuddy 自定义模型配置踩坑记录：models.json、/v1、API Key 一次讲清楚