在 WorkBuddy/CodeBuddy 中通过本地 models.json 接入 DeepSeek V4 完整指南【免费下载链接】awesome-deepseek-agent项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-deepseek-agentWorkBuddy/CodeBuddy 是支持自定义模型的 AI Agent 与编程助手本指南演示如何通过其本地模型配置文件models.json借助 OpenAI 兼容的 Chat Completions API 接入 DeepSeek V4deepseek-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在开始配置前按以下顺序完成准备工作安装并登录 WorkBuddy/CodeBuddy。至少打开一次项目目录让应用在本地创建自己的配置目录例如 Windows 用户主目录下的.codebuddy目录后续的models.json需要放置在该目录中。前往 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 Keysetx会持久化该环境变量。注意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 ] }字段含义与取值说明字段含义取值建议id模型的唯一标识也是请求 API 时使用的模型名必须与 DeepSeek 平台模型名完全一致deepseek-v4-pro或deepseek-v4-flashname显示在模型选择器中的友好名称例如DeepSeek V4 Pro可自定义vendor供应商名称用于分组展示例如DeepSeekurlOpenAI 兼容的 Chat Completions 接口地址https://api.deepseek.com/v1/chat/completionsapiKeyAPI 密钥支持${环境变量名}形式引用推荐${DEEPSEEK_API_KEY}避免明文maxInputTokens单次请求允许的最大输入 token 数配置示例为128000maxOutputTokens单次响应允许的最大输出 token 数配置示例为8192supportsToolCall是否支持工具调用Function Calling / Tool Use决定 Agent 能否调用工具truesupportsImages是否支持图片输入多模态DeepSeek 文本模型填falserelatedModels关联的轻量/推理模型映射供助手自动切换轻量与深度推理模型lite指向deepseek-v4-flashreasoning指向deepseek-v4-proavailableModels在模型选择器中实际开放可选的模型 id 列表列出上面定义的两个 id关于 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。第五步完全重启并选择模型配置完成后完全退出WorkBuddy/CodeBuddy不是最小化到托盘而是彻底退出进程然后重新打开。在模型选择器中应能看到并选择DeepSeek V4 Pro DeepSeek V4 Flash如果模型没有出现请回到第二步确认文件路径是否为配置作用域\.codebuddy\models.json并确认 JSON 格式合法。第六步可选在 PowerShell 中验证 API Key在正式使用前Windows 用户可以先在 PowerShell 中直接调用一次 Chat Completions 接口验证 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}如果请求成功返回正常 JSON 响应说明 API Key 与模型名都有效如果返回401或404请对照下一节的排查表处理。常见问题排查表现象可能原因与解决办法Authentication Fails或401apiKey不是真实的 DeepSeek API Key。检查密钥是否正确并确认没有把接口 URL 误填到 API Key 字段未找到模型/Model Not Found或404模型id必须严格写成deepseek-v4-pro或deepseek-v4-flash注意拼写与大小写读取本地模型配置失败/Failed to read local model configurationmodels.json不是合法 JSON或没有保存为 UTF-8 无 BOM 编码模型选择器中不显示模型完全退出并重启 WorkBuddy/CodeBuddy确认文件确实放在.codebuddy\models.json路径下用户级或项目级其一UI 中直接显示${DEEPSEEK_API_KEY}字面量说明应用启动时没有读取到环境变量。请从已经设置DEEPSEEK_API_KEY的终端中重启应用如果桌面端仍不展开环境变量则直接在 UI 或本地models.json中填入真实 API Key小结接入流程回顾整个接入过程可以概括为四步闭环安装登录并打开一次项目 → 把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考