WorkBuddy 如何接入 Claude Opus 4.8 和 GPT-5.5？自定义模型配置实战

最近在折腾 WorkBuddy 的自定义模型配置，发现它其实不只能用默认模型列表。只要后端服务兼容 OpenAI API，就可以把很多新模型接进去，比如 claude-opus-4-8、gpt-5.5、claude-sonnet-4-6、gpt-5.4 等。

这篇文章整理一下完整配置思路，重点讲清楚几个容易踩坑的地方：

  • WorkBuddy 的模型配置文件在哪里？
  • models.json 里关键字段怎么理解？
  • Base URL 为什么一定要注意 /v1？
  • Claude Opus 4.8 和 GPT-5.5 分别适合什么场景？
  • 团队使用时如何控制 Token 权限和调用成本？
  • 配置后 WorkBuddy 没显示模型该怎么排查？

我这里用的是 Crazyrouter 的 OpenAI-compatible API 做示例，因为它可以用一个 API Key 统一调用多个模型，比较适合 WorkBuddy 这种需要灵活切换模型的工具。

Crazyrouter 文档：https://docs.crazyrouter.com/en/introduction?utm_source=csdn&utm_medium=article&utm_campaign=dev_community

1. 为什么要给 WorkBuddy 配自定义模型？

WorkBuddy 这类 AI 工作流工具，本质上不是单纯的聊天窗口，而是把模型能力放进日常开发流程里：

  • 写代码、改 Bug
  • 分析报错日志
  • 生成测试用例
  • 阅读长文档
  • 理解项目结构
  • 辅助写 README / API 文档
  • 做自动化任务规划

问题在于：模型更新速度很快，客户端默认模型列表往往跟不上。

如果只能等软件官方更新模型列表，实际使用会比较被动。自定义模型的价值就在这里：只要服务端提供 OpenAI-compatible API，WorkBuddy 就可以提前接入新模型。

比如可以这样分工：

模型 更适合的场景
claude-opus-4-8 长文档分析、复杂推理、架构审查、多步骤任务规划
gpt-5.5 日常开发助手、代码生成、问题排查、文档编写
claude-sonnet-4-6 日常编码、批量文本处理、成本与效果平衡
gpt-5.4 常规问答、轻量代码修改、配置说明

我个人更建议不要只配置一个“大模型”。因为实际开发里，大部分任务并不需要一直上最高规格模型。多个模型放在 WorkBuddy 里，按任务切换，体验和成本都会更合理。

2. WorkBuddy 自定义模型的本质：改 models.json

WorkBuddy 的自定义模型配置，本质上是写入本地配置文件：

%USERPROFILE%\.workbuddy\models.json

一个简化后的模型配置大概长这样：

{
  "id": "gpt-5.5",
  "name": "GPT-5.5 via Crazyrouter",
  "vendor": "Custom",
  "url": "https://cn.crazyrouter.com/v1",
  "apiKey": "YOUR_CRAZYROUTER_API_KEY",
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": true,
  "useCustomProtocol": false
}

几个字段需要重点理解：

字段 说明
id 模型真实 ID，最终请求时会用这个值
name WorkBuddy 界面里展示的名称
vendor 自定义模型通常写 Custom
url API Base URL，OpenAI-compatible 服务一般需要 /v1
apiKey 调用接口用的 Key
supportsToolCall 是否支持工具调用
supportsImages 是否支持图片输入
supportsReasoning 是否支持推理能力
useCustomProtocol OpenAI-compatible API 通常设为 false

当然，你可以手动编辑这个 JSON 文件。但手动改配置有几个风险：

  • JSON 多一个逗号就报错；
  • URL 容易漏掉 /v1；
  • 重复写入同名模型后列表混乱；
  • 修改前没有备份，不好恢复；
  • 团队成员各自手改，配置不一致。

所以更推荐用脚本自动写入。

3. 一条 PowerShell 命令写入 WorkBuddy 模型

如果只是想快速把 Crazyrouter 模型接入 WorkBuddy，可以直接用这个开源脚本：

项目地址：https://github.com/xujfcn/workbuddy-crazyrouter?utm_source=csdn&utm_medium=article&utm_campaign=dev_community

在 Windows PowerShell 里执行：

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

脚本会提示你输入 Crazyrouter API Key，然后自动完成这些事情：

  • 创建或读取 %USERPROFILE%\.workbuddy\models.json
  • 写入 Crazyrouter 自定义模型
  • 自动补齐 /v1 API 路径
  • 添加 claude-opus-4-8、gpt-5.5 等模型
  • 对同名模型去重
  • 保留原有其它模型配置
  • 修改前自动备份旧文件

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

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

执行完成后，记得完全退出 WorkBuddy，再重新打开。只关闭窗口有时不够，最好确认托盘或任务管理器里进程已经退出。

4. Claude Opus 4.8 和 GPT-5.5 怎么选？

模型接入只是第一步，更关键的是知道什么时候该用哪个模型。

4.1 复杂推理、长上下文：优先 Claude Opus 4.8

如果任务里包含大量上下文，或者需要比较稳的多步骤推理，可以优先试 claude-opus-4-8。

典型场景：

  • 阅读大型技术文档
  • 分析复杂代码仓库
  • 做架构设计审查
  • 梳理迁移方案
  • 多文件代码审查
  • 产品需求拆解
  • 长上下文问答

这类任务不一定追求最快响应，而是更看重“想清楚”。比如让 WorkBuddy 看一批文件，然后总结模块边界、潜在风险和重构路径，Claude Opus 这类模型会更适合。

4.2 日常开发、通用生产力：优先 GPT-5.5

如果任务是高频开发辅助，gpt-5.5 可以作为主力模型。

典型场景：

  • 写代码片段
  • 修 Bug
  • 解释报错
  • 生成单元测试
  • 写 README
  • 设计 API 调用示例
  • 处理 DevOps 配置
  • 做日常技术问答

它更适合 WorkBuddy 里的大多数日常开发任务：响应速度、综合能力、通用性都比较均衡。

4.3 中间档模型也要保留

不要所有任务都默认最高规格模型。

像下面这些任务，用中间档模型就够了：

  • 普通摘要
  • 格式转换
  • 配置文件解释
  • 批量文本整理
  • 中等复杂度代码修改
  • 简单自动化脚本辅助

一个比较实用的策略是：

常规任务先用中间档或 GPT-5.5，长上下文、复杂推理、高价值任务再上 Claude Opus 4.8。

这样既能保证效果，也能避免调用成本失控。

5. 最常见的坑：Base URL 少了 /v1

很多 WorkBuddy 自定义模型配置失败，不是 API Key 错了，也不是模型不能用，而是 Base URL 写错了。

OpenAI-compatible API 的 Base URL 通常应该是：

https://cn.crazyrouter.com/v1

而不是：

https://cn.crazyrouter.com

少了 /v1 后，客户端拼接接口路径时可能会请求到错误地址，表现出来就是：

  • 模型列表有了，但调用失败；
  • 报 404；
  • 报接口路径不存在；
  • 看起来 Key 没问题，但就是请求不通。

脚本里会做 URL 规范化，所以即使你输入：

https://cn.crazyrouter.com

也会自动处理成：

https://cn.crazyrouter.com/v1

这个细节非常重要。很多“配置看起来都对，但就是不能用”的问题，最后都是这里出了错。

API Endpoint 说明可以看这里：https://docs.crazyrouter.com/en/api-endpoint?utm_source=csdn&utm_medium=article&utm_campaign=dev_community

6. 团队使用时，Token 不要随便全开

个人使用时，一个 API Key 配多个模型通常够用。但如果是团队使用 WorkBuddy，建议把 Token 权限拆细一点。

可以按场景创建不同 Token：

Token 类型 建议权限
开发 Token 允许 gpt-5.5、claude-sonnet-4-6 等日常模型
高阶分析 Token 允许 claude-opus-4-8 等高能力模型
测试 Token 设置较低额度，用于脚本和集成测试
自动化 Token 只允许工作流需要的模型，避免误调用

这样做有几个好处：

  1. 避免所有人无意中调用最高规格模型；
  2. 可以按项目或成员定位调用来源；
  3. 某个 Token 泄漏或异常时，可以单独停用；
  4. 可以用额度限制防止脚本死循环消耗；
  5. 模型白名单和预算控制更清晰。

需要注意：如果 Token 开了模型限制，WorkBuddy 里配置的模型必须在 Token 允许列表中。

否则即使账户余额充足，也可能因为 Token 无权访问该模型而调用失败。

7. 修改配置前，一定要可恢复

改 models.json 前最好有备份。

脚本默认会在修改前生成备份文件，类似：

models.json.bak.20260615093000

如果配置后 WorkBuddy 模型列表异常，可以这样恢复：

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

如果之前手动配过很多旧模型，模型列表已经比较乱，也可以先清理旧的 Crazyrouter 配置，再重新写入。

8. 关于一键命令的安全提醒

PowerShell 一键命令确实方便：

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

但从安全角度看，| iex 的含义是“下载后立即执行”。如果你是在公司电脑、生产环境或者安全要求较高的机器上操作，更稳妥的做法是先下载脚本，阅读确认后再执行。

例如：

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

这样至少知道脚本实际做了什么。

正常情况下，API Key 只会写入本机 WorkBuddy 的配置文件，不需要提交到 GitHub，也不应该发给别人。

API Key 创建方式参考：https://docs.crazyrouter.com/en/authentication?utm_source=csdn&utm_medium=article&utm_campaign=dev_community

9. 配置后 WorkBuddy 没看到模型，怎么排查？

如果脚本执行后，WorkBuddy 里没有看到 claude-opus-4-8 或 gpt-5.5，可以按下面顺序排查。

9.1 是否完全重启 WorkBuddy？

只关闭窗口不一定等于退出进程。建议从系统托盘或任务管理器确认 WorkBuddy 已完全退出，再重新打开。

9.2 models.json 是否写入成功？

检查文件：

notepad $env:USERPROFILE\.workbuddy\models.json

确认里面是否包含类似字段：

"id": "gpt-5.5"

或者：

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

9.3 URL 是否以 /v1 结尾？

应该是：

https://cn.crazyrouter.com/v1

不是：

https://cn.crazyrouter.com

9.4 Token 是否允许访问该模型？

如果 Token 设置了模型白名单，需要确认 claude-opus-4-8、gpt-5.5 等模型已经被加入允许列表。

如果不确定，可以临时取消模型限制测试一下。

9.5 Token 是否有额度限制？

有些调用失败不是账户余额不足，而是 Token 自己设置了额度限制，并且额度已经用完。

这时应该检查 Token 管理页面，而不是只看账户总余额。

10. 推荐配置方案

如果是个人开发者，可以先用一个 Token 配多个模型：

  • gpt-5.5：日常主力
  • claude-opus-4-8：复杂推理和长上下文
  • claude-sonnet-4-6：成本和效果平衡
  • gpt-5.4：轻量任务

如果是团队使用，建议拆成几个 Token：

开发者日常 Token

适合日常编码、Bug 修复、文档生成，允许中高频模型即可。

架构与长文档 Token

适合架构师、技术负责人或复杂项目分析，允许 claude-opus-4-8 这类高能力模型。

自动化脚本 Token

只开放自动化流程真正需要的模型，并设置较低额度，避免脚本异常导致持续调用。

11. 完整操作流程总结

最后把完整流程再压缩一下：

  1. 在 Crazyrouter 控制台准备 API Key；
  2. 打开 Windows PowerShell；
  3. 执行一键配置脚本；
  4. 输入 API Key；
  5. 等脚本写入 %USERPROFILE%\.workbuddy\models.json；
  6. 完全退出并重启 WorkBuddy；
  7. 在模型列表里选择自定义模型；
  8. 按任务类型选择 gpt-5.5、claude-opus-4-8 或其它模型。

命令如下：

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

如果想用环境变量传 Key：

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

总结

WorkBuddy 自定义模型配置的关键，不只是把几行 JSON 写进 models.json，而是把模型、Base URL、API Key、Token 权限、调用成本和团队管理方式一起考虑。

用 Crazyrouter 这类 OpenAI-compatible API，可以比较方便地把 claude-opus-4-8、gpt-5.5 等模型接入 WorkBuddy。再配合 PowerShell 脚本，就能自动完成模型写入、备份、去重和 /v1 规范化，减少手动配置带来的错误。

对个人开发者来说，这意味着可以更快用上新模型；对团队来说，则可以通过 Token 权限、模型白名单和额度限制，把 WorkBuddy 的模型使用变得更可控。

如果你正在用 WorkBuddy，又想接入更多 OpenAI-compatible 模型，可以从这个脚本开始试一下：

https://github.com/xujfcn/workbuddy-crazyrouter?utm_source=csdn&utm_medium=article&utm_campaign=dev_community

Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

MateClaw 2.0 正式发布：从“一个能干活的人”到“一支能协作的队伍”

avatar MCP技术社区

SkillDock：Skills 管理、MCP 管理与插件管理实践

以 SkillDock 为例，讲解 macOS 与 Windows 多工具环境下的 Skills 管理、MCP 管理、插件管理和 Git 变更处理实践。

avatar MCP技术社区
cover

MCP更新： 2026-07-28：从 Agent 插件协议到企业 AI 工具总线

avatar MCP技术社区