WorkBuddy 自定义模型配置踩坑记录：models.json、/v1、API Key 一次讲清楚
WorkBuddy 自定义模型配置踩坑记录：models.json、/v1、API Key 一次讲清楚
这篇不是官方文档，而是一份实战经验总结。配置 WorkBuddy 自定义模型时，最折腾人的往往不是“能不能接第三方模型”，而是一些小得不能再小的细节：models.json 路径找不到、JSON 里少一个逗号、base_url 少了 /v1、API Key 写错、WorkBuddy 没完全重启、模型 ID 服务端压根儿不存在、重复加模型搞得列表乱七八糟、改坏配置还没备份。这些问题单个看都不复杂，但挨个排查下来，时间就浪费了。
下面按“问题 → 原因 → 解决办法”的方式，把这些常见坑挨个儿捋清楚。文末还放了一个 PowerShell 一键配置脚本，适合不想手动改 JSON 的同学。
脚本仓库：
https://github.com/xujfcn/workbuddy-crazyrouter
坑 1：找不到 models.json
WorkBuddy 的用户级模型配置文件，通常放在：
%USERPROFILE%.workbuddymodels.json
举个例子：
C:Users你的用户名.workbuddymodels.json
在 PowerShell 里可以这样快速定位：
$ConfigPath = Join-Path $HOME ".workbuddymodels.json"
Write-Host $ConfigPath
Test-Path $ConfigPath
如果返回 False，说明文件还没生成。别慌，这可能是 WorkBuddy 还没创建用户级配置，或者你之前压根没配置过自定义模型。
解决办法：手动创建 .workbuddy 目录，再手动创建 models.json；或者直接用一键脚本，它会自动处理目录不存在的状况。
坑 2：JSON 格式写坏
手动编辑 JSON 最容易翻车。比如少写一个逗号：
{"id": "model-a""name": "model-a"}
这不是合法的 JSON。正确写法：
{"id": "model-a","name": "model-a"}
再比如末尾多一个逗号：
[{"id": "model-a"},]
标准 JSON 也不允许这样。
检查方法很简单，在 PowerShell 里跑一行：
Get-Content $HOME.workbuddymodels.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.workbuddymodels.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 就补上，千万别补重复。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。很多桌面程序关闭窗口后，后台进程还在。
建议做法：关闭 WorkBuddy → 打开任务管理器 → 确认 WorkBuddy 进程不存在 → 再重新打开。如果只是关窗口，配置可能不会重新读取。
坑 7：模型 ID 写错
模型 ID 不是随便写的。比如 claude-opus-4-8，这个 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.workbuddymodels.json -Raw | ConvertFrom-Json
$models | Group-Object id | Where-Object { $_.Count -gt 1 }
一键脚本会按模型 ID 去重，重复执行也不会一直追加同名模型。
坑 9：没有备份，改坏后不知道怎么恢复
这是最麻烦的情况。如果你手动改配置，第一步就该备份：
Copy-Item $HOME.workbuddymodels.json $HOME.workbuddymodels.json.bak
一键脚本默认会自动备份，备份文件类似 models.json.bak.20260605-140000。恢复方法：关闭 WorkBuddy → 删除当前 models.json → 把备份文件改名为 models.json → 重启 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%.workbuddymodels.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 是否带 /v1，apiKey 是否正确，id 是否是真实模型 ID，JSON 格式是否合法。
总结
WorkBuddy 自定义模型配置失败，大多数不是大问题，而是小细节：配置文件路径不对、JSON 写坏、URL 少了 /v1、API Key 没写对、模型 ID 不存在、WorkBuddy 没重启、重复模型太多、没有备份。
如果希望省掉这些排查步骤，可以直接用这个脚本：
https://github.com/xujfcn/workbuddy-crazyrouter
它的核心价值不是“多复杂”，而是把容易出错的配置动作自动化：自动创建配置文件、自动备份、自动补 /v1、自动去重、默认写入常用模型、支持恢复旧配置。对新手来说，这比手动改 models.json 稳很多。
