WorkBuddy 手动配置 X-AIO
不依赖 Coding Helper，手动在 WorkBuddy 中添加 X-AIO 自定义模型的分步教程。
WorkBuddy 是一款面向个人和团队的 AI 工作台，可以在同一个界面中切换不同模型。本篇是普通手动配置模式：你直接在 WorkBuddy 的模型设置中填写 X-AIO 的地址、API Key 和模型 ID，不需要安装或运行 Coding Helper。
如果希望用 Coding Helper 当前 0.9.x 主线一次装载全部 X-AIO 可用模型，请阅读使用 Coding Helper 配置 WorkBuddy 的教程。本篇仍保留完整手动方式，适合不安装 Helper 或只添加单个模型的用户。
页面示例基于 WorkBuddy v5.3.14。不同版本的按钮位置可能略有变化，但“设置 → 模型 → 添加模型”的配置逻辑一致。
开始前准备
你需要准备：
- 一台可以安装 WorkBuddy 的电脑；
- 一个可以接收扫码登录确认的微信或其他登录设备；
- 一个有可用额度、能够创建 API 密钥的 X-AIO 账号。
官方入口：
先看这条安全提醒
API 密钥等同于密码。请只在自己的 WorkBuddy 客户端中粘贴，不要发到群聊、工单或截图里。本教程中的截图均已隐藏密钥内容。
1. 安装并登录 WorkBuddy
- 打开 WorkBuddy 官网，下载与你的操作系统对应的安装包。
- 安装完成后启动 WorkBuddy。首次打开会出现登录页面。
- 用手机扫描页面上的二维码，并在手机上确认登录。确认后等待桌面端自动进入工作台。
- 看到左侧导航和对话区域后，说明登录成功。若二维码过期，刷新二维码再扫码即可。
本教程只需要登录 WorkBuddy 本身，不需要把微信密码或其他账号密码填入模型设置。
2. 在 X-AIO 创建短期 API 密钥
2.1 打开密钥管理页
在浏览器打开 X-AIO API 密钥页，登录后进入 API 密钥 页面。页面上方的 OpenAI 生态端点 会显示可供兼容客户端使用的 Base URL。
2.2 新建专用密钥
在“我的 API 密钥”区域点击 新建 API 密钥，按下面方式填写：
| 项目 | 建议填写 | 说明 |
|---|---|---|
| 密钥用途 | WorkBuddy 教程示例-日期 | 便于日后识别和删除，不要写真实密码 |
| 有效期 | 7 天或其他短期选项 | 仅测试时使用，降低泄露后的风险 |
点击 创建密钥，在成功提示中点击 OK 回到密钥列表。新密钥不是只在创建瞬间显示一次：在刚才创建的目标行中点击 复制 API 密钥（需要人工核对时可先点击 显示 API 密钥，核对后立即隐藏）。只在准备填写 WorkBuddy 时复制，粘贴完成后及时清理剪贴板；不要把完整密钥放进教程截图、聊天记录或普通文本文件。
创建成功后，列表中会显示密钥名称、脱敏后的密钥、状态和有效期。下图使用 7 天短期密钥作为示意；为避免暴露密钥指纹，密钥单元格已完全遮挡。
不要选永久有效
本教程只验证 WorkBuddy 是否能正常调用模型。测试完成后删除这把专用密钥即可；日常长期使用时，也建议按设备或用途分别创建密钥。
3. 认识两个地址
X-AIO 页面显示的是 Base URL，而 WorkBuddy 的“接口地址”输入框需要完整的聊天接口地址。两者的区别如下：
Base URL（用于确认服务区域）
https://llm-api.x-aio.com/v1WorkBuddy 接口地址（粘贴到输入框）
https://llm-api.x-aio.com/v1/chat/completions不要重复添加 /v1，也不要在地址末尾再加空格。若 X-AIO 后台以后显示了新的端点，请以后台当前显示的 Base URL 为准，再在末尾追加 /chat/completions。
4. 在 WorkBuddy 添加自定义模型
4.1 打开模型设置
回到 WorkBuddy，先点击左下角的用户入口，再点击 设置，然后进入左侧的 模型 页面。点击右上角 + 添加模型。
4.2 填写模型信息
添加模型和编辑模型使用同一组字段，请按下表填写。后面的 WorkBuddy 配置截图是保存后重新打开的最终核对画面，所以窗口标题显示“编辑模型”；首次添加时看到的字段相同。截图中的 API Key 只显示为圆点，这是正确的显示状态。
先打开 X-AIO 模型中心，在列表中找到要使用的模型，点击模型名称右侧的复制图标，复制完整的模型 ID。下图以 Kimi-K2.7-Code 为例；不要手打或修改大小写。你也可以根据速度、能力和费用选择模型中心中的其他兼容开源模型，最终以账号当前可用列表为准。
| WorkBuddy 字段 | 填写内容 |
|---|---|
| 提供商 | 自定义 / Custom |
| 接口地址 | https://llm-api.x-aio.com/v1/chat/completions |
| API Key | 粘贴刚刚创建的 X-AIO 短期密钥 |
| 模型名称 | 粘贴刚刚复制的模型 ID；页面示例为 Kimi-K2.7-Code |
| 工具调用 | 按需开启；首次验证可保持开启 |
| 图片输入、推理模式、自定义协议 | 如果模型或任务不需要，先保持关闭 |
| 输入、输出 | 保持“使用提供商默认值”，不需要手动填写 |
点击 保存。回到模型列表后，应能看到刚才添加的模型及“自定义”标记。
模型名称必须完全一致
模型名称区分大小写，也不能把模型中心的展示名称改成自己的昵称。复制模型 ID 时只复制文字本身，不要把两侧引号、空格或代码块符号一起复制；遇到“模型不存在”时优先重新复制这里的值。
5. 选择模型并完成第一次对话
- 点击设置窗口右上角的 × 关闭设置。若没有自动进入空白对话，点击左上角的 + 新建对话。
- 点击输入框右下角的当前模型名称（有些版本默认显示
Auto）。 - 在模型选择器中打开 自定义 分组，选择刚保存的模型，例如
Kimi-K2.7-Code。
- 确认输入框右下角已经显示
Kimi-K2.7-Code，再发送一条普通测试消息。例如：
Reply OK- 等待模型完成回复。只要对话区出现正常回复，并且回复下方显示
Kimi-K2.7-Code，就表示 WorkBuddy、API Key、接口地址和模型名称已经连通。
按上述步骤发送 Reply OK 后，预期会收到正常回复（例如 OK. What would you like to work on?），并在回复下方看到所选的自定义模型名称。示例图中的 API Key 已隐藏；请以你自己的实际回复和模型标签为准。
成功标准
- 消息发送后没有立即出现红色错误提示；
- 对话区显示模型回复，而不是一直转圈；
- 回复下方显示刚选择的自定义模型名称。
常见问题
提示 401、Unauthorized 或 API Key 无效
检查是否复制了完整密钥、前后是否多了空格，以及密钥是否已经过期或被删除。不要把密钥贴到聊天窗口中；应回到 设置 → 模型 编辑自定义模型。
提示 402 或订阅额度不足
打开 订阅总览，检查订阅状态和可用额度。额度恢复后重新发送测试消息；订阅或额度状态更新后偶尔需要等待片刻同步。
提示 404、模型不存在或路由不存在
确认模型名称来自 X-AIO 模型中心，并检查接口地址是否为：
https://llm-api.x-aio.com/v1/chat/completions常见错误是把 Base URL 和完整接口地址混用，或重复写成 /v1/v1/...。
一直转圈、超时或没有回复
先确认网络和代理稳定，再关闭并重新打开 WorkBuddy。新建对话、重新选择刚保存的自定义模型，然后再次发送 Reply OK。若仍失败，请记录错误码和发生时间，检查 X-AIO 服务状态、额度和密钥有效期；联系支持时不要发送完整 API 密钥。
找不到“自定义”模型
回到 设置 → 模型，确认模型已经保存并显示在“已保存模型”列表中；然后关闭模型选择器，再重新打开并进入 自定义 分组。必要时重启 WorkBuddy，避免旧版本模型列表尚未刷新。
6. 测试完成后的清理
- 在 X-AIO API 密钥页 找到名称类似
WorkBuddy 示例密钥-日期的密钥，点击删除并确认。 - 回到 WorkBuddy 的 设置 → 模型，删除不再使用的自定义模型配置。
- 从密码管理器、剪贴板历史和临时文本中移除这把测试密钥。
- 如果要长期使用，请为正式用途重新创建一把独立密钥，并设置合理的有效期；不同设备或用途尽量使用不同密钥。
删除密钥后，旧配置即使还留在本地也不能继续调用 X-AIO；但为了避免误用，仍建议同步删除 WorkBuddy 中的本地配置。