起因：工具顺手，模型想自己选
WorkBuddy 的工作流用着顺手，但有些任务想换个模型试试：长文档处理想用上下文更长的，日常小活想用响应更快的，写代码想用代码能力更强的。自带模型之外，它支持添加自定义模型——这篇把接入一个聚合网关的完整过程记录下来。接好之后，在 WorkBuddy 里就能从精选的约 20 个主力模型里按任务挑着用——这批是给编程工具精选的，覆盖 9 家厂商；官网网页聊天那边可选的更全（50+），但干活真正用得上的就是这批。接好后和我其他几个编程工具共用同一把 Key、同一份账单。
准备工作
- 注册 Kovelo 账号，在官网的
/keys页面创建一把 API Key（形如kovelo-xxx）并保存好。新注册账号有一笔 $1 体验额度，够把下面流程验证一遍。 - **这把 Key 不要锁定模型。 **锁定后这把 Key 只能走被锁定的那一个模型；用不锁定的 Key，下面添加的每个模型才能各走各的。
- 本地装好 WorkBuddy 并能正常打开。已经装好的跳过这步。
步骤一：GUI 添加单个模型（推荐先这样跑通）
打开 WorkBuddy，依次进入：设置 → 模型 → 点「+ 添加模型」。在添加界面里逐项填：
- 提供商：选「自定义 / Custom」。
- 接口地址：填下面这一条，必须带完整的
/chat/completions后缀，少了后缀请求到不了对话接口：
https://kovelo.ai/api/v1/chat/completions
- API Key：填准备工作中创建的那把 Key。
- 模型名称：填想用的模型 id，逐字照官网模型清单复制，不要自己改写。
然后展开高级配置，这里有两个关键勾选：
- 必须勾选「工具调用」。不勾的话，联网搜索、本地文件、终端这些能力都用不了——WorkBuddy 的工作流大半靠工具调用撑着，这项漏了等于白接。
- 如果添加的是视觉模型，再勾上「图片输入」；纯文本模型不用勾。
保存后回到对话界面，在模型选择处切到刚添加的模型，给它一个小任务验证链路：让它读一个本地文件、或联网搜一个关键词。能正常调用工具并返回结果，就说明接通了。整个添加过程就是填四项、勾两项，单个模型半分钟左右配完；不过逐个加满约 20 个也要十分钟上下，想一次到位的直接看步骤二。
步骤二（进阶）：编辑 models.json 批量配置
要一次配多个模型，逐个在 GUI 里添加比较慢，可以直接改配置文件。文件位置：
- macOS / Linux：
~/.workbuddy/models.json - Windows：
C:\Users<用户名>.workbuddy\models.json
下面是我自己 WorkBuddy 里在用的完整配置（精选 19 个模型、覆盖 9 家厂商），把每一项的 apiKey 换成你自己的 Key、粘贴进 models.json，保存后重启 WorkBuddy 生效——整个过程 3–5 分钟，约 20 个模型一次配齐：
{
"models": [
{
"id": "Claude Fable 5.1 · Kovelo",
"name": "Claude Fable 5.1 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "Claude Opus 5.5 · Kovelo",
"name": "Claude Opus 5.5 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 100000
},
{
"id": "Claude Sonnet 5.5 · Kovelo",
"name": "Claude Sonnet 5.5 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "Claude Haiku 5.5 · Kovelo",
"name": "Claude Haiku 5.5 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high",
"xhigh"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 128000
},
{
"id": "OpenAI GPT 6 Astra · Kovelo",
"name": "OpenAI GPT 6 Astra · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"maxInputTokens": 1050000,
"maxOutputTokens": 100000
},
{
"id": "OpenAI GPT 6.1 Sol · Kovelo",
"name": "OpenAI GPT 6.1 Sol · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"maxInputTokens": 1050000,
"maxOutputTokens": 100000
},
{
"id": "OpenAI GPT 6 Luna · Kovelo",
"name": "OpenAI GPT 6 Luna · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"low",
"medium",
"high",
"xhigh",
"max"
]
},
"maxInputTokens": 1050000,
"maxOutputTokens": 60000
},
{
"id": "OpenAI GPT-5.5 · Kovelo",
"name": "OpenAI GPT-5.5 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high",
"xhigh"
]
},
"maxInputTokens": 1050000,
"maxOutputTokens": 60000
},
{
"id": "Google Gemini 3.1 Pro · Kovelo",
"name": "Google Gemini 3.1 Pro · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high",
"xhigh"
]
},
"maxInputTokens": 1048576,
"maxOutputTokens": 30000
},
{
"id": "Google Gemini 3.8 Flash · Kovelo",
"name": "Google Gemini 3.8 Flash · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high",
"xhigh"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 60000
},
{
"id": "xAI Grok 4.7 · Kovelo",
"name": "xAI Grok 4.7 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"high",
"xhigh",
"max",
"medium"
]
},
"maxInputTokens": 500000,
"maxOutputTokens": 50000
},
{
"id": "xAI Grok build 0.1 · Kovelo",
"name": "xAI Grok build 0.1 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high"
]
},
"maxInputTokens": 500000,
"maxOutputTokens": 32768
},
{
"id": "DeepSeek V4 Pro · Kovelo",
"name": "DeepSeek V4 Pro · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"high",
"xhigh",
"max"
]
},
"maxInputTokens": 1048565,
"maxOutputTokens": 100000
},
{
"id": "DeepSeek V4.1 Flash · Kovelo",
"name": "DeepSeek V4.1 Flash · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 100000
},
{
"id": "Qwen 3.8 Max · Kovelo",
"name": "Qwen 3.8 Max · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high"
]
},
"maxInputTokens": 990000,
"maxOutputTokens": 50000
},
{
"id": "zAI GLM 5.3 · Kovelo",
"name": "zAI GLM 5.3 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 32768
},
{
"id": "Kimi K3 · Kovelo",
"name": "Kimi K3 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 30000
},
{
"id": "Kimi K2.7 Code · Kovelo",
"name": "Kimi K2.7 Code · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high"
]
},
"maxInputTokens": 262144,
"maxOutputTokens": 32768
},
{
"id": "MiniMax-M3 · Kovelo",
"name": "MiniMax-M3 · Kovelo",
"vendor": "Custom",
"url": "https://kovelo.ai/api/v1/chat/completions",
"apiKey": "",
"supportsToolCall": true,
"supportsImages": true,
"supportsReasoning": true,
"useCustomProtocol": false,
"reasoning": {
"supportedEfforts": [
"medium",
"high"
]
},
"maxInputTokens": 1000000,
"maxOutputTokens": 32768
}
]
}
两个提醒：
- 不要拿官网的 JSON 整份覆盖你现有的文件，否则会丢掉你已经填好的 Key。需要更新清单时用下面的官方更新流程。
- 文件里存的是明文 Key，不要把这个文件提交到 Git 仓库或随手发人；万一泄露，在官网的
/keys页面作废重建即可。
平台增减模型后：用官方脚本更新清单（保留已有 Key，仅 macOS）
平台增减模型后，清单要跟着更新。官方给了一个"只换清单、不动 Key"的更新流程（以下命令与脚本为官方文档原文）：
第 1 步：把下面这条命令粘贴到终端并按回车，它会提示你去复制；然后回到开发者页，点 WorkBuddy 一节 JSON 代码块右上角的复制按钮，再回到终端按一次回车，模型清单就保存好了。
echo "请切换到浏览器，点开发者页本章 JSON 代码块的 Copy 按钮，复制好后回到这里按回车"; read x; pbpaste > ~/kovelo-new.json
第 2 步：运行下面这段脚本。它从你现在的文件里取出 Key，填进新的模型列表，写入前自动备份，并保持原来的文件格式。Key 不会显示在屏幕上。如果提示 Key 有多种，说明你给不同模型填了不同的 Key，请先统一成一把再运行。
node -e '
const fs=require("fs"),os=require("os");
const p=os.homedir()+"/.workbuddy/models.json";
const neu=JSON.parse(fs.readFileSync(os.homedir()+"/kovelo-new.json","utf8"));
const list=Array.isArray(neu)?neu:neu.models;
const old=JSON.parse(fs.readFileSync(p,"utf8"));
const oldList=Array.isArray(old)?old:old.models;
const keys=[...new Set(oldList.map(m=>m.apiKey).filter(Boolean))];
if(keys.length!==1){console.log("现有文件里的 Key 有 "+keys.length+" 种，未做任何修改");process.exit(1)}
for(const m of list){m.apiKey=keys[0]}
fs.copyFileSync(p,p+".bak-"+Date.now());
fs.writeFileSync(p,JSON.stringify(Array.isArray(old)?list:{models:list},null,2));
console.log("已写入 "+list.length+" 个模型");
'
Windows 用户注意：官方文档明确说，这一节还没有 Windows 版步骤，不要自己拼命令；可以手动把新列表里每一项的 apiKey 改成自己的 Key，或者干脆用步骤一的 GUI 逐个添加。
验证：实际用了哪个模型，看用量日志
配好之后想确认请求到底跑在哪个模型上，不要问模型"你是谁"——模型自报身份不可靠。去 Kovelo 后台的用量日志看模型名一栏，那里记的是真实模型。步骤一里让它读文件、联网搜索的那次验证调用，也会在日志里留下一条，正好对一眼。
顺带一提，同一把 Key 也可以在网页端和 Claude Code、Codex、Cursor 里通用，用量合并统计在一份账单里（后台明细按输入、缓存读取、缓存写入、输出四项分开列）。WorkBuddy 这边接好，等于几个工具的模型池一起打通了。
FAQ
Q：需要海外信用卡或海外手机号吗？
不需要。支持微信和支付宝付款，也不用注册维护多个海外平台账号，注册拿到 Key 就能按上面的步骤配置。
Q：高级配置里的「工具调用」忘了勾，会怎样？
模型能对话，但联网搜索、本地文件、终端都用不了。回设置里把该模型的「工具调用」勾上再用；视觉模型还要多勾「图片输入」。
Q：我常用的模型下线了会怎样？
请求不会报错，仍写着旧模型名的请求会自动改由平台指定的接班模型回答，用量日志里能看到实际用的模型名；但建议按上面的更新流程把清单换新、改选新模型。
Q：改完 models.json 没生效？
先确认文件存对了位置，再重启 WorkBuddy——配置是启动时读的，不重启不生效。
Q：都能用哪些模型？
给编程工具精选了约 20 个主力模型，覆盖 Anthropic、OpenAI、Google、xAI、DeepSeek、阿里通义、Kimi、MiniMax、智谱 9 家厂商，文中 models.json 里就是完整清单；官网网页聊天那边可选的更全（50+）。添加时把模型 id 逐字照官网模型清单填即可。
结尾
一句话总结：使用习惯不用改，在设置里加一个自定义模型、接口地址带全后缀、工具调用勾上，WorkBuddy 就能按任务在约 20 个精选主力模型之间换着用。想试的话搜一下 Kovelo 就能找到官网，注册免费、新账号有 $1 体验额度，完整模型清单也在上面。
