企业官网建设流程全解析

在 WorkBuddy/CodeBuddy 中通过本地 models.json 接入 DeepSeek V4 完整指南

【免费下载链接】awesome-deepseek-agent项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-agent

WorkBuddy/CodeBuddy 是支持自定义模型的 AI Agent 与编程助手，本指南演示如何通过其本地模型配置文件models.json，借助 OpenAI 兼容的 Chat Completions API 接入 DeepSeek V4（deepseek-v4-pro/deepseek-v4-flash）。读完本文你将掌握用户级与项目级配置的差异、环境变量的正确用法、完整 JSON 配置的每个字段含义，以及常见报错的排查方法。

接入原理：为什么需要本地模型配置文件

WorkBuddy/CodeBuddy 这类桌面 AI 助手通常会内置默认模型供应商，而接入第三方模型一般有两种途径：

• 在设置界面选择内置的 OpenAI 兼容供应商并手动填写 Base URL 与 API Key（适用于工具内置了该入口的场景）；
• 通过本地模型配置文件声明自定义模型，让模型出现在模型选择器中（适用于支持本地模型配置文件的场景，即本文所述方式）。

DeepSeek 官方开放平台提供了与 OpenAI Chat Completions 协议兼容的接口（https://api.deepseek.com/v1/chat/completions），因此任何支持 OpenAI 兼容协议与自定义模型配置的客户端都可以直接接入 DeepSeek V4 系列模型。本仓库（awesome-deepseek-agent）正是围绕"在主流 AI Agent / 编程助手中接入 DeepSeek-V4-Pro 与 DeepSeek-V4-Flash"整理的一系列接入指南，WorkBuddy/CodeBuddy 是其中以本地 JSON 配置文件方式接入的代表之一（参见 README 工具清单 中对应条目）。

第一步：安装 WorkBuddy/CodeBuddy 并准备 API Key

在开始配置前，按以下顺序完成准备工作：

1. 安装并登录 WorkBuddy/CodeBuddy。
2. 至少打开一次项目目录，让应用在本地创建自己的配置目录（例如 Windows 用户主目录下的.codebuddy目录），后续的models.json需要放置在该目录中。
3. 前往 DeepSeek 开放平台 获取 API Key，用于后续配置与验证。

提示：模型命名以当前仓库使用的deepseek-v4-pro与deepseek-v4-flash为准。仓库的 贡献规范 明确要求示例中的模型名必须使用当前名称，避免沿用已弃用的旧名称（如deepseek-chat/deepseek-reasoner）。

第二步：确定配置文件的位置（用户级 vs 项目级）

WorkBuddy/CodeBuddy 的本地模型配置通过models.json提供，支持两种作用域：

用户级配置（推荐，对所有项目生效）

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

项目级配置（仅对当前项目生效）

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

选择建议：日常使用推荐配置在用户级，一次配置全局可用；若只在某个特定项目中需要使用 DeepSeek 模型，或希望不同项目使用不同模型组合，则使用项目级配置。需要注意应用是先打开过一次项目目录后才会生成对应的本地配置目录，配置前请确保该目录已经存在。

第三步：将 API Key 设置为环境变量

为了让models.json中不出现明文密钥，推荐先把 API Key 写入环境变量。Windows 用户可在 PowerShell 中执行：

setx DEEPSEEK_API_KEY "<your DeepSeek API Key>"

setx会持久化该环境变量。注意：setx只对之后新打开的进程生效，当前已打开的终端或已运行的 WorkBuddy/CodeBuddy 需要重启后才能读取到新变量（详见下文"重启并选择模型"与"常见问题"部分）。

第四步：编写 models.json 完整配置

在.codebuddy目录下创建或编辑models.json，写入以下配置：

{ "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" ] }

字段含义与取值说明

关于 token 上限，仓库 贡献规范 提到 DeepSeek V4 模型支持最高约 100 万 token 的上下文，本指南示例中maxInputTokens取128000、maxOutputTokens取8192，是相对稳妥的客户端侧配置值；如果你的任务需要更长上下文，可结合工具的输入限制适当上调maxInputTokens，但需以 DeepSeek 开放平台当前公布的模型上下文能力为准。

保存编码要求（重要）

保存models.json时必须使用UTF-8 无 BOM编码。部分桌面版本在读取带有 UTF-8 BOM 文件头的 JSON 时，会出现"读取本地模型配置失败"的问题。多数代码编辑器（VS Code、Notepad++ 等）可在"另存为"时选择编码为UTF-8（不带 BOM）。

第五步：完全重启并选择模型

配置完成后：

1. 完全退出WorkBuddy/CodeBuddy（不是最小化到托盘，而是彻底退出进程），然后重新打开。
2. 在模型选择器中应能看到并选择：

DeepSeek V4 Pro DeepSeek V4 Flash

如果模型没有出现，请回到第二步确认文件路径是否为<配置作用域>\.codebuddy\models.json，并确认 JSON 格式合法。

第六步（可选）：在 PowerShell 中验证 API Key

在正式使用前，Windows 用户可以先在 PowerShell 中直接调用一次 Chat Completions 接口，验证 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}'

如果请求成功返回正常 JSON 响应，说明 API Key 与模型名都有效；如果返回401或404，请对照下一节的排查表处理。

常见问题排查表

小结：接入流程回顾

整个接入过程可以概括为四步闭环：安装登录并打开一次项目 → 把 API Key 写入环境变量 → 编写 UTF-8 无 BOM 的models.json（用户级或项目级）→ 完全重启后在模型选择器中选择 DeepSeek V4 模型。遇到问题时，优先检查"密钥是否正确、模型 id 是否拼写精确、JSON 是否合法且无 BOM、路径是否位于.codebuddy下"这四个最容易出错的环节。

本指南的原始文档位于 docs/workbuddy.md（简体中文版见 docs/workbuddy.zh-CN.md），仓库中还有其他工具（Cline、Cherry Studio、LobeHub 等）的 DeepSeek 接入指南，可在 README 工具清单 中按需查阅。

【免费下载链接】awesome-deepseek-agent项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-agent