最后更新时间：2026-04-12
开发者入口：api.clawsocket.com
备用体验入口：AIMirror Gemini 中文站
很多人搜 workbuddy 配置第三方大模型 api，不是为了研究配置文件本身，而是想把 WorkBuddy 从默认模型扩展成一个可切换的桌面 AI 工作台。腾讯云官方文档已经给出关键路径：WorkBuddy 支持通过本地 models.json 配置文件接入自定义模型，官方示例把腾讯云 Token Plan 的混元模型写进 ~/.workbuddy/models.json，保存后重启 WorkBuddy 生效。[^1] 这就给第三方大模型 API 留出了一个清晰入口：只要你的服务兼容 OpenAI Chat Completions 风格，就可以按同样结构尝试配置。
这篇 workbuddy 配置第三方大模型 api 教程会把官方写法、第三方中转站写法和排错方法放在一起讲。需要先说明：腾讯官方文档示例面向腾讯云 Token Plan；本文的国内可用大模型中转站方案，是基于其 vendor: "OpenAI"、url、apiKey、availableModels 这些字段做的兼容配置延伸，不代表腾讯官方对所有第三方站点做了适配承诺。实际接入前，建议先用一个低成本模型跑通最小对话，再决定是否长期使用。
一、WorkBuddy 第三方大模型 API 配置到底改哪里
理解 workbuddy 配置第三方大模型 api，先不要去找复杂插件。官方文档的重点很直接：以 macOS 为例，创建 ~/.workbuddy 目录，新建 models.json，写入模型列表，然后保存并重启 WorkBuddy。配置里每个模型至少包含 id、name、vendor、url、apiKey、maxInputTokens、maxOutputTokens，最后再用 availableModels 指定哪些模型可选。[^1]
这几个字段可以这样理解：
| 字段 | 作用 | 配置建议 |
|---|---|---|
id |
WorkBuddy 识别模型的 ID，也常对应请求里的模型名 | 尽量和中转站后台给出的模型名保持一致 |
name |
在界面里更容易识别的显示名 | 写成人能看懂的名称，如 Claude Sonnet via ClawSocket |
vendor |
供应商类型 | 第三方中转站一般先填 OpenAI 兼容模式 |
url |
聊天补全接口地址 | 要写完整 chat completions 地址 |
apiKey |
认证密钥 | 不要提交到仓库，不要截图外发 |
availableModels |
WorkBuddy 可用模型列表 | 必须包含前面定义过的 id |
如果你只记一件事，就记住：WorkBuddy 读的是本地配置文件，不是网页后台表单。所以 workbuddy 配置第三方大模型 api 的排错重点也在本地路径、JSON 语法、接口地址和模型 ID，而不是反复重装客户端。
二、先按官方方式准备 models.json
第一步打开终端，创建配置目录：
mkdir -p ~/.workbuddy
第二步打开配置文件。如果你装了 VS Code，可以用：
code ~/.workbuddy/models.json
也可以用系统自带编辑器或 nano：
nano ~/.workbuddy/models.json
第三步先放一个最小结构。下面这个版本保留官方配置思路，但把中转站地址写成 api.clawsocket.com 的 OpenAI 兼容接口示例。实际使用时，把 sk-your-clawsocket-key 替换成你自己的 Key，把 id 替换成后台支持的模型名：
{
"models": [
{
"id": "gpt-4o-mini",
"name": "GPT-4o Mini via ClawSocket",
"vendor": "OpenAI",
"url": "https://api.clawsocket.com/v1/chat/completions",
"apiKey": "sk-your-clawsocket-key",
"maxInputTokens": 128000,
"maxOutputTokens": 4096
},
{
"id": "claude-sonnet-4-5",
"name": "Claude Sonnet via ClawSocket",
"vendor": "OpenAI",
"url": "https://api.clawsocket.com/v1/chat/completions",
"apiKey": "sk-your-clawsocket-key",
"maxInputTokens": 200000,
"maxOutputTokens": 4096
}
],
"availableModels": [
"gpt-4o-mini",
"claude-sonnet-4-5"
]
}
保存后完全退出 WorkBuddy，再重新打开。不要只关闭窗口，最好确认应用进程已经退出。第一次验证时，不要直接让模型写长文或读复杂文件，只发一句“请用中文回复 OK，并说明当前模型名称”。这样能判断三件事：配置文件被读取了、接口能连通、模型 ID 没写错。
三、为什么国内团队会加一个大模型中转站
workbuddy 配置第三方大模型 api 最常见的诉求，是把多个模型集中到一个入口里。WorkBuddy 本身是桌面 AI 智能体，适合处理本地操作、办公协同和对话任务；但不同场景对模型的要求不同：代码解释可能适合 Claude，中文写作可能适合 Gemini 或 GPT，快速问答又可能只需要轻量模型。如果每个供应商都单独申请 Key、单独配置网络、单独排错，团队维护成本会很高。
国内可用大模型中转站的价值就在这里。以 api.clawsocket.com 为例，它更适合已经习惯 OpenAI 风格接口的用户：你在 WorkBuddy 里仍然按 vendor: "OpenAI" 配置，只需要更换 url、apiKey 和模型名。以后要增加新模型，也是在同一个 models.json 里追加一段配置，不必推翻原来的接入方式。
这类中转站尤其适合三种情况。第一，你想在 WorkBuddy 里同时保留多个模型，按任务手动切换。第二，你的网络环境访问海外模型不稳定，希望有国内可用的统一入口。第三，你给团队成员配置 WorkBuddy，希望大家用同一套模型命名、额度和使用规范，而不是每个人自己乱填 Key。
四、第三方中转站配置时最容易错的 5 个点
第一，路径写错。官方示例使用的是 ~/.workbuddy/models.json，不是项目目录，也不是下载目录。你可以用下面命令确认文件存在：
ls -la ~/.workbuddy/models.json
第二，JSON 格式错。多一个逗号、少一个引号，WorkBuddy 都可能读不到配置。建议保存前用命令检查：
python3 -m json.tool ~/.workbuddy/models.json
第三，url 写成了基础域名。很多中转站文档会给你 baseURL，但 WorkBuddy 配置里的 url 更稳妥的写法是完整接口地址，例如 https://api.clawsocket.com/v1/chat/completions。如果只写到 /v1，请求可能打不到正确路径。
第四，模型 id 和后台不一致。workbuddy 配置第三方大模型 api 时，id 不是随便起的昵称，它很可能会作为模型参数参与请求。你可以把 name 写得好看，但 id 最好严格使用中转站支持的模型名。
第五，忘了写 availableModels。前面 models 里定义了模型，不代表界面一定会出现。官方示例也单独写了 availableModels 数组，把可用模型 ID 列出来。[^1] 所以你新增模型后，也要同步加入这个数组。
五、给不同任务推荐怎样配置模型
如果你刚开始做 workbuddy 配置第三方大模型 api，不建议一次塞十几个模型。模型太多会增加选择成本，也会让排错变复杂。更实用的做法是先保留三类模型。
| 任务 | 推荐模型类型 | 配置建议 |
|---|---|---|
| 日常问答、邮件、摘要 | 轻量快速模型 | maxOutputTokens 设 2048 到 4096，优先速度 |
| 代码解释、方案评审 | 推理或高质量模型 | 保留更高上下文，输出上限不要太低 |
| 长文档整理、会议纪要 | 长上下文模型 | maxInputTokens 按模型能力设置，不要盲目写满 |
在 api.clawsocket.com 这类中转站里，模型名会随供应商和版本变化。你应该以后台显示为准，不要直接复制别人文章里的模型 ID。本文示例更重要的是结构：vendor 用 OpenAI 兼容，url 指向 chat completions，apiKey 放你的中转站 Key，availableModels 和 id 保持一致。
六、安全注意：不要把 WorkBuddy Key 当成普通文本
workbuddy 配置第三方大模型 api 看起来只是编辑一个 JSON 文件，但里面的 apiKey 仍然是敏感凭据。不要把 models.json 传到群里，不要提交到 Git 仓库，也不要截图发给别人排错。如果你要给团队发模板，建议把 Key 写成占位符：
"apiKey": "sk-replace-me"
团队使用时，还要提前约定三件事。第一，哪些材料不能上传，例如客户合同、身份证、财务数据、内部源码。第二，谁负责额度和账单，避免一个人误跑长文档导致全队额度被打空。第三，配置变更怎么记录，尤其是模型名、接口地址和 Key 轮换时间。WorkBuddy 是效率工具，不应该成为密钥泄露和数据外发的盲区。
七、团队落地：先发模板，再让每个人填自己的 Key
如果你是在团队里推进 workbuddy 配置第三方大模型 api，不要直接把一份真实 models.json 发给所有人。更稳的做法是准备两份文件：一份是说明文档，写清每个字段怎么填；另一份是模板文件，只保留模型结构和占位符。团队成员拿到模板后，只替换自己的 apiKey，其余字段保持一致。这样后续排错时，大家至少使用同一组模型 ID 和同一套接口地址，不会出现“你能用、我不能用、但我们配置完全不一样”的混乱。
一个团队模板可以这样设计：主力模型只放 2 到 3 个，分别覆盖快速问答、代码审查和长文分析；备用模型只放 1 个，用于主模型限流或临时不可用时切换。不要把中转站后台所有模型都塞进 WorkBuddy，模型太多会让新人不知道该选哪个，也会让费用和质量难以复盘。真正需要新模型时，再由负责人更新模板并说明用途。
验证流程也要标准化。每个人完成 workbuddy 配置第三方大模型 api 后，先跑三条固定测试：第一条让模型回复当前任务说明，确认对话正常；第二条输入一段 300 字中文材料，让模型输出摘要，确认中文能力正常；第三条让模型生成一个简单 JSON，确认结构化输出可用。三条都通过，再把它用于真实办公任务。这样能把“配置成功”和“工作可用”区分开，避免只看能不能回复一句话。
对于需要长期使用 WorkBuddy 的团队，建议每月做一次轻量复盘。记录哪些模型最常被使用、哪些任务经常失败、哪类提示词效果最好、是否出现过额度异常。中转站只是入口，真正让工具稳定的是配置纪律和使用反馈。把这些反馈沉淀下来，下一次更新 models.json 时就不会靠感觉选模型。
八、FAQ：WorkBuddy 配置第三方大模型 API 常见问题
WorkBuddy 官方支持第三方 API 吗？
腾讯云官方文档的表述是，WorkBuddy 支持通过本地配置文件接入自定义模型，并给出了 models.json 示例。官方示例面向腾讯云 Token Plan，不等于所有第三方中转站都被官方认证。本文的第三方方案，适用于 OpenAI 兼容接口的工程尝试。
为什么我配置了 api.clawsocket.com 但界面没有模型？
先检查 availableModels 是否包含你的模型 id，再检查 JSON 是否有效，最后确认 WorkBuddy 是否完全重启。很多问题不是接口不可用，而是配置文件没有被正确读取。
url 应该写 baseURL 还是完整地址？
建议写完整 chat completions 地址。对 api.clawsocket.com 这类 OpenAI 兼容入口，可以先用 https://api.clawsocket.com/v1/chat/completions 测试。如果服务商后台给了不同路径，以后台文档为准。
能不能同时配置 GPT、Claude、Gemini？
可以尝试，只要中转站支持对应模型，并且它们都能通过同一套 OpenAI 兼容接口调用。建议先每次新增一个模型，测试成功后再加下一个，避免同时出错无法定位。
这套教程适合 Windows 吗？
本文按腾讯云官方文档的 macOS 示例展开。Windows 的核心逻辑仍然是找到 WorkBuddy 读取的配置目录并写入 models.json，但路径可能不同。没有确认路径前，不建议照搬 ~/.workbuddy。
总结：先小配置跑通，再把模型池扩起来
workbuddy 配置第三方大模型 api 的关键不是写一大段配置，而是按顺序验证：先确认 models.json 路径，再确认 JSON 格式，再确认中转站 Key 和模型 ID，最后重启 WorkBuddy 测试。官方文档已经把本地配置文件这条路说明清楚，国内用户如果想更快接入多模型，可以把 api.clawsocket.com 作为 OpenAI 兼容的大模型中转站入口，先用一个轻量模型跑通，再逐步加入 Claude、Gemini、GPT 等高质量模型。