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 稳很多。