WorkBuddy 怎么接自定义模型？添加 Claude、GPT、DeepSeek 等第三方 API 的完整教程（2026）
本页目录
一句话说清：WorkBuddy 是腾讯出的办公 AI 智能体桌面应用，可以接你自己的模型。入口：头像 → 设置 → 模型 → 添加模型，服务商选「自定义」，填接口地址、API Key、模型名，再在高级配置里打开「工具调用」。以 api.foo 为例，接口地址填 https://api.foo/v1。
本文依据 WorkBuddy 官方文档（国际版 5.9.4 时）和腾讯云的说明整理，接口部分用测试密钥实测过。我们没有在电脑上实际安装 WorkBuddy，界面以你看到的为准。
WorkBuddy 是什么
WorkBuddy 是腾讯云代码助手（CodeBuddy）团队推出的 AI 智能体，你用一句话描述任务，它自己规划步骤，调用工具读写文件、做表格、写报告、做 PPT。有国内版（workbuddy.cn）和国际版（workbuddy.ai）两个版本，分开运营。
它自带内置模型，按积分计费。想用别家的模型，或者用自己已经在付费的 API，就要「添加自定义模型」。
添加前要准备好
| 要准备的 | 说明 |
|---|---|
| 接口地址 | 服务商的 OpenAI 兼容地址，一般到 /v1 为止，比如 https://api.foo/v1 |
| API Key | 服务商给你的密钥 |
| 模型名 | 接口认的模型 ID，必须一字不差（含大小写），不是你自己起的显示名 |
两条硬要求：
- 只支持 OpenAI 兼容的 Chat Completions 接口。官方文档原话的意思是：自定义模型目前用 OpenAI 兼容的 Chat Completions 接口接入。Claude 原生的 Messages 接口、Gemini 原生接口都填不进去。
- 模型要会调用工具。WorkBuddy 是干活的智能体，读文件、做表格都靠工具调用。只会聊天、不支持工具调用的模型，能回话但做不了任务。
在 api.foo 上，密钥按分组创建：要用哪个模型，就把密钥建在有这个模型的分组里。每个模型能在哪些分组用，打开模型广场里这个模型的页面就能看到。
添加自定义模型：一步一步
-
打开 WorkBuddy，点左下角头像 → 设置 → 模型（国际版叫「系统设置」），进入模型设置页。
-
点「添加模型」，服务商选「自定义」。
-
填三项：
字段 以 api.foo 为例 接口地址 https://api.foo/v1API Key 你在 api.foo 控制台「API 密钥」里建的密钥 模型名 从模型广场复制，比如 claude-sonnet-5-5、gpt-6.1-sol、deepseek-v4-pro、kimi-k3、glm-5.3 -
展开高级配置，按模型的真实能力勾选（下一节细讲）。最少要打开「工具调用」。
-
点「测试连接」。通了再保存。
-
回到对话，在输入框的模型选择器里手动选这个模型。
一个模型添加一次。想同时用 Claude 和 GPT，就添加两条，各自填模型名。
Auto 模式不保证用你添加的模型。官方文档说明，Auto 按 WorkBuddy 自己的规则分配模型。要用自己的模型，在对话里手动选。
「测试连接」会真的调一次接口，可能产生一点费用。官方也提醒：测试成功只说明接口能回话，不等于看图、工具调用、长输入都没问题，要另外用一个简单任务试。
接口地址怎么填：「自定义协议」开关
高级配置里有个「自定义协议」开关，决定 WorkBuddy 怎么处理你填的地址：
| 开关 | WorkBuddy 怎么做 | 该怎么填 |
|---|---|---|
| 关（默认） | 把地址整理成以 /chat/completions 结尾，不会帮你补 /v1 |
https://api.foo/v1 或 https://api.foo/v1/chat/completions 都行 |
| 开 | 你填什么就用什么，不补任何路径 | 必须填完整的 https://api.foo/v1/chat/completions |
绝大多数情况保持关闭，只有服务商的路径不是标准写法时才打开。这个开关只改地址怎么拼，不会把别的接口格式转成 OpenAI 格式。
我们用测试密钥（sk-thisisafakekeyfortesting）核对过 api.foo 的几种写法：
| 实际请求的地址 | 结果 |
|---|---|
https://api.foo/v1/chat/completions |
401「无效的令牌」——地址对了，只是测试密钥不能用 |
https://api.foo/chat/completions（漏了 /v1） |
同上，api.foo 会自动补上 /v1 |
https://api.foo/v1/chat/completions/chat/completions（路径重复） |
404 Invalid URL |
换成你自己的密钥，返回「无效的令牌」的地方就会正常回答。
高级配置：能力怎么勾
官方的原则是：按模型和接口真实支持的能力填，不要全部打开。勾了模型不支持的能力，调用可能直接报错。
| 选项 | 什么意思 | 建议 |
|---|---|---|
| 工具调用 | 模型能按格式调用工具，是执行任务的前提 | 要打开。Claude、GPT、Gemini、DeepSeek、Kimi、GLM 等主流对话模型都支持 |
| 图片输入 | 模型能看图（截图分析、看图表） | 模型能看图才开。能看图 ≠ 能生图 |
| 推理模式 | 模型的思考 / 推理开关 | 按模型支持情况开；不确定先关，能用了再试 |
| 思考强度 | 推理的档位 | 只有模型和接口都支持时才填，填了不认的档位会报错 |
| 最大输入 / 输出 tokens | 上下文和单次输出的上限 | 留空用默认值即可。填大了不会让模型真的变大 |
用 Claude 要知道的一件事：缓存
WorkBuddy 只能用 OpenAI 兼容格式，所以 Claude 也走这个格式。这有一个费用上的差别：
- Claude 的提示词缓存要客户端主动打标记（
cache_control）。在 Claude Code 这类原生客户端里会自动打，长任务反复发送的上下文按便宜很多的缓存价计费。 - 走 OpenAI 兼容格式时，标记由客户端决定带不带。我们没法确认 WorkBuddy 会不会带。不带的话，每一轮都按完整输入价计费，长任务的费用会明显高。
- GPT、DeepSeek 这类模型由服务商自动缓存，不需要客户端打标记，用 OpenAI 兼容格式接没有这个差别。
建议：先用一个任务试，到 api.foo 控制台「使用日志」点开那条记录，看有没有缓存读取。缓存几乎为零、用量又大时，考虑在 WorkBuddy 里换 GPT、DeepSeek 等模型，或者把重度的编程任务放到 Claude Code 里做。
常见报错
| 现象 | 常见原因 | 怎么办 |
|---|---|---|
| 401、无效的令牌 | 密钥复制漏了、多了空格，或者把别家的密钥填进来了 | 重新复制密钥；在 api.foo 控制台看这把密钥是否启用、额度是否用完 |
| 404 | 地址路径重复（打开了「自定义协议」又只填了 /v1，或者手动拼成了 /v1/chat/completions/chat/completions） |
关掉「自定义协议」，地址填 https://api.foo/v1 |
| 返回一个网页，或者提示格式不对 | 地址填成了控制台、模型广场这样的网页地址 | 地址只填 https://api.foo/v1 |
| 无可用渠道、模型价格未配置 | 模型名和模型广场的写法不一致（含大小写），或者这把密钥的分组里没有这个模型 | 从模型页复制模型名；换一把建在对的分组里的密钥 |
| 测试连接通了，任务一执行就失败 | 没打开「工具调用」，或者模型不支持工具调用；也可能是勾了模型不支持的能力 | 打开工具调用、换支持工具调用的对话模型；把不确定的能力先关掉 |
| 对话里还是用的内置模型 | 开着 Auto，或者没在模型选择器里选 | 在对话的模型选择器里手动选你添加的模型 |
更多报错原文和排查步骤见 报错排查大全。
配置存在哪里
添加的模型和 API Key 保存在你电脑上的 models.json 里，不会上传：
| 版本 | 位置 |
|---|---|
| 国际版（macOS） | ~/.workbuddy-ai/models.json |
| 国际版（Windows） | %USERPROFILE%\.workbuddy-ai\models.json |
| 国内版 | 用户目录的 .workbuddy 文件夹里；更早用 CodeBuddy 配过的 ~/.codebuddy/models.json，升级后照样能用 |
实际位置以模型设置页上显示的为准。日常增删改在界面里做就行，不用手动改文件。这个文件里有密钥，不要发给别人，也不要传到公开的代码仓库。
相关阅读
常见问题
WorkBuddy 能接第三方 API 吗？
能。在头像 → 设置 → 模型里添加模型，服务商选「自定义」，填接口地址、API Key 和模型名就行。官方文档写明自定义模型目前只支持 OpenAI 兼容的 Chat Completions 接口，所以服务商要提供这种接口。
WorkBuddy 的接口地址要不要带 /v1？
要带。「自定义协议」开关关着（默认）时，WorkBuddy 会把地址补成以 /chat/completions 结尾，但不会帮你补 /v1。所以填到 /v1 为止，或者直接填完整的 /v1/chat/completions，两种都行，比如 https://api.foo/v1。
WorkBuddy 能用 Claude 吗？
能，但只能按 OpenAI 兼容格式接，不能用 Claude 原生的 Messages 接口。服务商要支持用 OpenAI 格式调用 Claude。长任务要留意：Claude 的提示词缓存要客户端主动打标记，走 OpenAI 格式时不一定能命中，费用可能比在 Claude Code 里用高。
为什么开了 Auto，没有用我添加的模型？
官方文档说明，Auto 模式按 WorkBuddy 自己的规则分配模型，不保证会用到你添加的自定义模型。要用自己的模型，在对话框的模型选择器里手动选它。
「测试连接」成功了，任务还是失败，是怎么回事？
测试连接只检查接口能不能回话，不检查工具调用、看图、长输入这些能力。WorkBuddy 干活要靠工具调用：在高级配置里打开「工具调用」，并选一个支持工具调用的模型，再用一个简单任务试一下。
添加的模型和 API Key 存在哪里？
存在你自己电脑上的 models.json 里，不上传。国际版在用户目录的 .workbuddy-ai 文件夹（Windows 是 %USERPROFILE%\.workbuddy-ai\models.json），国内版在 .workbuddy 文件夹；以模型设置页上显示的路径为准。这个文件里有密钥，不要发给别人或传到公开仓库。
发现内容有误？发邮件到 [email protected] 告诉我们。