> ## Documentation Index
> Fetch the complete documentation index at: https://docs.okab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WorkBuddy

> 通过控制台生成配置、设置页添加模型或编辑 models.json 接入 WorkBuddy

先按 [快速开始](https://docs.okab.ai/quickstart.md) 创建访问密钥。以下三种方式任选一种：推荐由控制台生成配置；只添加个别模型时用设置页；需要批量调整时直接编辑 `models.json`。

## 方式一：从控制台生成配置（推荐）

<video src="https://mintcdn.com/meliai/O9HtU_10MpSROMx7/videos/workbuddy-models-json.mp4?fit=max&auto=format&n=O9HtU_10MpSROMx7&q=85&s=19771d1dcd95cd027b16af2238c65894" controls />

1. 在控制台对应服务的 **访问密钥** 列表中，点击 **使用 → 客户端配置**，客户端选择 **WorkBuddy**。
2. 等待模型加载完成，按本机版本点击 **复制并打开国内版** 或 **复制并打开海外版**。
3. 在 WorkBuddy 的 **设置 → 模型** 中，点击 **本地配置文件** 的路径，打开 `models.json`。
4. 空文件直接粘贴；已有配置先备份，再把生成的 `models` 数组条目合并到原数组并保存。
5. 在模型选择器的 **自定义模型** 中选择 `MeliAI - ` 开头的模型。

配置包含完整密钥，请勿公开分享或提交到代码仓库。可用模型变化后，在控制台点击 **刷新模型**，更新原来的 MeliAI 条目。

## 方式二：在设置页添加模型

打开 WorkBuddy 的 **设置 → 模型**，或在模型选择器底部点击 **配置自定义模型**。

1. 点击 **添加模型**，**供应商** 选择 **自定义**。
2. 按下表填写；高级配置中的 Token 上限可留空，使用默认值。
3. 点击 **测试连接**，显示 **连接成功** 后保存。

| 字段 | 填写内容 |
| - | - |
| **接口地址** | `https://api.okab.ai/v1/chat/completions`，需填写完整路径 |
| **API Key** | 完整的 MeliAI 访问密钥，不加 `Bearer ` 前缀 |
| **模型名称** | 从 [模型广场](https://console.okab.ai/models) 复制模型 ID，并确认当前服务有调用权限 |
| **工具调用** | 模型支持工具调用时开启，Agent 和文件操作需要此能力 |
| **图片输入**、**思考模式** | 按模型实际能力开启 |

无需开启 **自定义协议**。保存后，模型会出现在 **自定义模型** 分组中。

## 方式三：手动编辑 models.json

在 **设置 → 模型** 中点击 **本地配置文件** 的路径。空文件可使用下面的结构；已有配置先备份，再把条目合并到原来的 `models` 数组。

```json theme={"system"}
{
  "models": [
    {
      "id": "<MODEL_ID>",
      "name": "MeliAI - 我的模型",
      "vendor": "MeliAI",
      "url": "https://api.okab.ai/v1/chat/completions",
      "apiKey": "<YOUR_MELIAI_API_KEY>",
      "supportsToolCall": true,
      "supportsImages": false,
      "supportsReasoning": false
    }
  ]
}
```

将 `<MODEL_ID>` 替换为有权限调用的模型 ID，`<YOUR_MELIAI_API_KEY>` 替换为完整密钥。`name` 是显示名称；三个 `supports` 字段按模型实际能力设置，示例仅开启工具调用。需要限制输入或输出长度时，可添加 `maxInputTokens`、`maxOutputTokens`，数值按模型能力填写。

保存后 WorkBuddy 会自动重新加载。文件必须是合法 JSON，不要加注释或末尾逗号；不要添加会隐藏内置模型的 `availableModels` 字段。国内版和海外版读取不同目录，以当前应用显示的路径为准。

## 验证与排查

在模型选择器的 **自定义模型** 中选择刚添加的模型，发送“只回答 OK”，再到 [仪表盘](https://console.okab.ai/usage) 核对 **调用记录**。需要使用 Agent 时，再让它读取一个项目文件，确认工具调用正常。

| 现象 | 处理方法 |
| - | - |
| 没有打开 WorkBuddy | 确认按钮与安装版本一致，海外版叫 WorkBuddy AI；也可手动进入 **设置 → 模型** |
| 模型没有出现 | 确认保存到当前版本显示的文件路径，JSON 无语法错误；完全退出后重开 |
| 只能对话，不能执行 Agent 任务 | 检查模型支持工具调用，且 `supportsToolCall` 为 `true` |

字段说明见 [官方配置文档](https://www.codebuddy.cn/docs/cli/models)，认证或额度错误见 [常见问题](https://docs.okab.ai/troubleshooting.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.