WorkBuddy 接自定义模型完整教程：3 步配置任意 OpenAI 兼容 API

适用版本：WorkBuddy 最新版 | 话题：WorkBuddy 自定义模型 · API 配置 · 模型自由

WorkBuddy 的自定义模型功能允许用户将任意兼容 OpenAI 协议的第三方 API 接入到 WorkBuddy 的对话和 Agent 工作流中，跳过内置积分消耗、直接调用自己的模型额度；配置信息仅存储在本地 ~/.workbuddy/models.json 文件中，不上传云端。无论是 DeepSeek 官方 API、Kimi、GLM，还是本地跑的 Ollama，只要提供商支持 OpenAI 兼容格式，就可以接进来。

为什么要接自定义模型

WorkBuddy 内置了 Hy3、GLM-5.2、Kimi-K3 等模型，使用时按积分计费。当你在以下情况时，接自定义模型更合适：

已有 DeepSeek、Kimi 或其他平台的 API 额度，不想重复付费
需要调用 WorkBuddy 内置列表里没有的模型（比如某个微调版本）
使用 Ollama 在本地跑开源模型，完全不走外网
希望接入一个能统一管理多款模型的 API 中间层，一个 Key 切换多模型

自定义模型接入后，费用由你直接向对应提供商支付，与 WorkBuddy 积分完全独立。

方式一：图形界面操作（推荐新手）

整个流程只需 3 步，不用碰任何配置文件。

第一步：打开配置入口

在 WorkBuddy 主界面，点击底部的模型选择器（默认显示当前使用的模型名），在弹出的模型列表最底部找到**「配置自定义模型」**，点击进入。

第二步：添加模型，选择提供商

进入「模型」设置页后，点击右上角**「+ 添加模型」**。

弹出「添加模型」对话框，顶部标注「仅支持 OpenAI 兼容协议 API」。

点击「提供商」下拉，看到已预设的选项：

分类	可选提供商
Coding Plan	Kimi Coding Plan
自定义 API	智谱开放平台 / GLM API、Kimi 中国版、MiniMax 中国版、深度求索 / DeepSeek、Ollama 本地
其他	自定义 / Custom（接入任意兼容接口）

选择预设提供商时，接口地址会自动填入，只需补上 API Key 即可保存。

选择**「自定义 / Custom」**时，需要手动填写所有字段（见第三步）。

第三步：填写接口信息并保存

选择「自定义 / Custom」后，表单展开四个字段：

接口地址：填写提供商的 chat completions 端点，格式为：

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

API Key：填入你在对应平台申请的密钥，以 sk- 开头。

模型名称：填写模型的参数名，即调用时传给 API 的 model 字段值。例如：

DeepSeek 官方：deepseek-chat 或 deepseek-reasoner
Kimi：moonshot-v1-8k 或 kimi-k2
Ollama 本地：llama3.2 或 qwen2.5:7b（与 ollama list 输出一致）

填写完成后点**「保存」**，模型会出现在 WorkBuddy 的模型选择器列表中，可直接使用。

方式二：直接编辑 models.json（适合批量配置）

如果需要一次添加多个模型，或者通过脚本管理配置，可以直接编辑本地文件：

macOS / Linux：~/.workbuddy/models.json
Windows：C:\Users\<用户名>\.workbuddy\models.json

文件格式示例：

{
  "models": [
    {
      "id": "deepseek-chat",
      "name": "DeepSeek Chat",
      "vendor": "DeepSeek",
      "apiKey": "sk-你的密钥",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "supportsToolCall": true,
      "supportsImages": false
    },
    {
      "id": "qwen2.5:7b",
      "name": "Qwen 2.5 7B（本地）",
      "vendor": "Ollama",
      "apiKey": "ollama",
      "url": "http://localhost:11434/v1/chat/completions",
      "supportsToolCall": false,
      "supportsImages": false
    }
  ]
}

字段说明：

字段	必填	说明
id	是	传给 API 的 model 参数值
name	是	下拉列表显示名称，自行定义
vendor	是	厂商标识，自行填写
apiKey	是	API 密钥；Ollama 本地填 "ollama"
url	是	完整的 chat completions 地址
supportsToolCall	否	是否支持工具调用，默认 false
supportsImages	否	是否支持图片输入，默认 false

文件保存后 WorkBuddy 会自动热重载（约 1 秒延迟），无需重启。

高级配置选项解读

图形界面的「高级配置」区域有四个选项，影响模型在 WorkBuddy 内的调用行为：

工具调用：勾选后，WorkBuddy 的 Agent 和技能（Skills）可以让该模型调用外部工具（搜索、代码执行等）。模型本身需支持 Function Calling，否则勾了也没效果。

图片输入：勾选后，在对话中可以上传图片让该模型分析。需要模型为多模态视觉模型，纯文本模型开了会报错。

思考模式：勾选后，触发模型的推理链路（类似 DeepSeek-R1 的 <think> 过程）。仅对支持此特性的模型有意义，如 DeepSeek Reasoner、某些 Kimi 版本。

自定义协议：勾选后，WorkBuddy 直接使用你填写的接口地址原样发请求，跳过自动路径补全。适用于通过 API 网关封装的非标准端点，或接口地址末尾不是 /chat/completions 的情况。

上下文窗口：手动指定该模型的输入/输出 token 上限，供 WorkBuddy 内部管理对话截断逻辑。不清楚可留空使用提供商默认值。

各常用平台接口地址速查

提供商	接口地址	模型名称示例
DeepSeek 官方	https://api.deepseek.com/v1/chat/completions	deepseek-chat
智谱 GLM	https://open.bigmodel.cn/api/paas/v4/chat/completions	glm-5-plus
Kimi 中国版	https://api.moonshot.cn/v1/chat/completions	moonshot-v1-8k
MiniMax	https://api.minimax.chat/v1/text/chatcompletion_v2	MiniMax-Text-01
Ollama 本地	http://localhost:11434/v1/chat/completions	与 ollama list 一致
七牛云多模型 API	https://api.qnaigc.com/v1/chat/completions	参考平台模型列表

使用统一多模型 API 中间层的好处是：一个 Key、一个地址，WorkBuddy 里只需配置一次，就能切换不同模型，无需为每家提供商单独管理密钥。

常见问题

Q：接入后显示「模型调用失败」怎么排查？

按顺序检查：① 接口地址末尾是否有多余斜杠或路径错误；② API Key 是否复制完整（常见问题：末尾空格）；③ 模型名称是否与提供商文档一致（大小写敏感）；④ 如果接口地址不是标准 /chat/completions 结尾，需要勾选「自定义协议」。

Q：Ollama 本地模型怎么接？

先确保 Ollama 已在本地运行（ollama serve），然后在 WorkBuddy 中选预设的「Ollama 本地 / Ollama」提供商，接口地址自动填为 http://localhost:11434/v1/chat/completions，API Key 填 ollama，模型名称填 ollama list 列出的模型名（如 llama3.2:latest）。

Q：接自定义模型会消耗 WorkBuddy 积分吗？

不会。自定义模型的请求直接发往你填写的第三方接口，费用由你向该提供商支付，与 WorkBuddy 积分完全独立。

Q：models.json 里的 API Key 安全吗？

配置仅存在本地，WorkBuddy 不会上传任何自定义模型信息到云端。但 models.json 是明文 JSON，建议不要将该文件同步到公共 Git 仓库，也不要分享给他人。

小结

WorkBuddy 的自定义模型功能本质上是一个兼容 OpenAI 协议的 API 转接层：只要提供商给出标准的 chat/completions 端点和 API Key，三步就能完成接入。图形界面适合快速配置单个模型，models.json 适合批量管理或脚本化部署。核心注意点：模型名称必须与提供商文档一致，高级配置里的工具调用和图片输入要与模型实际能力对齐，否则勾了反而会导致调用出错。

WorkBuddy 文档持续更新，本文配置方式基于 2026 年 8 月版本，如遇界面差异，以官方文档（codebuddy.cn/docs/workbuddy）为准。