WorkBuddy/CodeBuddy 接入 DeepSeek V4 完全指南models.json 本地模型配置、环境变量与常见排障【免费下载链接】awesome-deepseek-agent项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-agent本文是 awesome-deepseek-agent 仓库中的 WorkBuddy/CodeBuddy 接入指南 的深度展开版讲解如何通过 WorkBuddy/CodeBuddy 的本地模型配置文件.codebuddy\models.json接入 DeepSeek V4deepseek-v4-pro/deepseek-v4-flash走 OpenAI 兼容的 Chat Completions API 完成对话与编程辅助。读完本文你将掌握用户级与项目级配置文件的差异、完整字段语义、API Key 环境变量展开机制、PowerShell 连通性验证方法以及 401 / 404 / 配置读取失败等常见错误的排查思路。一、接入原理OpenAI 兼容的 Chat CompletionsWorkBuddy/CodeBuddy 是一款 AI Agent 与编程助手工具。在仓库首页的工具表中它被定位为「支持自定义 OpenAI 兼容模型配置的 AI Agent 与编程助手」见 README.zh-CN.md即它本身不内置 DeepSeek 厂商选项而是通过本地模型配置文件声明自定义模型再由客户端把请求转发到 OpenAI 兼容的 Chat Completions 端点。整个接入链路可以概括为WorkBuddy/CodeBuddy模型选择器 │ 读取 .codebuddy\models.json ▼ 自定义模型定义id / url / apiKey / token 上限 / 能力开关 │ OpenAI 兼容 Chat Completions 请求 ▼ https://api.deepseek.com/v1/chat/completionsDeepSeek API这一模式与仓库内其他工具如 Pi 的 models.json的接入思路一致在客户端声明模型元数据把请求指向统一的 OpenAI 兼容端点。只要models.json写得正确、API Key 有效模型就会出现在 WorkBuddy/CodeBuddy 的模型选择器中。二、准备工作安装、登录与 API Key开始配置前按顺序完成以下三步安装并登录 WorkBuddy/CodeBuddy确保客户端处于可用状态。至少打开一次项目目录。这一步的目的是让应用在工作目录下创建本地配置目录即.codebuddy后续模型配置文件的存放位置才有依托。获取 DeepSeek API Key。前往 DeepSeek 开放平台platform.deepseek.com 的 API Keys 页面创建密钥后续既会写入环境变量也会被models.json引用。提示API Key 属于敏感凭据建议优先通过环境变量注入见下文${DEEPSEEK_API_KEY}展开机制避免把密钥明文散落在配置文件里。三、编写 models.json完整配置与逐字段解析3.1 配置文件放在哪里用户级与项目级WorkBuddy/CodeBuddy 支持两种配置层级层级路径生效范围用户级C:\Users\你的用户名\.codebuddy\models.json所有项目项目级你的项目\.codebuddy\models.json仅当前项目想让 DeepSeek 在任何项目里都可用编辑用户级文件只想让某个项目使用 DeepSeek、避免影响其他项目就创建项目级文件。3.2 先把 API Key 写入环境变量在 PowerShell 中执行setx会持久化到用户环境变量setx DEEPSEEK_API_KEY your DeepSeek API Key注意setx只对之后新开的终端生效当前已打开的窗口不会立即读到该变量。因此设置完成后请从新终端启动 WorkBuddy/CodeBuddy确保 UI 进程继承到环境变量。3.3 完整配置文件逐字可复制{ 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 ] }3.4 字段语义详解对上述 JSON 的每个关键字段含义与注意事项如下字段说明注意事项id模型标识即请求体里的model参数必须与 DeepSeek API 的模型名严格一致deepseek-v4-pro或deepseek-v4-flash大小写与连字符都不能写错name在模型选择器中显示的名称可自定义如DeepSeek V4 Pro仅影响展示vendor厂商标识示例为DeepSeek用于在 UI 中归类urlOpenAI 兼容 Chat Completions 端点固定为https://api.deepseek.com/v1/chat/completions不要把该 URL 填到apiKey字段apiKey鉴权密钥支持${ENV_VAR}语法从环境变量展开本例为${DEEPSEEK_API_KEY}也可直接填明文maxInputTokens单次请求允许的输入 token 上限示例值为128000是文档给出的保守可用值maxOutputTokens单次回复的最大输出 token 数示例为8192supportsToolCall是否启用函数/工具调用能力true时允许 Agent 调用工具如文件读写、命令执行是编程助手的关键能力supportsImages是否支持图像输入DeepSeek V4 文本模型不支持固定为falserelatedModels关联模型映射从配置结构看lite指向更快的deepseek-v4-flashreasoning指向更强的deepseek-v4-pro用于在「轻量/推理」档位间切换availableModels模型选择器中开放可用的模型 id 列表只有出现在此列表中的id才会被客户端展示3.5 relatedModels 与 availableModels两条列表的分工availableModels决定「哪些模型可选」。它引用的id必须都在models数组中有对应定义否则会出现选择了模型却无法发起请求的情况。relatedModels定义模型之间的「关联档位」lite表示轻量快速档映射到 Flashreasoning表示深度推理档映射到 Pro。可以推断当编码助手需要快速补全或深度思考两种模式时会依据这组映射在不同模型间切换。3.6 保存编码UTF-8 无 BOM 是硬要求请将models.json保存为 UTF-8 无 BOM 编码。部分桌面版本在读取带 UTF-8 BOM 文件头的 JSON 时会直接判定为「本地模型配置读取失败」。保存要点在 VS Code 中右下角编码按钮选择UTF-8而非UTF-8 with BOM在 Windows 记事本中另存为时编码选择UTF-8新版记事本默认即无 BOM保存前可用任意 JSON 校验工具确认文件是合法 JSON无多余逗号、引号闭合。四、重启应用并选择模型完全退出WorkBuddy/CodeBuddy不是最小化也不是关窗口后立刻重开要确保进程退出、配置被重新加载然后重新打开。打开模型选择器此时应能看到两个自定义模型DeepSeek V4 Pro DeepSeek V4 Flash选中一个模型即可开始对话或编程任务。如果模型选择器中始终不显示多半是配置文件路径不对应放在.codebuddy\models.json或 JSON 解析失败可参考第六节排查。五、可选验证在 PowerShell 中直接调用 API在动手写配置之前或排障时可以用一条curl命令独立验证「API Key 是否有效、模型名是否写对」把问题从客户端配置中剥离出来$env:DEEPSEEK_API_KEYyour 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}这条命令的要点Authorization: Bearer $env:DEEPSEEK_API_KEY—— 用环境变量值作为 Bearer Token验证环境变量是否设置正确model:deepseek-v4-flash—— 直接以模型 id 发起请求验证模型名拼写stream:false—— 关闭流式输出便于一次性看到完整响应。判定标准请求返回包含choices的成功 JSON说明 API Key 与模型名均可用问题一定出在客户端配置上返回401说明鉴权失败返回404说明模型名错误。六、常见问题排查以下排查表直接对应配置过程中最常遇到的五类现象现象根因处理Authentication Fails或401API Key 无效或把接口 URL 误填到了 API Key 字段核对apiKey是否为真实的 DeepSeek API Key检查是否误把url值填入apiKey确认环境变量DEEPSEEK_API_KEY确实已设置未找到模型或404模型 id 与 API 侧模型名不一致严格使用deepseek-v4-pro或deepseek-v4-flash注意大小写与连字符读取本地模型配置失败JSON 非法或文件带有 UTF-8 BOM 头用校验工具确认 JSON 语法重新保存为 UTF-8 无 BOM模型选择器中不显示配置未被加载完全重启 WorkBuddy/CodeBuddy确认文件路径为.codebuddy\models.json用户级或项目级UI 中直接显示${DEEPSEEK_API_KEY}字样客户端未继承到环境变量变量未被展开从已设置DEEPSEEK_API_KEY的终端中重启应用若桌面端仍不展开变量可在 UI 或本地models.json中直接填入真实 API Key其中「UI 直接显示${DEEPSEEK_API_KEY}」最常见的原因是setx之后仍然从旧终端启动应用导致新进程没有继承环境变量。按照「新开终端 → 启动应用」的顺序操作即可避免。七、与仓库规范的呼应模型命名、上下文与推理档位本仓库的 CONTRIBUTING.md 沉淀了 DeepSeek 接入的通用约定可作为配置 WorkBuddy/CodeBuddy 时的背景知识模型命名DeepSeek 于 2026 年 4 月完成模型更名V3 时代的deepseek-chat/deepseek-reasoner/deepseek-coder已弃用当前正确名称为deepseek-v4-pro与deepseek-v4-flash见 CONTRIBUTING.md。这也是models.json中id必须严格使用这两个名字的原因。上下文窗口DeepSeek V4 系列支持最高 100 万 token 上下文见 CONTRIBUTING.md。本文示例中的maxInputTokens: 128000是文档给出的保守值如果你的 WorkBuddy/CodeBuddy 版本支持更大的输入长度可以在客户端允许范围内酌情调大。推理强度DeepSeek V4 Pro 支持max/high多档推理强度仓库规范建议以max档位获得最佳编码体验见 CONTRIBUTING.md。若你的 WorkBuddy/CodeBuddy 版本暴露了推理强度相关控制项优先使用max档。小结WorkBuddy/CodeBuddy 接入 DeepSeek V4 的核心就三步写好.codebuddy\models.json用户级或项目级→ 用环境变量注入 API Key → 完全重启并选择模型。遇到问题先对照第五节用curl独立验证 API Key 与模型名再回到第六节的排查表逐项核对就能在几分钟内完成接入。更多工具的 DeepSeek 接入指南可返回仓库首页 README.zh-CN.md 继续浏览本文对应的原始精简版文档见 workbuddy.zh-CN.md英文版见 workbuddy.md。【免费下载链接】awesome-deepseek-agent项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 WorkBuddy/CodeBuddy 接入 DeepSeek V4 完全指南：models.json 本地模型配置、环境变量与常见排障
WorkBuddy/CodeBuddy 接入 DeepSeek V4 完全指南models.json 本地模型配置、环境变量与常见排障【免费下载链接】awesome-deepseek-agent项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-agent本文是 awesome-deepseek-agent 仓库中的 WorkBuddy/CodeBuddy 接入指南 的深度展开版讲解如何通过 WorkBuddy/CodeBuddy 的本地模型配置文件.codebuddy\models.json接入 DeepSeek V4deepseek-v4-pro/deepseek-v4-flash走 OpenAI 兼容的 Chat Completions API 完成对话与编程辅助。读完本文你将掌握用户级与项目级配置文件的差异、完整字段语义、API Key 环境变量展开机制、PowerShell 连通性验证方法以及 401 / 404 / 配置读取失败等常见错误的排查思路。一、接入原理OpenAI 兼容的 Chat CompletionsWorkBuddy/CodeBuddy 是一款 AI Agent 与编程助手工具。在仓库首页的工具表中它被定位为「支持自定义 OpenAI 兼容模型配置的 AI Agent 与编程助手」见 README.zh-CN.md即它本身不内置 DeepSeek 厂商选项而是通过本地模型配置文件声明自定义模型再由客户端把请求转发到 OpenAI 兼容的 Chat Completions 端点。整个接入链路可以概括为WorkBuddy/CodeBuddy模型选择器 │ 读取 .codebuddy\models.json ▼ 自定义模型定义id / url / apiKey / token 上限 / 能力开关 │ OpenAI 兼容 Chat Completions 请求 ▼ https://api.deepseek.com/v1/chat/completionsDeepSeek API这一模式与仓库内其他工具如 Pi 的 models.json的接入思路一致在客户端声明模型元数据把请求指向统一的 OpenAI 兼容端点。只要models.json写得正确、API Key 有效模型就会出现在 WorkBuddy/CodeBuddy 的模型选择器中。二、准备工作安装、登录与 API Key开始配置前按顺序完成以下三步安装并登录 WorkBuddy/CodeBuddy确保客户端处于可用状态。至少打开一次项目目录。这一步的目的是让应用在工作目录下创建本地配置目录即.codebuddy后续模型配置文件的存放位置才有依托。获取 DeepSeek API Key。前往 DeepSeek 开放平台platform.deepseek.com 的 API Keys 页面创建密钥后续既会写入环境变量也会被models.json引用。提示API Key 属于敏感凭据建议优先通过环境变量注入见下文${DEEPSEEK_API_KEY}展开机制避免把密钥明文散落在配置文件里。三、编写 models.json完整配置与逐字段解析3.1 配置文件放在哪里用户级与项目级WorkBuddy/CodeBuddy 支持两种配置层级层级路径生效范围用户级C:\Users\你的用户名\.codebuddy\models.json所有项目项目级你的项目\.codebuddy\models.json仅当前项目想让 DeepSeek 在任何项目里都可用编辑用户级文件只想让某个项目使用 DeepSeek、避免影响其他项目就创建项目级文件。3.2 先把 API Key 写入环境变量在 PowerShell 中执行setx会持久化到用户环境变量setx DEEPSEEK_API_KEY your DeepSeek API Key注意setx只对之后新开的终端生效当前已打开的窗口不会立即读到该变量。因此设置完成后请从新终端启动 WorkBuddy/CodeBuddy确保 UI 进程继承到环境变量。3.3 完整配置文件逐字可复制{ 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 ] }3.4 字段语义详解对上述 JSON 的每个关键字段含义与注意事项如下字段说明注意事项id模型标识即请求体里的model参数必须与 DeepSeek API 的模型名严格一致deepseek-v4-pro或deepseek-v4-flash大小写与连字符都不能写错name在模型选择器中显示的名称可自定义如DeepSeek V4 Pro仅影响展示vendor厂商标识示例为DeepSeek用于在 UI 中归类urlOpenAI 兼容 Chat Completions 端点固定为https://api.deepseek.com/v1/chat/completions不要把该 URL 填到apiKey字段apiKey鉴权密钥支持${ENV_VAR}语法从环境变量展开本例为${DEEPSEEK_API_KEY}也可直接填明文maxInputTokens单次请求允许的输入 token 上限示例值为128000是文档给出的保守可用值maxOutputTokens单次回复的最大输出 token 数示例为8192supportsToolCall是否启用函数/工具调用能力true时允许 Agent 调用工具如文件读写、命令执行是编程助手的关键能力supportsImages是否支持图像输入DeepSeek V4 文本模型不支持固定为falserelatedModels关联模型映射从配置结构看lite指向更快的deepseek-v4-flashreasoning指向更强的deepseek-v4-pro用于在「轻量/推理」档位间切换availableModels模型选择器中开放可用的模型 id 列表只有出现在此列表中的id才会被客户端展示3.5 relatedModels 与 availableModels两条列表的分工availableModels决定「哪些模型可选」。它引用的id必须都在models数组中有对应定义否则会出现选择了模型却无法发起请求的情况。relatedModels定义模型之间的「关联档位」lite表示轻量快速档映射到 Flashreasoning表示深度推理档映射到 Pro。可以推断当编码助手需要快速补全或深度思考两种模式时会依据这组映射在不同模型间切换。3.6 保存编码UTF-8 无 BOM 是硬要求请将models.json保存为 UTF-8 无 BOM 编码。部分桌面版本在读取带 UTF-8 BOM 文件头的 JSON 时会直接判定为「本地模型配置读取失败」。保存要点在 VS Code 中右下角编码按钮选择UTF-8而非UTF-8 with BOM在 Windows 记事本中另存为时编码选择UTF-8新版记事本默认即无 BOM保存前可用任意 JSON 校验工具确认文件是合法 JSON无多余逗号、引号闭合。四、重启应用并选择模型完全退出WorkBuddy/CodeBuddy不是最小化也不是关窗口后立刻重开要确保进程退出、配置被重新加载然后重新打开。打开模型选择器此时应能看到两个自定义模型DeepSeek V4 Pro DeepSeek V4 Flash选中一个模型即可开始对话或编程任务。如果模型选择器中始终不显示多半是配置文件路径不对应放在.codebuddy\models.json或 JSON 解析失败可参考第六节排查。五、可选验证在 PowerShell 中直接调用 API在动手写配置之前或排障时可以用一条curl命令独立验证「API Key 是否有效、模型名是否写对」把问题从客户端配置中剥离出来$env:DEEPSEEK_API_KEYyour 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}这条命令的要点Authorization: Bearer $env:DEEPSEEK_API_KEY—— 用环境变量值作为 Bearer Token验证环境变量是否设置正确model:deepseek-v4-flash—— 直接以模型 id 发起请求验证模型名拼写stream:false—— 关闭流式输出便于一次性看到完整响应。判定标准请求返回包含choices的成功 JSON说明 API Key 与模型名均可用问题一定出在客户端配置上返回401说明鉴权失败返回404说明模型名错误。六、常见问题排查以下排查表直接对应配置过程中最常遇到的五类现象现象根因处理Authentication Fails或401API Key 无效或把接口 URL 误填到了 API Key 字段核对apiKey是否为真实的 DeepSeek API Key检查是否误把url值填入apiKey确认环境变量DEEPSEEK_API_KEY确实已设置未找到模型或404模型 id 与 API 侧模型名不一致严格使用deepseek-v4-pro或deepseek-v4-flash注意大小写与连字符读取本地模型配置失败JSON 非法或文件带有 UTF-8 BOM 头用校验工具确认 JSON 语法重新保存为 UTF-8 无 BOM模型选择器中不显示配置未被加载完全重启 WorkBuddy/CodeBuddy确认文件路径为.codebuddy\models.json用户级或项目级UI 中直接显示${DEEPSEEK_API_KEY}字样客户端未继承到环境变量变量未被展开从已设置DEEPSEEK_API_KEY的终端中重启应用若桌面端仍不展开变量可在 UI 或本地models.json中直接填入真实 API Key其中「UI 直接显示${DEEPSEEK_API_KEY}」最常见的原因是setx之后仍然从旧终端启动应用导致新进程没有继承环境变量。按照「新开终端 → 启动应用」的顺序操作即可避免。七、与仓库规范的呼应模型命名、上下文与推理档位本仓库的 CONTRIBUTING.md 沉淀了 DeepSeek 接入的通用约定可作为配置 WorkBuddy/CodeBuddy 时的背景知识模型命名DeepSeek 于 2026 年 4 月完成模型更名V3 时代的deepseek-chat/deepseek-reasoner/deepseek-coder已弃用当前正确名称为deepseek-v4-pro与deepseek-v4-flash见 CONTRIBUTING.md。这也是models.json中id必须严格使用这两个名字的原因。上下文窗口DeepSeek V4 系列支持最高 100 万 token 上下文见 CONTRIBUTING.md。本文示例中的maxInputTokens: 128000是文档给出的保守值如果你的 WorkBuddy/CodeBuddy 版本支持更大的输入长度可以在客户端允许范围内酌情调大。推理强度DeepSeek V4 Pro 支持max/high多档推理强度仓库规范建议以max档位获得最佳编码体验见 CONTRIBUTING.md。若你的 WorkBuddy/CodeBuddy 版本暴露了推理强度相关控制项优先使用max档。小结WorkBuddy/CodeBuddy 接入 DeepSeek V4 的核心就三步写好.codebuddy\models.json用户级或项目级→ 用环境变量注入 API Key → 完全重启并选择模型。遇到问题先对照第五节用curl独立验证 API Key 与模型名再回到第六节的排查表逐项核对就能在几分钟内完成接入。更多工具的 DeepSeek 接入指南可返回仓库首页 README.zh-CN.md 继续浏览本文对应的原始精简版文档见 workbuddy.zh-CN.md英文版见 workbuddy.md。【免费下载链接】awesome-deepseek-agent项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考