Tencent WorkBuddy 当前提供可视化的自定义模型配置。按照下面的顺序添加 青云TOP API，不需要手工修改官方账号 Provider。字段与行为以 WorkBuddy 官方 Model Configuration 文档为准。

第一步：安装并登录 WorkBuddy

  1. 打开 Tencent WorkBuddy 官方安装说明。
  2. 下载与你系统和处理器架构匹配的版本。
  3. 完成安装并启动 WorkBuddy。
  4. 使用 WorkBuddy 支持的登录方式进入主界面。

macOS 需要 12 或更高版本。首次启动可能请求文件、辅助功能或通知权限；只为你准备使用的功能授权，自定义模型配置本身不要求把所有权限一次性打开。

第二步：创建 WorkBuddy 专用 API 密钥

  1. 登录 青云TOP API 控制台。
  2. 打开“令牌管理”，新建一个只供 WorkBuddy 使用的令牌。
  3. 选择需要使用的模型分组。
  4. 复制令牌并妥善保存；截图前保持密码框掩码。

第三步：确认模型 ID

使用同一个令牌请求模型列表：

export QINGYUN_TOP_API_KEY="你的 青云TOP API API 密钥"

curl "https://top.qingyuntop.ai/v1/models" \
  -H "Authorization: Bearer $QINGYUN_TOP_API_KEY"

从返回结果中复制准确的模型 ID。下文用 gpt-4o-mini 举例；如果你的令牌分组没有该模型，请替换成实际返回的 ID。

第四步：打开自定义模型页面

在 WorkBuddy 中依次打开：

Settings → Model → Add Model

在 Provider 列表中选择 Custom。不要修改 WorkBuddy 内置 Provider，也不要选择只允许填写官方密钥、不能修改 URL 的预设。

第五步：填写 青云TOP API 配置

在新增模型对话框中填写：

  • Provider：Custom
  • Model name：gpt-4o-mini
  • URL：https://top.qingyuntop.ai/v1
  • API Key：青云TOP API 专用令牌

亚太地区可将 URL 改为：

https://top.qingyuntop.ai/v1

WorkBuddy 官方说明中，Custom Protocol 关闭时会按标准 OpenAI Chat Completions 规则校验并补全接口路径；打开后会把请求直接发送到填写的完整 URL。青云TOP API 的常规 OpenAI-compatible 配置应保持关闭，并填写到 /v1，不要手工追加 /chat/completions。

第六步：设置模型能力

首次保存时，只启用已经确认的能力：

  • 普通文本对话：启用。
  • Tool calling：只有模型和令牌分组已实际通过工具调用后才启用。
  • Image input：只有模型已实际通过图片输入后才启用。
  • Reasoning：只有模型协议和响应格式已确认兼容后才启用。

不要根据模型名称猜测能力。错误的能力开关会让 WorkBuddy 发送不受支持的请求结构。

第七步：保存并选择 青云TOP API 模型

  1. 点击 Save。
  2. 返回聊天页，打开模型选择器。
  3. 找到自定义模型分组。
  4. 选择刚添加的 gpt-4o-mini。
  5. 确认当前会话顶部显示该模型后，再发送消息。

第八步：发送第一条消息

先发送不包含文件或工具的短消息：

只回复 WORKBUDDY_青云TOP API_OK，不要添加其他内容。

必须同时满足以下条件，才能认定接入完成：

  1. WorkBuddy 会话出现模型正文回复；
  2. 青云TOP API 控制台出现同一时间的请求记录；
  3. 请求记录中的模型 ID 与 WorkBuddy 当前选择一致。

普通消息成功后，再逐项启用项目扫描、文件访问、工具调用和自动执行。

常见问题

  • 没有 Custom 选项：更新到支持自定义模型的 WorkBuddy 版本；不要修改官方账号配置绕过入口。
  • 提示 401：重新粘贴专用令牌，确认没有复制空格或已停用的旧令牌。
  • 提示 404：URL 使用 https://top.qingyuntop.ai/v1，并保持 Custom Protocol 关闭；不要重复追加接口路径。
  • 提示模型不存在：重新请求 /v1/models，复制令牌分组实际可见的模型 ID。
  • 保存后模型不在选择器中：返回 Settings → Model，确认自定义模型仍在列表中且已经保存。
  • 普通对话成功但工具失败：关闭能力开关，从纯文本开始逐项验证，不要把基础接入与工具兼容性混在一起排查。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。