WorkBuddy 支持把第三方大模型作为自定义模型接入，推荐从客户端的“设置 → 模型”进入配置，而不是一开始就手动编辑文件。官方文档说明，自定义模型的 API Key 等参数保存在本地配置中，WorkBuddy 只是把输入转发给你指定的模型服务；模型调用产生的费用、数据处理和可用性由第三方服务商负责。1
在正式填写 Key 之前，可以先用 AIMirror GPT 中文站 或 AICNBox 多模型入口 做中文问答和模型风格对比。它们是独立网页服务，不是 WorkBuddy 的 API provider，也不会替代你从服务商控制台创建密钥。
这篇教程适合需要在 WorkBuddy 中使用自建网关、OpenAI 兼容服务或其他模型平台的用户。示例使用占位地址和模型名，不能直接当作任何服务商的真实参数。配置前请准备 API Key、完整接口地址、模型 ID，并确认服务商的协议、隐私和收费规则。
接入前先确认接口类型
WorkBuddy 的普通自定义 API 通常按 OpenAI 兼容的 Chat Completions 路径工作，客户端会按标准规则校验或补全 /chat/completions。服务商使用经过网关封装的非标准路径时，可在高级配置中打开“自定义协议”，让 WorkBuddy 直接使用填写的完整 URL。这个开关只改变地址处理，不代表客户端会自动转换请求体、认证或响应格式；接口格式不兼容时仍需服务商提供适配。1
不要只看服务商宣传页上的“兼容 OpenAI”。至少确认四项：请求方法是否为 POST；认证是否使用 Authorization: Bearer <API_KEY>；请求和返回是否采用 OpenAI 兼容 JSON；流式输出、工具调用、图片输入等你要用的能力是否真的支持。只支持 Responses 的服务，不一定能直接填入 WorkBuddy 的普通 Chat Completions 配置，遇到这种情况应查看服务商是否提供兼容层。
先做一份配置记录
在打开设置页前，先把服务商文档中的基础地址、完整端点、模型 ID、认证方式和限流说明记在本地安全位置。把“基础地址”和“完整端点”分成两栏，避免把 /v1 或 /chat/completions 重复拼接。若服务商提供多个区域或多个模型，也要注明每个 ID 对应的价格和能力，后续排错会更快。
第一步：打开自定义模型配置
启动 WorkBuddy，进入“设置”或系统设置中的“模型”页面，点击添加模型。官方当前推荐使用图形界面管理自定义模型，可以新增、编辑和删除，不需要手动修改配置文件。部分版本的菜单名称可能略有差异，但入口都在模型设置附近。
在提供商列表中，先查找你的服务商预设；没有对应选项时选择“自定义 API”或“Custom”。预设通常会自动填入接口地址、模型列表和能力标记，自定义模式则需要你手动填写 URL、API Key 和模型名。不要为了显示一个熟悉的图标而选择错误的预设，供应商、协议和账单主体必须对应真实服务。1
第二步：填写三个核心字段
API URL
填写服务商提供的 API 基地址或完整端点。标准 OpenAI 兼容服务可能要求填写 https://api.example.com/v1，客户端再自动补全 /chat/completions；也有网关要求直接填写 https://api.example.com/v1/chat/completions。两种写法不能混用，最终以服务商文档和 WorkBuddy 的“自定义协议”说明为准。
API Key
粘贴服务商生成的 Key，不要加多余引号、空格或换行。保存前确认当前电脑不是共享设备，也不要把 Key 放进截图、聊天记录、项目仓库或团队文档。WorkBuddy 官方说明自定义模型配置保存在本地，但请求内容仍会发送给你填写的第三方模型服务，因此本地保存并不等于第三方不会处理数据。1
模型名称
填写服务商控制台显示的真实模型 ID，例如 provider-model-id。不要把页面展示名、套餐名称或营销名称直接当成模型 ID。模型 ID 错误时，最常见的结果是 404、模型不可用或保存后无法生成回复。需要切换模型时，建议复制服务商控制台中的 ID，保留一份不含 Key 的配置记录。
第三步：设置能力和协议
WorkBuddy 的自定义模型通常会让你选择或标记工具调用、图片输入、推理模式等能力。只勾选服务商确实支持的功能：不支持图片就不要开启图片输入，不支持工具调用就不要让 WorkBuddy 把任务交给工具，否则可能出现请求被拒绝或任务卡住。模型选择器里显示的能力标记只是客户端路由提示，不代表服务商一定实现了完整功能。
默认情况下，WorkBuddy 使用标准 /chat/completions 路径并自动校验和补全 URL。遇到网关使用非标准路径、项目路由或完整端点时，在高级配置中打开“自定义协议”，再把服务商给出的完整 URL 原样填入。打开后客户端会跳过路径自动补全，填错一个字符也可能直接导致 404，因此要记录原始地址并逐字核对。1
第四步：保存并做三次验证
保存模型后，在模型选择器中切换到新模型，先发送一句不含敏感信息的短请求，例如“请用三句话说明缓存和数据库的区别”。第一关是保存：模型名称、供应商图标和能力标记能够显示；第二关是请求：能在合理时间返回文本；第三关是能力：再用一个小文件测试你需要的功能，例如文档总结或小段代码解释。
验证时不要立即上传客户资料、生产代码或完整知识库。先确认请求走到了正确的服务商控制台，再查看余额、调用量和错误日志。若响应成功但工具调用失败，通常是能力标记、模型权限或服务商协议不匹配；若纯文本也失败，优先排查 URL、Key 和模型 ID。
用最小测试区分问题
可以准备三条固定测试：纯文本问答、短代码解释、一个不含敏感信息的小文件摘要。纯文本失败，优先检查地址、密钥和模型 ID；纯文本成功而代码任务失败，检查上下文长度、代码权限和模型能力；文本与代码都成功但文件失败，检查附件大小、文件格式和客户端权限。每次只调整一个字段，并在服务商后台确认是否产生了新调用，避免反复点击造成不可控费用。
旧配置文件怎么处理
官方文档说明，较早通过 ~/.codebuddy/models.json 配置的自定义模型，在界面升级后仍可继续使用，并且可以在 UI 中查看、编辑或删除。不同版本的 WorkBuddy 可能使用不同的本地配置目录，优先使用图形界面，不要根据网上文章手动创建未知路径。若需要迁移，先备份不含 Key 的字段，再在新界面重新保存，确认成功后再清理旧配置。若你的版本没有该文件，不要为了“补齐路径”而新建空配置；以当前客户端能识别的设置入口为准。1
常见报错与解决方法
401 或 403：检查 Key 是否过期、是否复制了完整内容、账号是否有该模型权限。不要在错误页面反复粘贴 Key，也不要把 Key 发给所谓客服。
404：重点检查 URL 是否重复了 /v1 或 /chat/completions，以及自定义协议开关是否与地址写法匹配。模型 ID 不存在也会返回 404。
保存成功但没有输出：先关闭工具调用、图片输入和推理标记，只保留普通文本请求；文本成功后再逐项打开能力。这样可以区分基础接口问题和高级能力不兼容。
请求很慢或费用异常：查看第三方服务商的用量与限额页面，确认 WorkBuddy 没有处于自动重试或长上下文模式。任务完成后删除不再使用的自定义模型和旧 Key，必要时在服务商后台撤销密钥。
需要更换服务商时
先在 WorkBuddy 中停用旧模型，不要立即删除仍用于排查的配置。导出或抄录不含 Key 的字段，包括模型显示名、模型 ID、地址形式和能力开关；然后创建新的自定义模型，使用无敏感信息的三条测试逐项验证。新模型稳定后，再删除旧配置并在原服务商后台撤销 Key。这样可以保留一条可回退路径，也能避免把旧网关地址误认为新服务商地址。
更换完成后，建议保留一份不含密钥的变更记录，写清旧模型停用时间、新模型核验时间、测试结果和费用预算。若团队多人使用 WorkBuddy，还要通知大家重新选择模型，避免部分会话继续调用已经撤销的 Key。发现账单或日志异常时，先暂停该模型，再按记录回滚。
安全与数据边界
自定义模型请求会经 WorkBuddy 发往你配置的第三方服务。官方说明也保留了完成请求、必要传输、安全审计、故障排查和依法留存所需的处理例外，因此不要把“Key 本地保存”理解为绝对不留存。代码、附件、聊天记录和提示词都可能包含隐私，接入前应先脱敏，并阅读双方的数据政策。金融、医疗、客户项目和企业内网场景，还应经过组织审批；本地 Ollama 可作为模型计算留在本机的备选，但也要核对其他连接器和工具的数据流向。1
API Key 与第三方账户额度绑定，泄露后可能产生未授权调用和额外费用。不要把 Key 写入 WorkBuddy 项目文件、截图或公开教程；多人共用电脑时，使用系统账户隔离，并在不再使用时删除本地配置、撤销旧 Key。
FAQ
WorkBuddy 能接任何大模型吗？
不能。模型服务至少要提供 WorkBuddy 能处理的协议和认证方式。优先选择官方预设；自定义服务要核对 URL、Key、模型 ID 和 Chat Completions 兼容性。
为什么要打开自定义协议？
只有当服务商使用非标准 URL、网关封装路径或完整请求端点时才需要打开。普通 /v1 基地址应先保持默认，让 WorkBuddy 自动补全标准路径。
自定义模型会上传到 WorkBuddy 云端吗？
官方说明模型配置参数保存在本地，WorkBuddy 作为通信链路转发输入。但你的内容仍会发送到所配置的第三方模型服务，具体留存和使用规则要看服务商协议。
能否把 API Key 分享给团队？
不建议。多人共用同一 Key 难以审计，也可能造成额度和数据风险。更稳妥的方式是每人使用自己的 Key，或由企业网关统一管理并设置权限和预算。
总结
WorkBuddy 接入第三方大模型 API 的顺序是：确认协议，进入模型设置，选择“自定义 API”，填写 URL、Key 和真实模型 ID，按需设置能力，必要时打开自定义协议，保存后用无敏感数据做文本和功能验证。正式接入前，务必核对费用、数据处理和 Key 撤销方式。