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

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

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

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

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

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

脚本仓库：

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

---

坑 1：找不到 models.json

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

%USERPROFILE%\.workbuddy\models.json

例如：

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

PowerShell 里可以这样查看：

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

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

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

解决办法：

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

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

---

坑 2：JSON 格式写坏

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

比如少一个逗号：

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

这不是合法 JSON。

正确写法：

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

再比如最后多一个逗号：

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

标准 JSON 也不允许这样写。

检查方法：

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

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

解决办法：

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

---

坑 3：models.json 结构写错

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

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

如果你写成单个对象：

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

可能就无法按预期读取。

排查时先确认：

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

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

---

坑 4：base_url 少了 /v1

这是最容易忽略的坑。

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

正确示例：

https://cn.crazyrouter.com/v1

容易写错成：

https://cn.crazyrouter.com

或者重复写成：

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

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

推荐规则：

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

PowerShell 里可以这么处理：

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

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

所以你传：

https://cn.crazyrouter.com

它会写入：

https://cn.crazyrouter.com/v1

---

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

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

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

如果你用环境变量方式：

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

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

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

可以检查一下：

$env:CRAZYROUTER_API_KEY

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

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

---

坑 6：WorkBuddy 没有完全重启

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

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

建议：

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

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

---

坑 7：模型 ID 写错

模型 ID 不是随便写的。

比如：

claude-opus-4-8

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

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

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

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

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

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

---

坑 8：重复添加模型

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

比如：

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

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

可以用 PowerShell 查重复：

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

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

---

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

这是最麻烦的情况。

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

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

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

models.json.bak.20260605-140000

恢复方法：

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

---

一键配置方式

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

打开 PowerShell：

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

或者先设置 API Key：

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

脚本会写入：

%USERPROFILE%\.workbuddy\models.json

接口地址：

https://cn.crazyrouter.com/v1

默认模型：

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

---

更稳妥的本地执行方式

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

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

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

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

如果想清理旧配置：

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

如果想自定义模型：

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

---

最小可用配置参考

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

[
  {
    "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 没重启；
• 重复模型太多；
• 没有备份。

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

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

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

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

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