接入 WorkBuddy/CodeBuddy

WorkBuddy/CodeBuddy 是面向开发者的专业 AI Agent 与编程助手工具，核心优势在于支持本地模型配置、无缝集成主流 IDE、项目级上下文感知、工具调用能力强，可深度融入你的日常开发流程，实现代码生成、调试、重构、文档生成全流程的 AI 赋能。

它支持通过 OpenAI 兼容的 Chat Completions API 接入 DeepSeek V4 模型，无需修改工具核心代码，只需简单配置即可使用 DeepSeek 的强推理能力和百万上下文窗口，大幅提升编码效率。

本教程将带你完成从安装到配置 DeepSeek 模型的全流程，看完即可在 WorkBuddy/CodeBuddy 中流畅使用 DeepSeek 模型。

1. 安装 WorkBuddy/CodeBuddy

操作目的：完成 WorkBuddy/CodeBuddy 基础环境部署，生成配置目录用于存放自定义模型配置。

• 安装并登录 WorkBuddy/CodeBuddy。 操作说明：从官方网站下载对应操作系统的安装包，按照向导完成安装并登录账号，安装完成后启动一次工具确认运行正常。
• 至少打开一次项目目录，让应用创建本地配置目录。 操作说明：打开任意项目目录后，工具会自动生成 .codebuddy 配置目录，用于存放自定义模型配置、项目级设置等内容。配置目录路径：Windows 为 C:\Users\<你的用户名>\.codebuddy，macOS/Linux 为 ~/.codebuddy，若未自动生成可手动创建。
• 前往 DeepSeek 开放平台 获取 API Key。 操作说明：获取调用 DeepSeek 接口的身份凭证，妥善保管避免泄露。

2. 配置本地模型

操作目的：通过 models.json 配置文件添加 DeepSeek 模型，支持用户级全局配置和项目级单独配置两种方式。

• 用户级配置：对所有项目生效，适合只需要一套配置的用户，创建或编辑用户级配置文件：

C:\Users\<你的用户名>\.codebuddy\models.json

• 项目级配置：仅对当前项目生效，适合不同项目需要使用不同模型、不同配置的场景，会覆盖用户级配置的相同字段，创建或编辑项目级配置文件：

<你的项目>\.codebuddy\models.json

先将 DeepSeek API Key 设置为环境变量（避免明文存储在配置文件中泄露）：

setx DEEPSEEK_API_KEY "<your DeepSeek API Key>"

操作说明：setx 是 Windows 下持久化环境变量的命令，执行后需要重启终端或电脑才能生效；若需要立即生效，可在当前 PowerShell 窗口执行 $env:DEEPSEEK_API_KEY="<your DeepSeek API Key>"。macOS/Linux 用户可将 export DEEPSEEK_API_KEY="<your Key>" 写入 Shell 配置文件完成持久化。

然后写入以下配置（完全保留原有参数，无修改）：

{
  "models": [
    {
      "id": "deepseek-v4-pro",
      "name": "DeepSeek V4 Pro",
      "vendor": "DeepSeek",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false,
      "relatedModels": {
        "lite": "deepseek-v4-flash",
        "reasoning": "deepseek-v4-pro"
      }
    },
    {
      "id": "deepseek-v4-flash",
      "name": "DeepSeek V4 Flash",
      "vendor": "DeepSeek",
      "url": "https://api.deepseek.com/v1/chat/completions",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": [
    "deepseek-v4-pro",
    "deepseek-v4-flash"
  ]
}

配置字段说明：

• id：模型唯一标识，必须与 DeepSeek 官方模型 ID 严格一致，否则会提示模型不存在。
• name：模型在选择器中显示的名称，可根据喜好自定义。
• vendor：模型厂商，用于分类显示。
• url：DeepSeek Chat Completions 接口地址，必须带 /v1 后缀，与其他工具的配置不同，请注意不要遗漏。
• apiKey：从环境变量读取 DEEPSEEK_API_KEY 的值，若不使用环境变量也可直接填入实际的 API Key，但不推荐，避免泄露。
• maxInputTokens/maxOutputTokens：模型输入输出长度限制，可根据需求调整，DeepSeek V4 最大支持 1M 上下文。
• supportsToolCall：指定模型支持工具调用，DeepSeek V4 支持工具调用，故设置为 true。
• supportsImages：指定模型不支持图片输入，DeepSeek V4 目前仅支持文本输入，故设置为 false。
• relatedModels：关联模型配置，方便快速在 Lite 和 Pro 版本之间切换。
• availableModels：指定要在模型选择器中显示的模型 ID，必须与前面定义的 id 对应。

请将 models.json 保存为 UTF-8 无 BOM。部分桌面版本在读取带 UTF-8 BOM 文件头的 JSON 时，可能会读取本地模型配置失败。Windows 用户使用记事本保存时，编码选择“UTF-8”（注意不是“UTF-8 with BOM”）；使用 VS Code 等编辑器时，右下角可查看编码格式，点击可切换为 UTF-8 无 BOM。

3. 重启并选择模型

操作目的：让工具重新读取新的模型配置文件，因为工具启动时只会加载一次配置，修改后必须重启才能生效。 完全退出 WorkBuddy/CodeBuddy（包括后台进程）后重新打开。 在模型选择器中选择：

DeepSeek V4 Pro
DeepSeek V4 Flash

选择后即可开始使用 DeepSeek 模型进行编码工作。

4. 可选：验证 API Key

操作目的：在配置前先验证 API Key 和网络是否正常，避免后续配置完成后才发现问题，节省排查时间。 Windows 用户可以在 PowerShell 中验证 API Key：

$env:DEEPSEEK_API_KEY="<your DeepSeek API Key>"

curl https://api.deepseek.com/v1/chat/completions `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer $env:DEEPSEEK_API_KEY" `
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"stream":false}'

验证成功预期结果：返回包含 choices 字段的 JSON 响应，其中包含模型返回的内容，说明 API Key、模型 ID、网络都正常；若返回 401 说明 API Key 错误，404 说明模型 ID 错误，429 说明请求频率超限或余额不足。

常见问题

• Authentication Fails 或 401：检查 apiKey 是否为真实 DeepSeek API Key。不要把接口 URL 填到 API Key 字段。 补充排查步骤：首先执行上述验证命令确认 API Key 有效，其次检查环境变量是否正确设置，重启终端后从终端启动 WorkBuddy/CodeBuddy，若桌面快捷方式启动不生效，可重启电脑或直接在配置文件中填入明文 API Key。
• 未找到模型 或 404：检查模型 id 是否严格写成 deepseek-v4-pro 或 deepseek-v4-flash。 补充排查步骤：确认配置文件中的 url 后缀为 /v1/chat/completions，不要遗漏 /v1；确认 DeepSeek 开放平台账号有对应模型的访问权限。
• 读取本地模型配置失败：检查 models.json 是否是合法 JSON，并保存为 UTF-8 无 BOM。 补充排查步骤：使用在线 JSON 校验工具验证 JSON 语法是否正确，检查是否存在缺少逗号、括号不匹配等问题；确认文件编码为 UTF-8 无 BOM。
• 模型选择器中不显示：完全重启 WorkBuddy/CodeBuddy，并确认文件放在 .codebuddy\models.json。 补充排查步骤：检查 availableModels 数组中是否包含对应模型的 id，确认文件路径正确（用户级或项目级的 .codebuddy 目录下），确认文件权限允许工具读取。
• UI 中直接显示 ${DEEPSEEK_API_KEY}：请从已设置 DEEPSEEK_API_KEY 的终端中重启 WorkBuddy/CodeBuddy。如果桌面端仍不展开环境变量，可以在 UI 或本地 models.json 中填入真实 API Key。 补充说明：桌面快捷方式启动时可能无法读取用户级环境变量，重启电脑后可解决，或直接在配置文件中填写明文 Key，注意不要将配置文件提交到代码仓库。

额外常见问题

1. 调用时返回 400 参数错误？ 排查步骤：检查配置文件中的 url 是否正确，是否带 /v1 后缀；检查 supportsToolCall 字段是否设置为 true。
2. 调用时响应缓慢？ 排查步骤：检查网络是否能正常访问 api.deepseek.com，国内用户可使用稳定的代理提升访问速度。

参考资料

• awesome-deepseek-agent
• WorkBuddy/CodeBuddy 官方文档