WorkBuddy 接入自定义模型完整教程：Claude、OpenAI、DeepSeek 与 Sub2API

2026-08-20

1 0

WorkBuddy 自定义模型可以通过 设置 → 模型 的可视化界面配置，也可以使用用户级或项目级 models.json 管理。最容易出错的地方不是 API Key，而是接口协议：当前通用自定义模型以 OpenAI Chat Completions 兼容格式为核心，接口 URL 通常必须写到完整的 /v1/chat/completions。OpenAI、DeepSeek 可以直接接入；Claude 原生 /v1/messages 与此协议不同，如果当前 WorkBuddy 版本的提供商列表中有 Anthropic/Claude 预设，应优先使用预设，否则需要通过能转换为 OpenAI 兼容格式的网关接入。

本文按 2026 年 8 月 19 日可用的 WorkBuddy 文档与 DeepSeek 官方接入说明整理，覆盖 OpenAI、DeepSeek、Claude、其他兼容 API，以及 Sub2API 中转站 API Key 的创建和使用。API Key 均使用占位值，正文不提供共享密钥或公共密钥。

一、先判断该用哪种接入方式

接入对象	推荐方式	WorkBuddy 中填写的 URL	关键限制
OpenAI 官方 API	Provider 预设或自定义模型	`https://api.openai.com/v1/chat/completions`	模型 ID 必须是账号实际可用的 ID
DeepSeek 官方 API	DeepSeek 预设或自定义模型	`https://api.deepseek.com/v1/chat/completions`	以官方当前模型列表为准
Claude 官方 API	当前版本若提供 Anthropic/Claude 预设则优先使用	由预设自动填写	不要把 `/v1/messages` 当作 Chat Completions URL
OpenAI 兼容服务	Custom API	服务商给出的完整 `/chat/completions` 地址	必须真实兼容工具调用和流式输出
Sub2API	Custom API	`https://你的域名/v1/chat/completions`	Key 要绑定正确分组，模型 ID 要在该分组可用
Ollama 本地模型	Ollama 预设或 Custom API	`http://localhost:11434/v1/chat/completions`	只适合本机或可信内网，不要把端口裸露到公网

WorkBuddy 的官方模型配置说明确认，新版可以直接在设置页面添加、编辑和删除自定义模型；以前写在 ~/.codebuddy/models.json 中的模型仍会继续生效。官方的 models.json 配置文档还明确要求：通用自定义模型使用 OpenAI 接口格式，url 应是完整接口路径，而不是只写域名或 /v1。

如果你还在搭建 AI 编程环境，可先阅读 Claude Code 接入 DeepSeek 的 Windows 教程；更多 AI 与效率工具内容收录在 Seedloc 教程。

二、准备 API Key，并先做好安全隔离

开始配置前，建议为 WorkBuddy 单独创建一个 API Key，不要复用生产服务、团队后台或其他客户端正在使用的主密钥。

在模型服务商或中转站后台创建独立 Key；
如果平台支持，设置月度额度、有效期、IP 白名单和并发限制；
Key 只保存在密码管理器、系统环境变量或 WorkBuddy 模型设置中；
截图、日志、文章和聊天记录中只展示前后少量字符；
一旦完整 Key 出现在公开页面，立即撤销并重新生成。

OpenAI 的官方 API 快速开始和 Anthropic 的官方 API 概览都将 API Key 视为服务端凭据，不应放进公开代码或可被其他人读取的客户端配置。个人电脑上的 WorkBuddy 虽然是本地应用，也应遵循最小权限原则。

三、通过 WorkBuddy 可视化界面添加模型

新版 WorkBuddy 的操作路径如下：

打开 WorkBuddy，进入 设置（Settings）；
选择 模型（Model）；
点击添加自定义模型；
优先选择列表中的服务商预设；没有对应服务商时选择 Custom API；
填写模型名称、模型 ID、API URL 和 API Key；
根据模型真实能力设置 Tool Call、图片输入和推理能力；
保存后回到任务页面，在模型选择器的自定义模型分组中选择它。

服务商预设会自动补充接口 URL 和部分能力参数，通常比手填稳定。使用 Custom API 时，URL 应直接指向请求接口，例如：

https://api.openai.com/v1/chat/completions
https://api.deepseek.com/v1/chat/completions
https://api.your-domain.tld/v1/chat/completions

以下地址通常不完整：

https://api.openai.com/v1
https://api.deepseek.com
https://api.your-domain.tld

高级设置中的 Custom Protocol 只用于关闭路径校验和自动补全，让 WorkBuddy 按填写的 URL 发送请求。它不会自动把 OpenAI 请求体转换成 Anthropic Messages 请求体；协议不一致时，即使 URL 能访问也可能返回 400。

四、接入 OpenAI 官方 API

在 WorkBuddy 中选择 OpenAI 预设最省事。如果当前版本没有预设，可以按下面填写：

字段	值
名称	`OpenAI Direct`
模型 ID	OpenAI 账号实际可用的模型 ID
API URL	`https://api.openai.com/v1/chat/completions`
API Key	在 OpenAI Platform 创建的独立 Key

模型 ID 不要根据网页产品名称猜测。API 型号、ChatGPT 网页套餐和账号权限不是一回事，应从 OpenAI 当前模型文档、控制台或模型列表中确认。

可以先在 PowerShell 验证 Key 和模型是否可用：

$env:OPENAI_API_KEY = "sk-your-openai-key"
$env:OPENAI_MODEL_ID = "your-openai-model-id"

$body = @{
  model = $env:OPENAI_MODEL_ID
  messages = @(
    @{ role = "user"; content = "Reply with OK" }
  )
  stream = $false
} | ConvertTo-Json -Depth 6

Invoke-RestMethod `
  -Uri "https://api.openai.com/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:OPENAI_API_KEY" } `
  -ContentType "application/json" `
  -Body $body

能返回 choices 说明基础对话链路正常。是否支持工具调用、图片输入和长上下文，还要以该模型的官方能力为准，不要为了让按钮可选而把所有能力开关都打开。

五、接入 DeepSeek 官方 API

DeepSeek 已提供专门的 WorkBuddy/CodeBuddy 接入说明。截至本文核验时间，官方示例使用以下配置：

字段	DeepSeek V4 Pro	DeepSeek V4 Flash
模型 ID	`deepseek-v4-pro`	`deepseek-v4-flash`
API URL	`https://api.deepseek.com/v1/chat/completions`	同左
最大输入	`128000`	`128000`
最大输出	`8192`	`8192`
Tool Call	开启	开启
图片输入	关闭	关闭

如果你的 DeepSeek 控制台显示不同模型，请以控制台和最新官方文档为准。模型 ID 是请求参数，不是可以自由命名的显示名称。

PowerShell 验证示例：

$env:DEEPSEEK_API_KEY = "sk-your-deepseek-key"

$body = @{
  model = "deepseek-v4-flash"
  messages = @(
    @{ role = "user"; content = "Reply with OK" }
  )
  stream = $false
} | ConvertTo-Json -Depth 6

Invoke-RestMethod `
  -Uri "https://api.deepseek.com/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:DEEPSEEK_API_KEY" } `
  -ContentType "application/json" `
  -Body $body

六、Claude 应该怎样接入

Claude 官方 API 使用 Anthropic Messages 协议，常见端点是 /v1/messages，认证头和请求体也与 OpenAI Chat Completions 不同。因此要分两种情况处理。

WorkBuddy 有 Anthropic 或 Claude 预设

直接选择预设，只填写 API Key 和模型。URL、认证方式和能力字段交给预设管理。保存前核对预设确实来自 WorkBuddy，而不是名称相近的第三方服务。

WorkBuddy 只有 Custom API

不要把 https://api.anthropic.com/v1/messages 直接填入普通 OpenAI 兼容配置。此时需要满足以下任一条件：

使用明确提供 OpenAI Chat Completions 兼容层的 Claude 网关；
使用自建协议转换服务；
使用能把 Chat Completions 转换到 Claude 上游的 Sub2API 分组。

配置网关时，WorkBuddy 看到的仍然应该是完整的 /v1/chat/completions 地址。模型 ID 使用网关公布的 ID，不一定等于 Anthropic 官方名称。网关是否完整支持 Tool Call、流式输出、思考内容和图片输入，需要逐项测试。

七、接入任意 OpenAI 兼容 API

只要服务满足以下条件，就可以按 Custom API 接入：

接收 POST /v1/chat/completions；
使用 Authorization: Bearer <API Key> 或服务商明确说明的认证方式；
请求体包含 model 和 messages；
流式响应、错误码和 Tool Call 结构与 OpenAI 格式兼容；
模型 ID 可以通过文档或 /v1/models 确认。

建议先用最小请求验证基础对话，再测试工具调用。很多服务只做了文本对话兼容，勾选 Tool Call 后才会暴露格式不完整的问题。

通用 PowerShell 测试模板：

$env:COMPAT_BASE_URL = "https://api.your-domain.tld"
$env:COMPAT_API_KEY = "sk-your-compatible-key"
$env:COMPAT_MODEL_ID = "your-compatible-model-id"

$body = @{
  model = $env:COMPAT_MODEL_ID
  messages = @(
    @{ role = "user"; content = "Reply with OK" }
  )
  stream = $false
} | ConvertTo-Json -Depth 6

Invoke-RestMethod `
  -Uri "$env:COMPAT_BASE_URL/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:COMPAT_API_KEY" } `
  -ContentType "application/json" `
  -Body $body

your-domain.tld、Key 和模型 ID 均代表你自己的服务信息，不是可直接调用的公共配置。

八、Sub2API 创建 API Key

Sub2API 是开源 AI API 网关，可管理 Claude、OpenAI、DeepSeek 等上游账号，并把用户 Key 绑定到指定分组。项目 README 明确提示：某些上游账号或订阅的转发方式可能违反服务商条款，部署和使用前应核对上游许可，并遵守所在地法律及服务协议。

如果你使用别人运营的 Sub2API 站点，用户端流程通常是：

登录 Sub2API 控制台；
进入 API 密钥；
点击 创建密钥；
填写容易识别的名称，例如 WorkBuddy-PC；
选择能够访问目标模型的分组；
按需设置配额、有效期、速率/用量限制或 IP 限制；
创建后立即复制 sk-... 密钥，并保存到密码管理器。

Sub2API 的 Key 与分组绑定。分组决定可用上游、计费倍率和模型范围。如果 /v1/models 有结果但调用模型返回权限错误，先检查 Key 的分组，而不是反复重建 WorkBuddy 配置。

使用 Key 查询可用模型：

$env:SUB2API_BASE_URL = "https://sub2api.your-domain.tld"
$env:SUB2API_KEY = "sk-your-sub2api-key"

Invoke-RestMethod `
  -Uri "$env:SUB2API_BASE_URL/v1/models" `
  -Headers @{ Authorization = "Bearer $env:SUB2API_KEY" }

在 WorkBuddy 中添加 Sub2API 模型时填写：

字段	值
Provider	`Custom API`
名称	`Sub2API - Claude`、`Sub2API - OpenAI` 等自定义显示名称
模型 ID	`/v1/models` 返回且分组允许的精确 ID
API URL	`https://sub2api.your-domain.tld/v1/chat/completions`
API Key	新创建的独立 Sub2API Key

Sub2API 同时实现 /v1/messages 和 /v1/chat/completions 等路由，但 WorkBuddy 的普通自定义模型应使用 Chat Completions 地址。即使 Sub2API 上游是 Claude，也让网关完成协议转换，不要把 WorkBuddy 的通用配置指向 /v1/messages。

九、使用 models.json 统一管理多个模型

需要在多台电脑、多个项目或团队仓库中复用配置时，models.json 比逐个点击更容易审计。

用户级路径：

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

项目级路径：

<项目目录>/.codebuddy/models.json

项目级配置优先于用户级配置；相同 id 会被项目级定义覆盖。下面的示例同时包含 OpenAI、DeepSeek 和 Sub2API：

{
  "models": [
    {
      "id": "your-openai-model-id",
      "name": "OpenAI Direct",
      "vendor": "OpenAI",
      "url": "https://api.openai.com/v1/chat/completions",
      "apiKey": "${OPENAI_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192
    },
    {
      "id": "deepseek-v4-pro",
      "name": "DeepSeek V4 Pro",
      "vendor": "DeepSeek",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false,
      "relatedModels": {
        "lite": "deepseek-v4-flash",
        "reasoning": "deepseek-v4-pro"
      }
    },
    {
      "id": "deepseek-v4-flash",
      "name": "DeepSeek V4 Flash",
      "vendor": "DeepSeek",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false
    },
    {
      "id": "your-sub2api-model-id",
      "name": "Sub2API Gateway",
      "vendor": "Sub2API",
      "url": "${SUB2API_BASE_URL}/v1/chat/completions",
      "apiKey": "${SUB2API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192
    }
  ],
  "availableModels": [
    "your-openai-model-id",
    "deepseek-v4-pro",
    "deepseek-v4-flash",
    "your-sub2api-model-id"
  ]
}

保存时注意：

文件必须是合法 JSON，不能写注释或尾随逗号；
建议使用 UTF-8 无 BOM；
availableModels 中必须包含希望显示的模型 ID；
环境变量要在 WorkBuddy 启动前存在；
Windows 使用 setx 后只影响新启动的进程，需要完全退出并重新打开 WorkBuddy；
如果桌面端不展开 ${SUB2API_KEY}，可从已设置变量的终端启动，或改用可视化设置保存 Key。

不要把带真实 Key 的项目级 models.json 提交到 Git。团队仓库只保存环境变量引用和示例结构。

十、验证是否真正配置成功

保存模型后不要只看“模型已出现”，至少完成四项验证：

基础对话：发送“只回复 OK”，确认能正常返回；
连续对话：追问上一条内容，确认上下文没有丢失；
工具调用：让 WorkBuddy 执行一个只读的小任务，确认工具参数和结果能闭环；
长输出：生成一段结构化内容，观察是否中途断流或出现格式错误。

使用中转站时，再到 Sub2API 的用量记录检查：Key、模型、Token 计费和请求时间是否与本次测试一致。看不到请求通常说明 URL、DNS 或客户端配置错误；有请求但上游失败，则重点检查分组、模型 ID和上游状态。

十一、常见错误排查

`401` 或 Authentication Fails

Key 粘贴时带了空格或换行；
把 API URL 填进了 Key 字段；
Key 已撤销、过期或额度耗尽；
环境变量只在当前终端存在，WorkBuddy 进程没有继承；
Sub2API Key 没有绑定可用分组。

`404` 或模型不存在

URL 只写到域名或 /v1，没有完整 /chat/completions；
模型 ID 使用了显示名称，而不是 API 返回的精确 ID；
中转站分组不开放该模型；
服务商更新了模型名称，但本地仍是旧配置。

`400`、请求体错误或 Unsupported field

最常见原因是协议不匹配，例如把 Anthropic /v1/messages 填进 OpenAI 兼容配置。Custom Protocol 只能改变 URL 处理方式，不能改变请求体结构。

模型能聊天，但 WorkBuddy 任务失败

基础对话兼容不等于 Agent 能力兼容。关闭没有证据支持的 supportsToolCall、supportsImages 或推理开关，再逐项测试。如果服务商声称兼容，但工具调用返回结构缺字段，应由服务商修复协议实现。

模型不出现在选择器

检查 models.json 路径；
检查 JSON 语法和 UTF-8 BOM；
确认 ID 已加入 availableModels；
等待配置热加载后重新打开模型列表；
仍无效时完全退出 WorkBuddy 再启动。

十二、最终安全清单

每个客户端使用独立 API Key；
给 Sub2API Key 设置合理额度和有效期；
文章、截图、终端历史和 Git 中没有完整 Key；
URL 使用 HTTPS，只有本机 Ollama 等可信场景使用 HTTP；
模型 ID 来自官方控制台或 /v1/models；
Claude 原生协议与 OpenAI 兼容协议没有混用；
Tool Call 和图片能力经过实际测试后再开启；
中转服务的运营方、日志政策、计费和上游授权可以被信任。

配置完成后，建议先用一个低风险、只读任务验证完整链路，再交给 WorkBuddy 处理本地文件或连接器数据。想对比其他 AI 工具，可继续阅读 ChatGPT 与 Gemini 工具介绍；如果主要目标是低成本 AI 编程，也可以参考 Windows 配置 Claude Code 与 DeepSeek。

声明：本站原创文章文字版权归本站所有，转载务必注明作者和出处；本站转载文章仅仅代表原作者观点，不代表本站立场，图文版权归原作者所有。如有侵权，请联系我们删除。

WordPress 7.1 正式发布：新功能、兼容性与安全升级指南

WordPress 7.1 Mary Lou 已正式发布。本文梳理响应式样式、全新媒体编辑器、协作 Notes、浏览器端图片处理和新区块，并给出 1Panel、自建站与生产环境的备份、兼容性检查、升级及回滚步骤。

seedloc

3 0