在当今快节奏的开发环境中，WorkBuddy 凭借其灵活的工作流编排与强大的系统级集成能力，已成为众多开发者桌面端不可或缺的“生产力中枢”。它不仅能够聚合碎片化的开发工具，更能作为专属的智能中台，让开发者在无需切换上下文的沉浸式环境下直接调用顶尖 AI 能力，从而大幅消除日常任务的执行摩擦，让核心精力彻底回归到高价值的思考与创造中。
为了帮助广大开发者更高效地将 B.AI 的高性能模型矩阵与系统级基础设施引入日常开发工作流，本文将详细指引您如何在 WorkBuddy 桌面端添加 B.AI 自定义模型。配置前请准备好 WorkBuddy 账号、B.AI API Key，以及当前账号实际可用的模型 ID。接下来，只需跟随本文的简单配置，即可在本地解锁极致流畅的 AI 协作体验。
一、开始之前
第一步：安装 WorkBuddy
前往 WorkBuddy 官方下载页面 ，根据您的系统环境选择对应的安装包。已经安装 WorkBuddy 的用户可以跳过本步。若找不到「模型」或「添加模型 」选项，先选择「检查更新」 进行版本升级。
Windows
官方页面当前提供 Windows x64（兼容 ARM64） 安装包，要求 Windows 10 或更高版本。下载安装程序后，双击并按向导完成安装，再启动 WorkBuddy。
注意：如果系统阻止安装，请先确认安装包来自官方页面，再检查弹窗中的应用名称与发布者信息。不要通过关闭 Windows 安全防护绕过检查。
macOS
官方页面当前分别提供 Apple 芯片版和 Intel 版 .dmg，要求 macOS 12.0 或更高版本。
- M1、M2、M3、M4 等机型选择 Apple 芯片版。
- Intel 处理器机型选择 Intel 版。
打开 .dmg 后，将 WorkBuddy 拖入「应用程序」，再从应用程序文件夹启动。如果不确定芯片类型，可在「关于本机」中查看「芯片」或「处理器」。
其他系统说明
目前 WorkBuddy 桌面端仅支持 Windows 与 macOS，暂不支持 Linux。同时，考虑到移动端与鸿蒙端的功能范围不同，本教程的所有操作均以桌面端为准。
第二步：登录 WorkBuddy
首次启动时，点击「登陆」，按客户端显示的方式完成认证。国际版官方文档列出 Google 和 GitHub OAuth。如果当前客户端显示微信扫码或其他入口，以客户端实际选项为准。
第三步：获取 B.AI API Key
请先登录 B.AI，在左侧导航栏中进入 API 管理或 API Key 管理页面，点击「创建 API Key」并为其设置一个便于识别的名称（例如 WorkBuddy）。由于 B.AI 的官方机制限制，完整的 Key 只会在创建成功时显示一次，因此请务必在创建后立即复制并妥善保存。
配置前的重要确认事项：
- 前置检查：配置前请确认账号有可用额度，且该 API Key 对目标模型具有调用权限。
- 模型 ID 获取：模型 ID 应以 B.AI GET /v1/models 的返回结果或当前控制台列表为准，不能只参考其他教程中的示例名称。
- 协议兼容性：WorkBuddy 自定义模型使用 OpenAI Chat Completions 协议，因此目标模型还必须对该端点开放。只支持 Anthropic Messages 或 OpenAI Responses 的配置不能直接填入。
注意：不要在文章、截图、聊天记录或公开仓库中暴露完整 Key。如果怀疑 Key 已泄露，请立即删除旧 Key、创建新 Key，并更新 WorkBuddy 配置。
二、通过界面配置 B.AI API
第一步：打开自定义模型配置
打开 WorkBuddy，点击左下角账户头像，选择「设置 」。
在左侧选择「模型」，点击「添加模型」。
如果当前列表中已有其他自定义模型，请确保点击「添加模型」新增配置，切勿直接覆盖无关模型的参数。若您需要修改现有的 B.AI 模型，只需点击该模型旁边的铅笔图标即可。如果您希望在修改的同时保留旧版模型，则应当作全新模型重新添加一条配置。
第二步：填写接入参数
在「提供商」下拉列表中选择「自定义」，在弹出的页面中填写相关信息。
填写说明如下：
URL 与「 自定义协议」必须成对设置：
根据 WorkBuddy 官方文档，当「自定义协议」关闭时，客户端会按照标准的 OpenAI Chat Completions 规则，自动在填写的 URL 末尾补全 /chat/completions 路径；当该开关开启时，客户端将直接向您填写的完整 URL 发起请求，不再进行任何路径拼接。注意不要把两种方式混用。重复拼接成 /v1/chat/completions/chat/completions 时，通常会返回 404。
第三步：设置模型能力
「高级设置」中的开关只用于声明模型能力，勾选后不会让原本不支持的模型自动获得能力。请根据实际情况，参考以下原则进行配置：
第四步：保存配置
检查 URL、API Key 和模型 ID 后，点击「保存」。新模型应出现在「已保存模型」列表中。
如果没有显示，依次检查保存弹窗是否仍然打开、字段是否报错、模型选择器是否刷新以及客户端版本。必要时完全退出 WorkBuddy 后重新启动。模型出现在列表中，只能说明配置已保存，不能证明 B.AI 调用已经成功，仍需进行后续验证。
三、选择模型并验证配置
第一步：选中 B.AI 自定义模型
返回「新建任务」，打开输入框附近的模型选择器，在自定义模型分组中选择刚添加的模型。测试期间不要选择“Auto”模式，“Auto”模式可能调度其他模型，无法证明本次请求使用了 B.AI。
第二步：验证普通对话
发送一条不依赖工具的简单问题：
请只回复：B.AI 普通对话测试成功
收到正常回复后，说明 WorkBuddy 已读取配置，并且 Key、URL 与模型 ID 至少可以完成一次文本调用。如果失败，按「当前模型 → API Key → URL 与协议开关 → 模型 ID → 额度与权限」的顺序检查。不要通过询问模型「你是谁」判断路由是否成功，模型自报身份不能作为接入证据。
第三步：验证工具调用
请先新建一个只用于测试的文件夹，放入一两个不含隐私信息的文本文件，接着在 WorkBuddy 中将该文件夹选为 workspace，并仅授予完成读取任务所需的权限，最后发送以下指令：
请读取当前工作空间中的文本文件，列出文件名并各用一句话总结内容。不要修改、移动或删除任何文件。
WorkBuddy 显示文件读取工具调用，并正确返回文件摘要，才说明工具调用链路可用。能聊天但不能读文件时，检查工具调用、模型工具调用能力、B.AI 端点支持以及工作空间权限。
第四步：核对 B.AI 调用记录
若 B.AI 控制台提供用量或调用记录，请前往核对近期的请求时间、模型 ID、请求次数以及 Token 消耗量，确保数据与刚刚的测试相符。
为了确保整个接入流程完整可用，请逐一核查以下三个阶段的成功状态：
四、常见问题
1、找不到自定义模型入口怎么办？
可能是尚未登录、客户端版本较旧，或打开的不是桌面端模型设置。先登录，再进入「设置」→「模型」。若依然找不到入口，选择「检查更新」更新客户端并重启。问题持续时，通过「帮助与反馈」提交版本号和截图。
2、Windows 或 macOS 无法安装或打开怎么办？
先确认系统版本满足要求、安装包来自官方页面，并检查下载的架构是否正确。按系统提供的安全设置流程处理拦截，不要关闭安全防护，也不要改用不明镜像。
3、保存后为什么没有显示模型？
先确认「已保存模型」中是否存在该条目，再关闭设置并重新打开模型选择器。仍未显示时完全退出并重启 WorkBuddy，同时检查客户端更新。
4、出现 401、403、404、429 是什么原因，如何解决？
每次只需修改一项，再用普通对话重测，便于定位原因。
5、出现 “model not found”提示如何解决？
重新调用 GET /v1/models 或查看当前控制台列表，复制准确的 id。不要填写展示名称、别名或其他教程中的版本号。还要确认该模型对 Chat Completions 端点开放。
6、一直加载、超时或连接失败怎么办？
请先确认网络可以访问 https://api.b.ai，再用简短问题进行测试。随后检查 URL、代理或企业网络策略、B.AI 服务状态，以及输入文件是否过大。问题持续时记录发生时间、WorkBuddy 版本、完整错误信息与请求 ID，再联系官方支持。
7、能聊天但不能读取文件怎么办？
按「模型能力 → Tool Calling 开关 → 工作空间 → 文件权限」的顺序检查。先用普通文本文件测试，不要直接选择系统目录、受保护目录或敏感文件。
8、为什么系统仍然在调用内置模型？
请检查模型选择器，确保未处于“Auto”状态，且已明确选中已配置的 B.AI 自定义模型。发送一个简短的问题，然后前往 B.AI 控制台核对调用时间与用量数据。如仍有疑问，建议新建一个对话任务重新测试。
9、关闭软件后，下次怎么启动？
Windows 可从开始菜单或桌面快捷方式启动，macOS 可从应用程序或启动台启动。重启后若未看到自定义模型，请先确认当前账号是否处于登录状态，随后前往「设置」→「模型」检查已保存的模型列表。
10、换电脑是否需要重新配置？
建议重新配置。WorkBuddy 界面提示自定义模型会写入本机 .workbuddy/models.json，不能仅凭登录同一账号就假定 API Key 与模型配置会同步。新电脑上应重新添加模型并完成两项验证，不要通过聊天、公开网盘或未加密文档传输 Key。
参考资料：
- WorkBuddy 官方下载页
- WorkBuddy 官方模型配置文档
- WorkBuddy Windows 安装指南
- WorkBuddy macOS 安装指南
- B.AI API 参考
- B.AI 获取 API Key 指南
