使用 WorkBuddy 集成 GenStudio API

AI 助手

WorkBuddy 是面向桌面办公场景的智能体客户端，支持在设置中添加自定义模型，通过 OpenAI 兼容协议调用第三方 API 服务。本文指导在 WorkBuddy 中接入 GenStudio 通用 LLM API，使对话和智能体任务使用 GenStudio 上的模型。

本文先按最少步骤完成一次对话，再说明如何按模型调整图片输入、思考模式等配置，最后介绍网络限制和常见问题的排查。

本文基于 WorkBuddy macOS 桌面客户端 5.9.3 的设置界面。其他版本的界面措辞可能略有差异，配置项含义保持一致。

快速开始

以下步骤使用 deepseek-v4.1-flash-1017 作为示例模型，并按该模型的能力填写全部 高级配置。使用其他模型时，见按模型调整配置。

准备 API Key

创建以 sk- 为前缀的 GenStudio 通用 API Key。详见 GenStudio API 快速集成。

获取通用 API Key

注意

GenStudio 通用 LLM API 服务有 API 频率限制。租户在 GenStudio 的服务等级决定了 API 调用是否计费，以及享受的 API 频率上限。详见 LLM API 计费规则。

安装 WorkBuddy

从 WorkBuddy 官网 下载对应平台的桌面客户端并安装，然后启动 WorkBuddy。

添加自定义模型

在设置中添加一个自定义模型，指向 GenStudio 的 OpenAI 兼容接口。保存后，该模型进入自定义模型列表，可在对话中选择；配置保存在本地 ~/.workbuddy/models.json 文件中。

1. 打开 WorkBuddy 设置：在菜单栏选择 WorkBuddy＞设置…。

2. 在左侧导航选择 模型，在 自定义模型 区域选择 添加模型。

3. 供应商 选择 自定义：

   • 供应商 默认不是 自定义，需要手动改选；自定义 在下拉列表的 其他 分组中。
   • WorkBuddy 的自定义模型仅支持 OpenAI 兼容协议 API；内置供应商使用各自固定的接入地址，不能指向 GenStudio。

4. 填写接入信息：

   • 接口地址：填写 https://cloud.infini-ai.com/maas/v1/chat/completions。
   • API Key：填写准备 API Key中创建的 API Key。
   • 模型名称：填写 deepseek-v4.1-flash-1017。必须与 GenStudio 模型卡片显示的模型 ID 完全一致，否则请求返回模型不存在。

   警告

   ~/.workbuddy/models.json 以明文保存 API Key，文件权限为 0600，仅当前用户可读。不要把该文件提交到代码仓库、写入镜像或分享给他人；不再使用该模型时，在 自定义模型 列表中选择 删除。

5. 选择 测试连接，确认 接口地址 和 API Key 可用：

   • 测试连接 只发送一条固定的短请求，不带工具和思考相关参数，所以不能证明工具调用、图片输入和思考模式的设置会被接受，这些以对话中的实际回复为准。

6. 按 deepseek-v4.1-flash-1017 的能力配置 高级配置：

   • 工具调用：保持开启（默认值）。

   • 图片输入：开启。该模型的 model_type 为 多模态模型，支持图片输入。

   • 思考模式：开启。该模型默认开启思考，支持 low、high、max 三档推理强度，默认 high，见使用 DeepSeek 的 thinking 参数。开启后出现以下选项：

     • 仅思考模式：保持关闭（默认值）。
     • 允许关闭思考：保持开启（默认值）。该模型可以显式关闭思考。
     • 默认思考强度：选择 高。
     • 支持的思考强度：勾选 低、高、极致。
     • 允许关闭思考 保持开启时，WorkBuddy 5.9.3 的对话请求不携带 reasoning_effort，默认思考强度 和 支持的思考强度 暂不影响请求。先按模型能力填好，关闭 允许关闭思考 后即生效，见思考模式。

   • 自定义协议：保持关闭（默认值）。

   • 输入：填写 1048576（context_length，上下文窗口上限）。该值超过快捷档位的最大值 256K，需要在输入框中手动填写。输入、输出的取值都来自模型列表接口，查询方法见选择模型并确认取值。

   • 输出：填写 393216（max_output_length，单次回复上限）。回复不需要这么长时，也可以选择更小的快捷档位，不要超过该值。

7. 选择 保存。

需要使用其他模型，或想了解每一项配置的含义和对请求的影响，见按模型调整配置。

发送第一条消息

添加完成后，用这个模型发送一条消息，确认配置可用。

1. 选择 新建任务。

2. 在输入框右下角打开显示当前模型名称的下拉框，在列表下部的 自定义模型 分组中选择 deepseek-v4.1-flash-1017。

3. 第一条消息不需要选择工作空间，发送：

   你好，请用一句话介绍你自己。

4. 回复上方显示 已完成，回复下方显示的模型名称是 deepseek-v4.1-flash-1017，说明这条对话已经使用 GenStudio 上的这个模型。

没有收到回复或提示错误，见排查常见问题。

按模型调整配置

快速开始已按 deepseek-v4.1-flash-1017 填写了全部 高级配置。不同模型在图片输入、思考模式和 Token 上限上的取值不同，使用其他模型时，按本节说明调整。

查看 API 接入信息

WorkBuddy 通过 GenStudio 的 OpenAI 兼容接口调用模型：

• OpenAI (OpenAI Compatible)

  • Base URL: https://cloud.infini-ai.com/maas/v1

  • Endpoints

    • Create Chat Completion: /chat/completions
    • List Models: /models

WorkBuddy 的 接口地址 填写 Base URL 加 /chat/completions。

选择模型并确认取值

填写 输入、输出 和 图片输入 前，先确认模型 ID、上下文窗口和多模态能力。可以用以下任一方式查看：

• 模型广场：打开对应模型卡片查看，不需要调用接口。

  打开模型广场

• 模型列表接口：调用 /models，从对应模型条目中读取 id（模型 ID）、context_length（上下文窗口 Token 数）、max_output_length（单次回复的 Token 上限）和 model_type（模型类型）：

  curl --request GET \
    --url 'https://cloud.infini-ai.com/maas/v1/models' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer sk-xxxxxxxxxx'

  模型列表接口兼容 OpenAI 的模型列表响应，并在每个模型对象中额外返回 context_length、max_output_length 和 model_type。响应的 data 数组中，deepseek-v4.1-flash-1017 的条目如下：

  {
    "id": "deepseek-v4.1-flash-1017",
    "object": "model",
    "created": 0,
    "owned_by": "",
    "max_output_length": 393216,
    "context_length": 1048576,
    "model_type": "多模态模型"
  }

本文以下列三个模型为例，取值来自它们在 /models 中的返回。配置时请以当前账号实际返回的模型条目为准：

• glm-5.3

  • 输入：1048576（context_length，上下文窗口上限）。
  • 输出：不超过 131072（max_output_length，单次回复上限）。
  • 图片输入：保持关闭。model_type 为 大语言模型，不支持图片输入，发送 image_url 会返回 HTTP 400，错误信息为 Bad Request: [message type 'image_url' is not supported]。
  • 思考：始终开启思考，thinking.type 设为 "disabled" 会返回 HTTP 400。开启 思考模式 时，允许关闭思考 关闭。

• kimi-k3

  • 输入：1048576。
  • 输出：不超过 1048576。
  • 图片输入：可开启。model_type 为 多模态模型，支持图片输入。
  • 思考：始终推理，使用顶层 reasoning_effort 控制强度，不通过 thinking.type 控制。开启 思考模式 时，允许关闭思考 关闭。

• deepseek-v4.1-flash-1017

  • 输入：1048576。
  • 输出：不超过 393216。
  • 图片输入：可开启。model_type 为 多模态模型，支持图片输入。
  • 思考：默认开启思考且可显式关闭，thinking.type 设为 "disabled" 后响应不含 reasoning_content。开启 思考模式 时，允许关闭思考 可开启。

建议显式填写 输入 和 输出。三个模型的上下文窗口都超过 输入 快捷档位的最大值 256K，需要在输入框中手动填写 context_length；max_output_length 也都超过 输出 快捷档位的最大值 64K，输出 可按任务需要的回复长度选择快捷档位，或直接填写不超过 max_output_length 的数值。

注意

以上模型仅为示例。GenStudio 当前可用的模型及其 ID，以模型广场或模型列表接口（/models）的返回结果为准。

高级配置

高级配置 声明 WorkBuddy 可以为该模型启用的能力和 Token 上限。开关只控制 WorkBuddy 侧的行为，不能为模型增加它本身不具备的能力。每项配置保存后写入 ~/.workbuddy/models.json 中对应的字段。也可以直接编辑该文件：WorkBuddy 5.9.3 检测到文件变化后会自动重新加载，之后新建的任务使用新配置，不需要重启。

• 工具调用：默认开启。执行需要读写文件、运行命令的智能体任务时保持开启；目标模型不支持工具调用时关闭。

  • 写入 supportsToolCall。
  • 验证：发送一项需要读取文件的任务，WorkBuddy 能调用工具并继续生成回复。

• 图片输入：默认关闭。目标模型支持图片输入时开启，之后可以在对话中附带截图或图片文件。是否支持图片输入以模型卡片的说明为准，见选择模型并确认取值。

  • 写入 supportsImages。
  • 验证：开启后附带一张截图，不会提示当前模型不支持图片。

• 思考模式：默认关闭。开启后按思考模式配置强度档位。上文三个示例模型的 允许关闭思考 等选项都在开启后才会出现，请先开启。

  • 写入 supportsReasoning；思考相关配置另存于 reasoning 对象。

• 自定义协议：默认关闭。关闭时，WorkBuddy 使用标准 /chat/completions 路径，并自动校验、补全接口地址；开启后直接使用填写的接口地址，跳过路径校验与自动补全，适用于经网关或代理的非标准路径。接入 GenStudio 时保持默认关闭。

  • 例如只填写以 /v1 结尾的 Base URL 时，WorkBuddy 5.9.3 仍会把请求发往 /v1/chat/completions。
  • 写入 useCustomProtocol。

• 输入：上下文窗口 Token 上限。添加模型时为空，输入框提示 使用提供商默认值；也可选择 32K、64K、128K、256K 快捷档位。

  • 写入 maxInputTokens；留空时不写入该字段。
  • WorkBuddy 按该值估算对话历史的占用，决定何时自动压缩历史，不会作为参数发送给模型。

• 输出：单次回复的 Token 上限。添加模型时为空，输入框提示 使用提供商默认值；也可选择 8K、16K、32K、64K 快捷档位。

  • 写入 maxOutputTokens；留空时不写入该字段。
  • 填写后，对话请求携带该值作为 max_tokens（部分模型为 max_completion_tokens，GenStudio 对两者的处理相同）；留空时请求不携带该参数，回复长度上限由模型服务的默认值决定。

思考模式

开启 思考模式 后，WorkBuddy 展示以下配置。这些字段保存在 ~/.workbuddy/models.json 的 reasoning 对象中。

• 仅思考模式：默认关闭。开启后模型只返回思考内容。

• 允许关闭思考：默认开启。关闭后该模型在 WorkBuddy 中始终思考。

  • 关闭时写入 canDisableThinking: false。
  • 开启时，对话请求不携带 reasoning_effort，下面两项不会影响对话请求；关闭后，对话请求才携带 reasoning_effort。

• 默认思考强度：默认为自动，也可选择低、中、高、超高、极致。

  • 写入 defaultEffort；保持自动时不写入该字段。

• 支持的思考强度：勾选目标模型实际支持的档位。WorkBuddy 的对话界面不提供强度选择，请求携带的强度由本项和 默认思考强度 决定。

  • 写入 supportedEfforts；一项都不勾选时不写入该字段。

界面档位在 ~/.workbuddy/models.json 中保存为以下取值，与 GenStudio 请求参数 reasoning_effort 的取值同名：

• 低 写入 low
• 中 写入 medium
• 高 写入 high
• 超高 写入 xhigh
• 极致 写入 max

允许关闭思考 关闭后，对话请求携带的 reasoning_effort 由 默认思考强度 决定；选择未勾选的档位时，WorkBuddy 不会原样发送。以快速开始中的 deepseek-v4.1-flash-1017 为例，支持的思考强度 勾选低、高、极致时，WorkBuddy 5.9.3 的对话请求携带的取值如下：

• 默认思考强度 为 高 或保持自动：携带 high。
• 默认思考强度 为 极致：携带 max。

警告

各模型对强度取值的校验并不一致：

• glm-5.3 严格校验，发送 medium、xhigh、minimal 或 none 都返回 HTTP 400，错误信息为 'reasoning_effort' must be one of: 'low', 'high', 'max' 或 invalid reasoning_effort: value must be 'low', 'high', or 'max' for this model.。
• kimi-k3 和 deepseek-v4.1-flash-1017 会接受 medium 和 xhigh，但两者的文档都只声明 low、high、max 三档，接口接受不代表按该档位生效。

为避免请求被拒绝或实际强度与预期不一致，配置 支持的思考强度 时只勾选 低、高、极致，默认思考强度 也只选择这三档之一，或保持自动。其他模型请按各自文档确认档位。

另有两点说明：

• 需要固定档位时，关闭 允许关闭思考，并把 默认思考强度 设为该模型文档声明的档位，在同一会话中保持不变。Kimi K3 的文档指出，切换档位会影响前缀缓存命中。
• 发送消息时，WorkBuddy 还会向当前模型发出一个生成对话标题的请求，该请求固定携带 reasoning_effort: "none"，与 思考模式、允许关闭思考 的设置无关。glm-5.3 不接受 none（见上文告警），这个请求会返回 HTTP 400；WorkBuddy 5.9.3 在该请求被拒绝时不会提示错误，对话照常进行。

网络与沙箱限制

两项全局设置会影响 WorkBuddy 访问 GenStudio 端点：

• 网络代理：位于 通用 分区，默认为直接连接。企业网络或代理环境下直连失败时，可切换连接方式，修改后立即生效。
• 网络安全：位于 安全中心 的 沙箱安全 下，按优先级控制沙箱内任务可访问的 URL 和域名。

警告

沙箱内执行的智能体任务受 网络安全 规则约束。如果规则未放行 GenStudio 的 API 域名，任务内对该端点的请求会被拒绝，即使 测试连接 通过。出现此类问题时，在 网络安全 中为对应域名添加放行规则。

排查常见问题

按现象找到对应条目。测试连接 通过只说明地址和密钥可用，模型名称、思考强度、图片等设置是否被接受，要看对话中的实际回复。错误提示里带有 HTTP 状态码或错误码时，也可以在 GenStudio LLM API 错误码中查对应条目。

• 测试连接失败

  • 核对 接口地址 和 API Key，见添加自定义模型。
  • 确认密钥在控制台中未删除、未过期、未被禁用，账户余额和服务等级满足当前调用。
  • 直连失败时，在网络与沙箱限制中检查 网络代理。

• 请求返回模型不存在

  • 核对 模型名称，必须与模型卡片显示的模型 ID 完全一致。
  • 用模型列表接口确认当前账号的返回中包含该模型 ID。

• 返回 HTTP 400，错误信息提到 reasoning_effort 只能是 low、high 或 max

  • 思考强度取值被模型拒绝。支持的思考强度 和 默认思考强度 只选低、高、极致，见思考模式。

• 发送图片时返回 HTTP 400，错误信息含 message type 'image_url' is not supported

  • 当前模型不支持图片输入。关闭 图片输入 或换用支持图片输入的模型，见选择模型并确认取值。

• 返回 HTTP 400，错误信息含 max_tokens should be less or equal to

  • 输出 超过了模型的 max_output_length。改为不超过该值的数值，见选择模型并确认取值。

• 工具调用失败、回复被截断

  • 回到高级配置，检查 工具调用 开关以及 输入、输出 上限。

• 返回 HTTP 401、402、403 或 429

  • 401：API Key 无效、已过期或已被禁用。
  • 402：账户余额或预算不满足调用条件。
  • 403：当前租户或账号没有该模型的访问权限，请确认模型已开通。
  • 429：触发频率限制，降低请求频率，见 API 频率限制。

• 沙箱内任务访问不到 GenStudio

  • 在 网络安全 中放行 GenStudio 的 API 域名，并确认任务是否运行在沙箱内，见网络与沙箱限制。

相关文档

更多关于 GenStudio API 的使用说明，请参考以下文档。

• GenStudio LLM API 错误码
• 视觉语言模型与图像理解
• 为 Chat Completions 请求选择推理参数
• 使用 GLM 的 thinking 参数
• 使用 Kimi 的 thinking 和 reasoning_effort
• 使用 DeepSeek 的 thinking 参数