WorkBuddy

WorkBuddy 是支持自定义模型接入与工具调用的桌面 AI 客户端。通过自定义模型接入 Step Plan 后，可以在 WorkBuddy 中调用 Step 系列模型。 WorkBuddy 已上架 Step 5 Preview，可在模型列表中选择。本文介绍通过自定义模型接入 Step Plan 的方式，调用消耗您自己的 Step Plan 额度。

前置条件

已开通 Step Plan 订阅，并在阶跃星辰开放平台创建 API Key。

在 App 内添加模型

打开模型设置

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

填写连接信息

本文以 Step 5 Preview 为例。Step Plan 支持的其他模型也可以按同样方式添加，模型清单见 Step Plan 概述。

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

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

设置模型能力

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

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

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

保存并发送第一条消息

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

请只回复：连接成功

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

通过配置文件添加模型

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

[
  {
    "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。

验证工具调用

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

请使用文件工具列出当前目录的一级文件和文件夹，并告诉我一共有多少项。只读取，不修改或删除文件。

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

直接验证 API

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

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 访问测试目录。

Agent 与工具

静态托管

工具接入

迁移

文本与推理

请求与上下文

文件与知识

视觉理解

语音

错误与排障

前置条件

在 App 内添加模型

通过配置文件添加模型

验证工具调用

直接验证 API

问题排查

相关文档

​前置条件

​在 App 内添加模型

​通过配置文件添加模型

​验证工具调用

​直接验证 API

​问题排查

​相关文档

前置条件

在 App 内添加模型

通过配置文件添加模型

验证工具调用

直接验证 API

问题排查

相关文档