WorkBuddy 如何配置自定义模型？从 models.json 到 PowerShell 自动化

WorkBuddy 如何配置自定义模型？从 models.json 到 PowerShell 自动化#

WorkBuddy 支持自定义模型，这意味着你不一定只能使用默认模型，也可以把符合接口规范的第三方模型服务接入进来。

很多教程会直接告诉你“修改 models.json”，但对新手来说，真正麻烦的不是知道要改哪个文件，而是：

• models.json 放在哪里？
• 每个字段分别是什么意思？
• url 要不要带 /v1？
• API Key 写错了怎么办？
• 改坏 JSON 后怎么恢复？
• 多次添加同一个模型会不会重复？

这篇文章从工程角度讲清楚 WorkBuddy 自定义模型配置的基本原理，并给出一个 PowerShell 自动化脚本示例，用来减少手动编辑 JSON 的出错概率。

说明：本文重点是 WorkBuddy 自定义模型配置方法和脚本自动化思路，不讨论具体模型服务优劣。

1. WorkBuddy 自定义模型配置的基本思路#

WorkBuddy 的自定义模型，本质上是把模型信息写入本地配置文件。

常见配置项包括：

一个简化后的模型配置可能长这样：

{
  "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 会读取这些配置，并在模型列表里显示对应的自定义模型。

2. models.json 在哪里？#

用户级配置文件通常在：

%USERPROFILE%\.workbuddy\models.json

换成 PowerShell 里的路径，大概是：

$HOME\.workbuddy\models.json

例如 Windows 用户名是 alice，那路径可能是：

C:\Users\alice\.workbuddy\models.json

如果这个文件不存在，可以手动创建，也可以通过脚本自动创建。

3. 手动编辑 models.json 容易出哪些问题？#

手动编辑不是不行，但比较容易踩坑。

3.1 JSON 格式错误#

比如少一个逗号：

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

这个 JSON 就是错误的。

正确写法：

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

3.2 url 少了 /v1#

很多 OpenAI 兼容接口要求地址以 /v1 结尾，例如：

https://api.example.com/v1

如果只写：

https://api.example.com

就可能导致 WorkBuddy 拼接接口路径时找不到正确 endpoint。

3.3 模型重复写入#

如果你多次复制粘贴配置，可能会出现多个相同 id 的模型。

这样不仅难维护，也可能导致 WorkBuddy 读取时出现混乱。

3.4 改坏后没有备份#

很多人第一次改配置时，没有先备份原文件。

一旦格式改坏，想恢复就比较麻烦。

所以比较稳妥的做法是：

1. 修改前先备份。
2. 写入时做 JSON 格式校验。
3. 对同名模型执行更新，而不是重复追加。
4. 保留其它已有自定义模型。

4. 用 PowerShell 自动化配置#

下面这个开源脚本就是为了解决这些问题：

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

它做的事情很简单：

• 找到 WorkBuddy 的 models.json
• 如果文件不存在就创建
• 如果文件存在就先备份
• 读取已有模型配置
• 合并新的自定义模型
• 对同名模型去重
• 把接口地址规范成 /v1
• 写回 JSON 文件

一键执行方式：

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

脚本会提示输入 API Key。输入的 Key 只会写入本机 WorkBuddy 配置文件。

如果不想交互输入，也可以先设置环境变量：

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

执行完成后，需要完全退出并重新打开 WorkBuddy，然后在模型列表中选择 Custom / 自定义模型。

5. 为什么脚本会自动补 /v1？#

脚本里有一个 Base URL 规范化逻辑。

如果你传入：

https://cn.crazyrouter.com

脚本会自动变成：

https://cn.crazyrouter.com/v1

这是因为许多 OpenAI 兼容接口会把 /v1 作为 API 版本路径。

如果配置文件里少了这层路径，后续请求可能会失败。

相关逻辑可以概括成：

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

这个小处理可以减少很多“接口地址看起来没错，但就是连不上”的问题。

6. 默认模型列表#

脚本默认会写入几组模型：

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

这些模型会被写成 WorkBuddy 的自定义模型项。

如果你想自定义模型列表，可以下载脚本后本地执行，并传入 -Models 参数。

例如：

.\setup-workbuddy-crazyrouter.ps1 `
  -Models "model-a", "model-b", "model-c"

7. 保留旧模型还是替换旧模型？#

默认情况下，脚本会保留原有其它自定义模型。

也就是说，如果你之前已经配置了别的模型，脚本不会直接删掉它们。

如果你希望清理旧的同类配置，可以使用：

.\setup-workbuddy-crazyrouter.ps1 -ReplaceCrazyrouter

这个参数会删除旧的同类配置，只保留本次写入的模型。

适合这些场景：

• 之前配置过很多重复模型
• 想重新整理模型列表
• 想避免旧 URL 和新 URL 混在一起

8. 备份和恢复#

脚本默认会在写入前备份旧配置。

备份文件类似：

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

如果新配置不符合预期，可以这样恢复：

1. 关闭 WorkBuddy。
2. 找到 .workbuddy 目录。
3. 删除当前 models.json。
4. 把备份文件改名为 models.json。
5. 重新打开 WorkBuddy。

如果你明确不想备份，可以使用：

.\setup-workbuddy-crazyrouter.ps1 -NoBackup

但第一次使用不建议加这个参数。

9. 不放心一键执行怎么办？#

从安全角度看，直接执行远程 PowerShell 脚本前，最好先阅读脚本内容。

你可以先打开这个地址查看源码：

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

或者先下载到本地：

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

看完后再执行：

.\setup-workbuddy-crazyrouter.ps1

这比直接 | iex 更适合对安全比较敏感的环境。

10. 常见问题#

Q1：执行完脚本，WorkBuddy 里没看到模型？#

先确认是否完全退出并重新打开 WorkBuddy。只是关闭窗口不一定等于进程完全退出。

Q2：API Key 会上传吗？#

脚本只把 API Key 写入本机的 WorkBuddy 配置文件。你也可以直接阅读脚本源码确认它没有上传逻辑。

Q3：配置文件改坏了怎么办？#

找到 .bak.yyyyMMdd-HHmmss 备份文件，改回 models.json，然后重启 WorkBuddy。

Q4：可以改接口地址吗？#

可以。使用 -BaseUrl 参数：

.\setup-workbuddy-crazyrouter.ps1 -BaseUrl "https://your-api.example.com"

脚本会自动补齐 /v1。

Q5：可以改模型列表吗？#

可以。使用 -Models 参数：

.\setup-workbuddy-crazyrouter.ps1 -Models "model-a", "model-b"

总结#

WorkBuddy 自定义模型的关键不复杂：

1. 找到 models.json。
2. 写入模型 ID、接口地址、API Key 和能力字段。
3. 确保 URL 路径正确。
4. 修改前做好备份。
5. 修改后重启 WorkBuddy。

真正容易出错的是手动编辑 JSON 的细节。

如果只是配置一两个模型，手动改也可以；如果经常切换模型、整理模型列表，或者不想每次都处理备份和去重，用 PowerShell 脚本会更稳。

示例脚本已开源：

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