WorkBuddy 自定义模型不生效？models.json、base_url 和模型 ID 排错清单

WorkBuddy 自定义模型不生效？models.json、base_url 和模型 ID 排错清单#

WorkBuddy 支持自定义模型后，很多开发者会尝试接入自己的模型服务或 OpenAI 兼容接口。

配置本身并不复杂，但实际使用时经常会遇到这些情况：

• 配置写完了，模型列表里没出现。
• 模型出现了，但一调用就报错。
• 同一个模型出现了好几次。
• 改完 models.json 后 WorkBuddy 启动异常。
• 不确定 base_url 到底该怎么写。

这篇文章整理一个排错清单，帮助你从文件路径、JSON 格式、接口地址、模型 ID、API Key、备份恢复几个方面逐项检查。

1. 先确认 models.json 路径#

用户级配置文件通常在：

%USERPROFILE%\.workbuddy\models.json

PowerShell 中可以这样查看：

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

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

这时可能有两种情况：

1. WorkBuddy 还没有生成用户级模型配置。
2. 你需要手动创建 .workbuddy 目录和 models.json 文件。

可以用脚本自动创建，也可以手动创建。

2. 配置后必须完全重启 WorkBuddy#

很多人改完配置后，只是关闭窗口，然后马上重新打开。

但有些桌面程序可能仍然有后台进程。

建议：

1. 退出 WorkBuddy。
2. 打开任务管理器。
3. 确认 WorkBuddy 相关进程已经结束。
4. 再重新启动。

如果程序没有重新读取配置，模型列表就不会更新。

3. 检查 JSON 格式是否正确#

models.json 必须是合法 JSON。

常见错误包括：

少逗号#

错误示例：

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

正确示例：

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

多余逗号#

错误示例：

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

标准 JSON 不允许最后一个元素后面多逗号。

引号错误#

JSON 字符串必须使用英文双引号：

{
  "id": "model-a"
}

不要写成：

{
  'id': 'model-a'
}

PowerShell 可以尝试读取验证：

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

如果这里报错，说明 JSON 格式有问题。

4. 检查配置结构是不是数组#

很多 WorkBuddy 自定义模型配置是数组结构，例如：

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

如果你写成单个对象：

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

程序可能无法按预期读取。

如果你不确定结构，可以参考官方文档或先备份，再用自动化脚本生成一份标准结构。

5. 检查 base_url 是否带 /v1#

很多 OpenAI 兼容接口的基础地址需要以 /v1 结尾。

例如：

https://api.example.com/v1

如果你只写：

https://api.example.com

调用时可能会找不到正确接口。

如果你写成：

https://api.example.com/v1/v1

也会出错。

一个比较稳妥的规则是：

1. 去掉末尾 /
2. 如果没有 /v1，补上 /v1
3. 不要重复补

PowerShell 逻辑可以这样写：

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

开源脚本 workbuddy-crazyrouter 里也做了类似处理。

6. 检查模型 ID 是否真实可用#

model 或 id 不是随便写的。

如果配置里写了：

{
  "id": "claude-opus-4-8"
}

那服务端也必须认识这个模型 ID。

如果模型 ID 写错，常见现象是：

• WorkBuddy 能显示模型
• 但调用时报 404
• 或返回 model not found
• 或返回权限不足

排查方法：

1. 查看模型服务文档。
2. 查看模型列表接口。
3. 先用 curl 单独测试模型是否能调用。
4. 再放进 WorkBuddy。

7. 检查 API Key#

API Key 错误时，常见返回是：

建议不要把 Key 写进截图或公开文章。

如果用 PowerShell 设置环境变量：

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

注意这个环境变量只在当前 PowerShell 会话里有效。关闭窗口后就没了。

如果要长期保存，应该使用更安全的密钥管理方式，或者每次运行脚本时手动输入。

8. 检查能力字段#

WorkBuddy 自定义模型里可能包含这些能力字段：

{
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": false,
  "useCustomProtocol": false
}

这些字段会影响 WorkBuddy 如何使用模型。

例如：

• 如果模型不支持图片输入，就不要把 supportsImages 写成 true。
• 如果模型不支持工具调用，开启后可能出现异常。
• 如果接口路径需要特殊处理，才考虑 useCustomProtocol。

不确定时，先用保守配置：

{
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": false,
  "useCustomProtocol": false
}

然后再逐步测试。

9. 检查是否重复写入模型#

如果你多次手动复制配置，可能出现多个相同模型 ID。

可以用 PowerShell 粗略检查：

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

如果出现重复，可以手动删除，也可以使用脚本按模型 ID 合并。

示例脚本：

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

它会对同名模型执行更新，避免重复写入。

10. 如何恢复旧配置？#

如果你使用的脚本会自动备份，通常会看到类似文件：

models.json.bak.20260605-140000

恢复步骤：

1. 完全退出 WorkBuddy。
2. 打开 %USERPROFILE%\.workbuddy\。
3. 删除当前 models.json，或改名为 models.json.bad。
4. 把备份文件改名为 models.json。
5. 重新启动 WorkBuddy。

如果没有备份，只能重新手动构造配置。

所以每次修改前都建议先备份。

11. 一个最小可用配置示例#

下面是一个最小示例，仅用于说明结构：

[
  {
    "id": "example-model",
    "name": "example-model",
    "vendor": "Custom",
    "url": "https://api.example.com/v1",
    "apiKey": "sk-xxx",
    "supportsToolCall": true,
    "supportsImages": false,
    "supportsReasoning": false,
    "useCustomProtocol": false
  }
]

如果这个结构能被 WorkBuddy 读取，再逐步增加更多模型。

12. 推荐排错顺序#

建议按这个顺序检查：

1. models.json 路径是否正确。
2. JSON 是否能被 ConvertFrom-Json 解析。
3. 配置结构是否是数组。
4. WorkBuddy 是否完全重启。
5. url 是否正确带 /v1。
6. id 是否是服务端真实模型 ID。
7. apiKey 是否有效。
8. 能力字段是否和模型能力匹配。
9. 是否有重复模型。
10. 必要时恢复备份。

总结#

WorkBuddy 自定义模型不生效，通常不是一个大问题，而是几个小配置项中的某一个出了错。

最常见的是：

• 路径不对
• JSON 格式错误
• 没有完全重启
• base_url 少了 /v1
• 模型 ID 写错
• API Key 无效
• 重复模型太多

如果你不想每次手动编辑，可以使用带备份、去重和 URL 规范化的脚本来维护配置。

示例脚本：

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

建议先阅读脚本内容，再根据自己的模型服务修改接口地址和模型列表。

附：使用 https://cn.crazyrouter.com 接入 WorkBuddy 的完整步骤#

如果你的目标是把 WorkBuddy 连接到 Crazyrouter，可以按下面流程配置。

第一步：准备 API Key#

在 Crazyrouter 控制台创建或复制一个可用 API Key。

为了避免把 Key 写进命令历史，也可以先在当前 PowerShell 会话里设置环境变量：

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

第二步：确认接口地址#

WorkBuddy 自定义模型最终需要使用 OpenAI-compatible API 地址。

Crazyrouter 国内接口地址建议写成：

https://cn.crazyrouter.com/v1

如果你传入的是：

https://cn.crazyrouter.com

示例脚本会自动规范成：

https://cn.crazyrouter.com/v1

第三步：一键写入 WorkBuddy 配置#

打开 PowerShell，执行：

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

如果已经提前设置了环境变量，脚本会直接读取：

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

脚本默认会写入这些模型：

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

第四步：重启 WorkBuddy#

执行完成后，完全退出 WorkBuddy，再重新打开。

然后在模型列表中选择：

Custom / 自定义模型

如果模型列表没有刷新，优先检查 WorkBuddy 是否仍有后台进程没有退出。

第五步：本地下载后执行（更适合谨慎场景）#

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

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"

如果想清理旧的 Crazyrouter 自定义模型，只保留本次写入的模型，可以加：

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

第六步：恢复旧配置#

脚本默认会备份旧配置，备份文件类似：

%USERPROFILE%\.workbuddy\models.json.bak.20260605-140000

如果新配置不符合预期：

1. 完全退出 WorkBuddy。
2. 打开 %USERPROFILE%\.workbuddy\。
3. 删除或改名当前 models.json。
4. 把备份文件改名为 models.json。
5. 重新打开 WorkBuddy。

常见接入问题#

开源脚本地址：

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