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

# WorkBuddy

WorkBuddy 是支持自定义模型接入与工具调用的桌面 AI 客户端。通过自定义模型接入 Step Plan 后，可以在 WorkBuddy 中调用 Step 系列模型。

WorkBuddy 已上架 Step 5 Preview，可在模型列表中选择。本文介绍通过自定义模型接入 Step Plan 的方式，调用消耗您自己的 Step Plan 额度。

## 前置条件

已开通 Step Plan 订阅，并在 [阶跃星辰开放平台](https://platform.stepfun.com/interface-key) 创建 API Key。

## 在 App 内添加模型

**1. 打开模型设置**

打开 WorkBuddy 的「设置」，进入「模型」，点击「添加模型」。

**2. 填写连接信息**

本文以 Step 5 Preview 为例。Step Plan 支持的其他模型也可以按同样方式添加，模型清单见 [Step Plan 概述](https://platform.stepfun.com/docs/zh/step-plan/overview.md#支持的模型)。

| 界面字段 | 填写内容 |
| - | - |
| 供应商 | 自定义（OpenAI 兼容协议 API） |
| 接口地址 | `https://api.stepfun.com/step_plan/v1` |
| API Key | 在 Step 开放平台创建的 API Key |
| 模型名称 | `step-5-preview` |

当前版本会在接口地址后自动拼接 `/chat/completions`，填写 Base URL 即可。

**3. 设置模型能力**

展开「高级配置」，按下表设置，其他选项保持默认。

| 配置项 | 设置 |
| - | - |
| 工具调用 | 勾选，用于执行文件读取等本地任务 |
| 图片输入 | 勾选 |
| 思考模式 | 勾选 |
| 自定义协议 | 不勾选 |
| 默认思考强度 | `medium` |
| 可选思考强度（界面提供该字段时） | `low`、`medium`、`high` |
| 最大输入 tokens（界面提供该字段时） | `1000000` |
| 最大输出 tokens（界面提供该字段时） | `64000` |

首次接入使用 `medium`，后续按任务调整思考强度。

**4. 保存并发送第一条消息**

1. 点击「测试连接」，连接成功后点击「保存」。
2. 在对话界面的模型选择器中选择刚添加的 `step-5-preview`。列表中可能同时存在内置的同名模型，请选择自己添加的条目。
3. 发送测试消息：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请只回复：连接成功
```

回复中出现「连接成功」表示 App 内接入成功。

## 通过配置文件添加模型

除 App 内配置外，也可以直接编辑配置文件添加模型。路径以 App 设置页「本地配置文件」显示的为准，macOS 下通常为 `~/.workbuddy-ai/models.json`；文件不存在时先通过 App 添加一次模型。已有配置时，将模型对象追加到数组中，保留原有内容。

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
[
  {
    "id": "step-5-preview",
    "name": "Step 5 Preview（阶跃星辰）",
    "vendor": "Custom",
    "url": "https://api.stepfun.com/step_plan/v1",
    "apiKey": "YOUR_STEP_API_KEY",
    "supportsToolCall": true,
    "supportsImages": true,
    "supportsReasoning": true,
    "useCustomProtocol": false
  }
]
```

`url` 填 Base URL，不要带 `/chat/completions`。保存为 UTF-8 编码的 JSON，模型在界面中显示为 `name` 字段的值。模型没有出现时，先确认文件路径与 JSON 格式，再完全退出并重新打开 WorkBuddy。

## 验证工具调用

首次回复成功后，打开一个本地测试目录，发送下面的任务，并按界面提示授予目录访问权限。

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
请使用文件工具列出当前目录的一级文件和文件夹，并告诉我一共有多少项。只读取，不修改或删除文件。
```

检查返回结果是否与目录内容一致，并确认 WorkBuddy 实际调用了文件工具。

## 直接验证 API

如需区分 App 配置问题与服务端问题，可在 macOS 终端执行以下命令。执行 `read -s STEP_API_KEY` 后粘贴密钥并回车，输入不会显示。

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
read -s STEP_API_KEY
printf '\n'
curl --silent --show-error \
  https://api.stepfun.com/step_plan/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${STEP_API_KEY}" \
  -d '{
    "model": "step-5-preview",
    "messages": [{"role": "user", "content": "Reply with exactly OK."}],
    "reasoning_effort": "low",
    "max_tokens": 1024,
    "stream": false
  }'
unset STEP_API_KEY
```

返回 JSON 中 `choices[0].message.content` 为 `OK` 表示接口与密钥可用，失败时按 `error` 内容排查。该请求只验证接口与密钥，App 内接入仍需在 WorkBuddy 中发送消息确认。

## 问题排查

| 现象 | 原因 | 处理方式 |
| - | - | - |
| 测试连接提示 API Key 无效或没有权限 | 该提示会合并多种鉴权错误 | 检查 Key 是否完整、账号是否具备调用权限，必要时用「直接验证 API」一节的请求查看服务端返回的具体原因。 |
| 模型出现在列表中，但发送消息失败 | 选中的可能是内置同名模型，或配置未生效 | 在模型选择器中确认选中的是自己添加的条目，并查看完整错误信息。 |
| 提示 404 或模型不存在 | 接口地址或模型 ID 填写不正确 | 核对接口地址为 `https://api.stepfun.com/step_plan/v1`、模型名称为 `step-5-preview`，并确认未勾选自定义协议。 |
| 返回 402 或 `quota_exceeded` | 接口地址指向按量付费通道，或账号额度不足 | 将接口地址改为 `https://api.stepfun.com/step_plan/v1`。Step Plan 额度只在 `step_plan` 端点生效，普通 `/v1` 按账户余额计费。 |
| 修改 `models.json` 后模型没有出现 | 文件路径不是实际读取的路径，或 JSON 无法解析、模型未加入 `availableModels` | 确认修改的是 WorkBuddy 实际读取的 `models.json`，校验 JSON 后重新打开 WorkBuddy。 |
| 对话正常，但没有执行文件工具 | 未启用工具调用，或未授予目录访问权限 | 确认「工具调用」已勾选，并允许 WorkBuddy 访问测试目录。 |

## 相关文档

* [Step Plan 快速开始](https://platform.stepfun.com/docs/zh/step-plan/quick-start.md)：账号准备、接口地址与工具接入参数。
* [推理模型](https://platform.stepfun.com/docs/zh/guides/developer/reasoning.md)：`reasoning_effort` 等推理强度参数的用法。
* [Step 5 Preview](https://platform.stepfun.com/docs/zh/guides/models/step-5-preview.md)：上下文窗口、输入类型与能力参数。


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