WorkBuddy / CodeBuddy 配置

WorkBuddy / CodeBuddy 支持通过本地模型配置文件添加自定义模型。请先完成客户端本身的安装、登录和启动；本页只介绍如何为 yuyuflow 配置模型，不包含安装脚本或脚本化环境变量设置。

推荐先验证通用 API

建议先阅读 LLM 配置，使用 cURL 验证 API Key、模型 ID 和 Chat Completions 地址，再把相同参数写入 models.json。

配置文件位置

客户端支持用户级和项目级配置：

级别	Windows 路径	适用场景
用户级	`C:\Users\<你的用户名>\.codebuddy\models.json`	为当前用户提供默认模型
项目级	`<项目目录>\.codebuddy\models.json`	只对某个项目覆盖或补充配置

如果客户端在其他操作系统运行，请按客户端显示的用户目录使用对应路径。项目级文件适合团队或单项目设置，但提交到仓库前必须确认其中没有真实凭证。

配置模型

将下面的示例保存为 models.json。模型 ID、上下文长度和输出上限必须以控制台实际可用值为准；示例中的模型名仅用于说明结构。

json

{
  "models": [
    {
      "id": "YOUR_PRIMARY_MODEL",
      "name": "yuyuflow 主模型",
      "vendor": "yuyuflow",
      "url": "https://art-api.yuyuflow.com/v1/chat/completions",
      "apiKey": "${API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false,
      "relatedModels": {
        "lite": "YOUR_FAST_MODEL",
        "reasoning": "YOUR_PRIMARY_MODEL"
      }
    },
    {
      "id": "YOUR_FAST_MODEL",
      "name": "yuyuflow 快速模型",
      "vendor": "yuyuflow",
      "url": "https://art-api.yuyuflow.com/v1/chat/completions",
      "apiKey": "${API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": [
    "YOUR_PRIMARY_MODEL",
    "YOUR_FAST_MODEL"
  ]
}

环境变量与密钥安全

${API_KEY} 只有在客户端明确支持环境变量展开时才会生效。若客户端没有展开变量，请使用其内置的安全凭证入口注入 API Key，不要把真实密钥直接写入项目文件、截图或公开仓库。

字段说明

字段	说明
`id`	请求时发送的模型 ID，必须与平台实际模型名完全一致。
`name`	在模型选择器中显示的名称，可按团队习惯命名。
`vendor`	模型供应商或平台标识，用于区分不同 provider。
`url`	OpenAI 兼容 Chat Completions 完整地址。
`apiKey`	API Key 或环境变量引用；不要填写带 `Bearer` 前缀的值。
`maxInputTokens`	客户端允许发送的最大输入令牌数，应不超过模型限制。
`maxOutputTokens`	客户端允许生成的最大输出令牌数，应不超过模型限制。
`supportsToolCall`	是否向客户端声明支持工具调用；只有平台和模型确实支持时才设为 `true`。
`supportsImages`	是否支持图像输入；不支持视觉模型时保持 `false`。
`relatedModels`	可选的模型关联关系，例如轻量模型和推理模型。关联值必须是已定义的 `id`。
`availableModels`	模型选择器展示和可选用的模型 ID 列表。

地址和协议规则

url 使用 OpenAI 兼容的 Chat Completions 协议：

text

https://art-api.yuyuflow.com/v1/chat/completions

如果 https://art-api.yuyuflow.com 本身已经以 /v1 结尾，应改为：

text

https://art-api.yuyuflow.com/chat/completions

最终地址只能包含一个 /v1。不要将 Codex 的 Responses API 地址或 Claude Code 的 Claude 兼容地址直接填入 WorkBuddy / CodeBuddy 的 url。

最小请求验证

在写入配置前，可以用占位符替换为本地安全存储的值后验证：

bash

curl -X POST "https://art-api.yuyuflow.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_PRIMARY_MODEL",
    "messages": [
      {"role": "user", "content": "请只回复 pong"}
    ]
  }'

收到正常的 assistant 响应后，再继续排查客户端配置。若平台要求其他请求路径或协议，请以平台 API 文档为准。

应用配置

确认 JSON 语法正确，文件保存为 UTF-8 无 BOM。
确认配置文件位于用户级或当前项目的 .codebuddy 目录。
完全退出 WorkBuddy / CodeBuddy，再重新打开客户端。
打开模型选择器，确认 availableModels 中的模型可见并选中目标模型。
发送一个简单请求，确认模型、鉴权和工具调用行为符合预期。

常见问题

`Authentication Fails` 或 `401`

检查 API Key 是否过期、令牌分组是否允许访问该模型，以及 apiKey 是否误写成带 Bearer 前缀的字符串。如果使用 ${API_KEY}，确认客户端确实支持环境变量展开。

模型返回 `404` 或模型不存在

确认 id 使用的是控制台显示的完整模型 ID，并检查 availableModels 和 relatedModels 中是否存在拼写错误。不要把模型展示名称当成请求 ID。

JSON 格式错误

使用 JSON 校验器检查逗号、引号、数组和对象括号。文件必须保存为 UTF-8 无 BOM，且不要在 JSON 中加入注释。

修改后模型没有出现

确认文件名为 models.json、目录名为 .codebuddy，并完全退出后重启客户端。项目级配置应放在当前打开项目的根目录下。

`${API_KEY}` 没有被展开

部分桌面客户端不会读取或展开环境变量引用。请改用客户端提供的安全凭证配置方式；不要因此把真实 API Key 提交到项目文件。

Chat Completions 与 Responses API 不匹配

WorkBuddy / CodeBuddy 的本页配置使用 /chat/completions 请求格式；Codex 配置使用 Responses API。请使用与客户端协议匹配的地址和配置，不要交叉复制。

请求地址出现重复 `/v1`

检查 https://art-api.yuyuflow.com 是否已经包含 /v1。基础地址和 url 后缀只能由一方负责拼接。

下一步可阅读 Agent 工具总览、CC-Switch 配置、Codex 配置或 Claude Code 配置。

WorkBuddy / CodeBuddy 配置​

配置文件位置​

配置模型​

字段说明​

地址和协议规则​

最小请求验证​

应用配置​

常见问题​