WorkBuddy 配置第三方大模型 api 教程

如果你想在腾讯 WorkBuddy 里使用自己的模型入口，这篇 WorkBuddy 配置第三方大模型 api 教程 可以直接照着做。核心思路很简单：在本机用户目录创建 models.json，把第三方 OpenAI-compatible API 的 url、apiKey、模型 id 写进去，重启 WorkBuddy 后选择对应模型。

按腾讯云官方文档，WorkBuddy 支持通过本地配置文件接入自定义模型，官方示例位置是 ~/.workbuddy/models.json，并通过 models 和 availableModels 两段配置控制可用模型[^1]。如果你想把 Claude、GPT、Gemini 或其他大模型放到同一套入口里，可以优先使用 api.clawsocket.com，再通过 ai-api-proxy.com 查看更多工具接入教程。

WorkBuddy 配置第三方大模型 api 的关键，不是改客户端源码，而是把 models.json 里的 url、apiKey、id 和 availableModels 写对。

快速结论

• WorkBuddy 配置第三方大模型 api 教程 的核心文件是 models.json
• macOS 推荐路径是 ~/.workbuddy/models.json
• Windows 推荐路径是 %USERPROFILE%\.workbuddy\models.json
• 第三方 OpenAI-compatible 接口通常要把 url 写成完整的 /v1/chat/completions
• ClawSocket 的常用接口地址是 https://api.clawsocket.com/v1/chat/completions
• 改完配置后必须完全重启 WorkBuddy，否则新模型可能不会出现

一、WorkBuddy 第三方模型配置原理

很多人以为 WorkBuddy 配置模型要在设置页里找 Base URL，其实目前公开文档给出的方式是本地配置文件。你要做的是在本机创建一个 models.json，里面写入模型数组。WorkBuddy 启动时读取这个文件，再把 availableModels 里的模型显示到可选列表。

最小结构大概是这样：

{
  "models": [
    {
      "id": "模型名",
      "name": "显示名称",
      "vendor": "OpenAI",
      "url": "接口地址",
      "apiKey": "你的 API Key",
      "maxInputTokens": 100000,
      "maxOutputTokens": 4096
    }
  ],
  "availableModels": [
    "模型名"
  ]
}

这里最容易搞错的是 id 和 availableModels。id 是实际请求时使用的模型标识，availableModels 里必须包含同一个 id，否则你写了模型对象，WorkBuddy 也不一定会显示出来。

二、macOS 怎么配置 WorkBuddy 第三方大模型 api

macOS 用户可以直接按官方文档的路径来做。先打开终端，创建目录：

mkdir -p ~/.workbuddy

然后打开配置文件：

code ~/.workbuddy/models.json

如果你没有 VS Code，也可以用系统自带编辑器：

nano ~/.workbuddy/models.json

接下来把本文后面的 JSON 示例粘进去，替换成你自己的 ClawSocket API Key，保存文件，最后完全退出并重启 WorkBuddy。

三、Windows 怎么配置 WorkBuddy 第三方大模型 api

Windows 也可以按同样思路处理，只是用户目录写法不同。打开 PowerShell，先创建目录：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.workbuddy"

然后用记事本打开配置文件：

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

如果你更习惯命令行，也可以用 VS Code：

code "$env:USERPROFILE\.workbuddy\models.json"

保存后重启 WorkBuddy。这里有一个细节：如果你重启后仍然看不到模型，先确认 WorkBuddy 已更新到支持本地 models.json 的版本，再检查路径是否真的是当前 Windows 用户目录下的 .workbuddy 文件夹。

WorkBuddy 配置第三方大模型 api 的流程：创建 models.json、写入模型、确认 availableModels、重启应用、实际对话验证。

四、用 ClawSocket 配置 WorkBuddy 的完整 JSON

下面是一个可以直接改的 ClawSocket 示例。这个配置适合把 WorkBuddy 接到 api.clawsocket.com 这类 OpenAI-compatible 入口。

{
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "name": "Claude Sonnet - ClawSocket",
      "vendor": "OpenAI",
      "url": "https://api.clawsocket.com/v1/chat/completions",
      "apiKey": "你的-ClawSocket-API-Key",
      "maxInputTokens": 200000,
      "maxOutputTokens": 8192
    }
  ],
  "availableModels": [
    "claude-sonnet-4-20250514"
  ]
}

这段 WorkBuddy 配置第三方大模型 api 教程 示例里，最重要的是 4 个字段：

字段	作用	建议
id	实际模型名	以 ClawSocket 后台可用模型为准
name	WorkBuddy 里显示的名称	写清楚模型和入口，方便区分
vendor	供应商类型	OpenAI-compatible 入口一般写 OpenAI
url	请求地址	写完整的 https://api.clawsocket.com/v1/chat/completions

如果你的模型名不是 claude-sonnet-4-20250514，不要硬抄。进入 api.clawsocket.com 后台确认当前可用模型名，再把 id 和 availableModels 同时改掉。

五、同时配置多个第三方模型

WorkBuddy 可以一次写多个模型。比如你想同时放 Claude 和 GPT，可以这样写：

{
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "name": "Claude Sonnet - ClawSocket",
      "vendor": "OpenAI",
      "url": "https://api.clawsocket.com/v1/chat/completions",
      "apiKey": "你的-ClawSocket-API-Key",
      "maxInputTokens": 200000,
      "maxOutputTokens": 8192
    },
    {
      "id": "gpt-5.4",
      "name": "GPT-5.4 - ClawSocket",
      "vendor": "OpenAI",
      "url": "https://api.clawsocket.com/v1/chat/completions",
      "apiKey": "你的-ClawSocket-API-Key",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192
    }
  ],
  "availableModels": [
    "claude-sonnet-4-20250514",
    "gpt-5.4"
  ]
}

这也是 WorkBuddy 接第三方大模型最适合团队使用的地方：一个文件里可以把多个模型收口到同一套入口，后续换模型时不用重新理解每个供应商的接口差异。

六、配置后怎么验证是否生效

完成 models.json 后，按这个顺序检查：

1. 确认 JSON 没有多余逗号，可以用编辑器格式化一下
2. 确认 availableModels 里的每一项都能在 models.id 里找到
3. 确认 url 是完整的聊天补全接口，不是只写域名
4. 确认 API Key 没有复制空格或换行
5. 完全退出 WorkBuddy，再重新打开
6. 在 WorkBuddy 模型选择处确认新模型是否出现
7. 发一条短消息测试返回

如果你想排查第三方 API 本身是否可用，可以先用同一个 Key 在普通脚本里请求 api.clawsocket.com。如果脚本能返回，但 WorkBuddy 不显示模型，问题通常在 models.json 的路径或 JSON 结构。

七、Windows 和 macOS 配置差异

这篇 WorkBuddy 配置第三方大模型 api 教程 同时覆盖 Windows 和 macOS，但两边真正不同的地方只有路径和编辑器命令。

平台	配置目录	配置文件	常见问题
macOS	~/.workbuddy	~/.workbuddy/models.json	终端权限、文件没保存、应用没重启
Windows	%USERPROFILE%\.workbuddy	%USERPROFILE%\.workbuddy\models.json	文件后缀变成 .txt、目录建错用户、旧进程没退出

如果你在 Windows 上用记事本编辑，保存时要确认文件名不是 models.json.txt。如果你在 macOS 上用 nano，编辑完以后用 Ctrl + O 保存，再用 Ctrl + X 退出。无论哪个平台，最后都建议完全退出 WorkBuddy 再重新打开，不要只关闭窗口。

另外，WorkBuddy 配置第三方大模型 api 教程 里最容易忽略的一点是版本。腾讯云文档是在 2026 年 3 月更新的，如果你的客户端版本较旧，可能不会读取本地模型配置。遇到配置无效时，先更新 WorkBuddy，再检查路径和 JSON。

八、常见问题

1. WorkBuddy 配置第三方大模型 api 教程 一定要用腾讯云 Token Plan 吗

不一定。腾讯官方文档示例主要展示腾讯云 Token Plan，但它同时说明 WorkBuddy 支持通过本地配置文件接入自定义模型。只要第三方入口兼容对应请求格式，就可以按 models.json 方式尝试接入。

2. 为什么我配置了模型，WorkBuddy 里看不到

优先检查 3 件事：文件路径是否正确、availableModels 是否包含模型 id、WorkBuddy 是否已经完全重启。Windows 用户还要注意不要把文件保存成 models.json.txt。

3. url 应该写到哪里

如果你接的是 ClawSocket 这类 OpenAI-compatible 接口，建议写完整路径：

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

不要只写 https://api.clawsocket.com，也不要只写 https://api.clawsocket.com/v1。

4. API Key 能不能写环境变量

官方示例是直接写在 models.json 的 apiKey 字段里。为了安全，至少要保证这个文件不要上传到 Git，也不要分享给别人。如果团队共用，建议给 WorkBuddy 单独开一把 Key，方便后续撤销和审计。

总结

这篇 WorkBuddy 配置第三方大模型 api 教程 的核心可以压缩成一句话：在 Windows 或 macOS 的用户目录下创建 .workbuddy/models.json，把第三方模型的 id、url、apiKey 和 availableModels 写对，然后重启 WorkBuddy 验证。

如果你只是接一个模型，最短路径就是用 api.clawsocket.com 生成 Key，把 url 写成 https://api.clawsocket.com/v1/chat/completions，再把模型名填进 id 和 availableModels。如果你后面还要接 Claude Code、Cursor 或 OpenAI SDK，可以继续在 ai-api-proxy.com 查对应工具的接入方式，把多模型能力统一到同一套 API 入口里。

参考资料

• 腾讯云官方：WorkBuddy 知识引擎原子能力

[^1]: 腾讯云 WorkBuddy 文档当前公开说明：WorkBuddy 支持通过本地 models.json 配置文件接入自定义模型，官方示例以 macOS 路径和腾讯云 Token Plan 模型为例。