WorkBuddy 接入第三方中转站 API 教程

发布于 2026-08-19

这篇 WorkBuddy 第三方中转站 API 接入教程介绍 models.json、接口地址、模型 ID 与 API Key 配置，并覆盖 Windows/macOS 步骤和 401、404 排错。

WorkBuddy 接入第三方中转站 API，优先在最新版客户端的“+配置自定义模型”中完成；如果界面没有通用的 OpenAI 兼容入口，或需要一次配置多个模型，再编辑用户目录下的 ~/.workbuddy/models.json。真正决定能否调用成功的不是模型显示名称，而是中转站提供的完整接口地址、准确模型 ID、有效 API Key 和协议兼容性。

先说结论

完成 WorkBuddy 第三方 API 配置，需要同时满足这 6 项：

WorkBuddy 已升级到支持自定义模型的版本；腾讯云当前文档要求 v4.22.15。
中转站明确支持 OpenAI Chat Completions 兼容接口，而不只是“有 Claude、GPT 或 Gemini 模型”。
url 使用中转站提供的接口地址，常见形式是 https://api.example.com/v1/chat/completions。
id 与中转站模型列表中的模型 ID 完全一致。
availableModels 包含同一个 id，否则模型可能不会出现在 WorkBuddy 列表中。
保存后完全退出并重启 WorkBuddy，再用中转站控制台的调用记录验证请求是否到达。

如果还没选服务商，可先查看 OpenAI API 中转服务商对比或 AI API 服务商目录。不要仅凭“支持某模型”就购买额度，应先确认 WorkBuddy 所需的完整 URL、模型 ID、流式输出和工具调用是否可用。

WorkBuddy 支持哪种第三方 API 配置方式

当前应把官方图形界面和本地配置文件视为两条不同路径。腾讯云 2026 年 5 月更新的官方文档，展示的是 WorkBuddy 对话框底部的“+配置自定义模型”入口；多家中转站文档则提供了 models.json 配置方式。

配置方式	适合场景	主要风险
WorkBuddy 图形界面	当前版本已经显示目标供应商或 OpenAI 兼容选项	不同版本可选项可能不同
`models.json`	通用中转站、批量添加模型、需要精确填写 URL	JSON 格式、路径和字段映射容易写错

不要在只支持腾讯云 Token Plan 的表单里硬填第三方中转站 Key。若界面没有通用协议入口，应改用 models.json，而不是把供应商类型随便选成一个能保存的选项。

配置前需要准备什么

先从中转站控制台或接入文档确认以下信息：

信息	示例	怎么判断
API Key	`sk-your-api-key`	建议单独创建一把低额度 Key
Chat Completions URL	`https://api.example.com/v1/chat/completions`	以服务商 WorkBuddy 或 OpenAI 兼容文档为准
模型 ID	`provider-model-id`	必须使用控制台实际提供的 ID，不能自己翻译
输入/输出上限	`128000` / `8192`	不要填写高于服务商或上游支持的值
工具调用	支持或不支持	需要实际测试，不能只看模型名称
图片输入	支持或不支持	WorkBuddy 字段不能让上游凭空获得多模态能力

“OpenAI 兼容”只说明请求格式相近，不代表工具调用、图片输入、推理参数和流式响应全部兼容。WorkBuddy 是桌面智能体，能正常聊天只是最低门槛；如果需要操作电脑或调用工具，还要单独验证 tool call。

方法一：在 WorkBuddy 界面添加自定义模型

如果你的 WorkBuddy 已经提供通用自定义模型表单，优先用界面配置：

将 WorkBuddy 升级到当前最新版。
在对话界面底部打开模型切换入口。
点击“+配置自定义模型”。
选择中转站文档指定的供应商或 OpenAI 兼容类型。
填入 API Key、完整接口地址和模型 ID。
保存后切换到新模型，发起一次最小对话。
到中转站控制台查看调用记录、模型名和 token 用量。

不同 WorkBuddy 版本的表单字段可能变化。若界面只有腾讯云 Token Plan 等预设项，没有 Base URL 或通用协议字段，就继续使用下面的 models.json 方法。

方法二：编辑 models.json

WorkBuddy 的用户级自定义模型文件通常位于：

系统	配置文件路径
macOS / Linux	`~/.workbuddy/models.json`
Windows	`%USERPROFILE%\.workbuddy\models.json`

注意目录是 .workbuddy，不要误写成 .codebuddy。Windows 使用记事本保存时，还要确认文件没有变成 models.json.txt。

macOS / Linux 创建配置文件

先完全退出 WorkBuddy，再打开终端：

mkdir -p ~/.workbuddy
nano ~/.workbuddy/models.json

如果已有配置，修改前先备份：

cp ~/.workbuddy/models.json ~/.workbuddy/models.json.bak

Windows 创建配置文件

打开 PowerShell：

$workBuddyDir = Join-Path $env:USERPROFILE ".workbuddy"
New-Item -ItemType Directory -Force $workBuddyDir
$modelsFile = Join-Path $workBuddyDir "models.json"
if (Test-Path $modelsFile) { Copy-Item $modelsFile "$modelsFile.bak" }
notepad $modelsFile

通用 OpenAI 兼容配置模板

把下面示例中的 URL、API Key、模型 ID 和 token 上限替换为中转站提供的真实值：

{
  "models": [
    {
      "id": "provider-model-id",
      "name": "自定义显示名称",
      "vendor": "OpenAI",
      "url": "https://api.example.com/v1/chat/completions",
      "apiKey": "sk-your-api-key",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    }
  ],
  "availableModels": [
    "provider-model-id"
  ]
}

这段配置里最重要的是字段之间的对应关系：

字段	应该填什么	常见错误
`id`	中转站实际接受的模型 ID	填成营销名称或自行缩写
`name`	WorkBuddy 内显示的名称	与 `id` 混淆；此项可自定义
`vendor`	协议类型，通用 OpenAI 兼容示例使用 `OpenAI`	误以为必须等于真实模型厂商
`url`	服务商要求的请求地址	只填域名、漏掉 `/v1` 或 endpoint
`apiKey`	中转站签发的 Key	带入空格、换行或使用已停用 Key
`maxInputTokens`	服务商支持的最大输入长度	为追求长上下文而虚报数值
`maxOutputTokens`	服务商支持的最大输出长度	超过上游限制导致请求失败
`supportsToolCall`	是否向 WorkBuddy 声明工具调用能力	写 `true` 就误以为上游一定支持
`availableModels`	要显示的模型 ID 列表	没有包含 `models[].id`

vendor 更接近协议选择器，不等于模型的真实厂商。对于 OpenAI-compatible 接口，多家现行接入文档使用 OpenAI；如果你的中转站给了 WorkBuddy 专用模板，应保持其大小写和字段值，不要自行改成 Custom 或 openai。

URL 到底填 /v1 还是完整路径

对于当前常见的 models.json 配置，优先填写中转站明确给出的完整 Chat Completions 地址，例如：

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

但不同 WorkBuddy 版本和服务商模板可能采用 Base URL，由客户端继续拼接 endpoint。判断规则如下：

服务商给出的内容	`url` 怎么填
明确给出 WorkBuddy 专用完整地址	原样填写，包括 `/v1/chat/completions`
只给出 OpenAI Base URL，例如 `/v1`	先确认其 WorkBuddy 文档是否要求补 `/chat/completions`
NewAPI 类接口只写了域名	通常需要补成 `/v1/chat/completions`，再以服务商文档为准
返回 404 且控制台没有有效调用记录	优先检查域名、`/v1` 和 endpoint 是否完整

不要机械地给所有地址补 /v1，也不要机械地删掉 /chat/completions。参考文章中同时存在 Base URL 和完整 endpoint 两种写法，说明它们不是可跨服务商照抄的统一标准。社区案例里，NewAPI 地址缺少 /v1 会导致 WorkBuddy 模型已经显示，但对话仍报错。

如何同时添加多个模型

在 models 数组里继续添加模型对象，并把每个 id 同步写入 availableModels：

{
  "models": [
    {
      "id": "provider-model-a",
      "name": "模型 A",
      "vendor": "OpenAI",
      "url": "https://api.example.com/v1/chat/completions",
      "apiKey": "sk-your-api-key",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true
    },
    {
      "id": "provider-model-b",
      "name": "模型 B",
      "vendor": "OpenAI",
      "url": "https://api.example.com/v1/chat/completions",
      "apiKey": "sk-your-api-key",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": false
    }
  ],
  "availableModels": [
    "provider-model-a",
    "provider-model-b"
  ]
}

同一个 id 不要重复添加。多个中转站也可以共存，但建议在 name 中标注服务商，避免切换时选错；id 仍须保持上游要求的真实模型名。

保存后如何验证 WorkBuddy 已接入中转站

验证应从配置文件到中转站逐层进行，不要只问模型“你是谁”。模型可能根据提示词回答一个不准确的身份，不能证明请求实际走了哪个上游。

在本地检查 JSON 语法，不要把带 API Key 的文件上传到在线格式化网站。
确认 availableModels 中的每个值都能在 models[].id 中找到。
完全退出 WorkBuddy，包括仍在后台运行的进程，然后重新打开。
在模型列表中确认自定义模型出现。
发送一句简短测试消息，先验证基础文本响应。
在中转站控制台核对调用时间、请求模型、token 用量和状态码。
再测试一次需要工具调用的任务，确认不只是普通聊天可用。

macOS / Linux 如果本机已安装 Node.js，可以在本地检查 JSON：

node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")); console.log("JSON OK")' ~/.workbuddy/models.json

Windows PowerShell 可以这样检查：

Get-Content "$env:USERPROFILE\.workbuddy\models.json" -Raw |
  ConvertFrom-Json |
  Out-Null

命令没有报 JSON 解析错误，只能说明文件格式正确，不代表 URL、Key 或模型权限正确。

常见错误与排查顺序

现象	最可能原因	先怎么处理
模型列表里看不到自定义模型	路径错误、JSON 无效、`availableModels` 漏写、应用未完全重启	先检查文件路径和 ID 映射
模型出现但对话报错	URL、协议或模型能力不兼容	检查完整 endpoint 和中转站调用记录
401 / unauthorized	API Key 错误、已失效、带空格或鉴权格式不兼容	换一把专用 Key，并查看 API 401 排查
404 / not found	漏了 `/v1`、缺少 `/chat/completions` 或请求打到面板域名	对照服务商 WorkBuddy/OpenAI 文档逐段核对 URL
model not found	`id` 不是服务商实际模型名，或账号无该模型权限	从控制台复制模型 ID，不要猜名称
429 / too many requests	余额不足、套餐限流或上游拥堵	查看用量与限额，并参考 API 429 排查
能聊天但工具调用失败	中转站只兼容基础补全，未完整转发 tool call	将 `supportsToolCall` 改为 `false`，或更换明确支持 WorkBuddy 的接口
输出过短或被截断	`maxOutputTokens` 太低，或服务商限制低于配置值	按服务商上限调整，不要盲目填大
`AGENT_CRAFT_CORE_FINISH_REASON_ERROR`	WorkBuddy 的汇总错误，不能单凭错误名定位	先看中转站是否收到请求，再查 URL、模型 ID 和工具调用