手把手教你安装 Claude Code 并接入 DeepSeek配置、排错、实战全纪录最近在尝试把 Claude Code 接入 DeepSeek 时踩了不少坑版本不匹配、模型名识别不了、代理配置报 400、甚至还有组织订阅限制的提示。网上的资料要么只讲一半要么直接用旧版本参数照着配很容易卡住。这篇文章我把完整的安装流程、DeepSeek API 接入方式、VSCode 配置方法、常见报错排查思路整理成一套可复现的实操教程适合刚接触 Claude Code 的开发者也适合已经在用但想切换到 DeepSeek 模型的朋友。先明确一下本文要解决的问题Claude Code 是 Anthropic 官方推出的终端编程助手默认情况下它面向 Claude 模型设计DeepSeek 是国产开源大模型API 兼容性做得比较好。我们要做的就是通过配置让 Claude Code 调用 DeepSeek 的 API从而用更低的成本获得代码补全、文件读写、命令执行等能力。整个过程会涉及 Node.js 环境安装、Claude Code CLI 安装、DeepSeek API Key 申请、环境变量配置、VSCode 扩展设置以及常见的 400、529、模型名不识别等错误处理。文章不会局限于“能跑通”这个层面还会解释每个配置项的含义帮助你理解 Claude Code 的工作方式。这样即使后续版本更新你也能根据自己的情况调整。1. 背景与核心概念1.1 Claude Code 是什么Claude Code 是 Anthropic 提供的一款命令行编程助手工具。它运行在终端里可以读取项目文件、生成代码、执行命令、修改文件并基于当前项目的上下文提供建议。和 ChatGPT 网页版不同Claude Code 更贴近“本地开发工具”的定位适合在真实项目中直接使用。它的核心工作方式可以理解为你通过终端对话Claude Code 会根据上下文调用工具比如读文件、写文件、执行 shell 命令然后把结果反馈给你。这种模式比单纯复制粘贴代码更高效尤其适合重构、批量修改、写测试等场景。不过要注意Claude Code 原生设计是围绕 Claude 模型走的。如果你没有 Claude 的订阅或 API 权限直接安装后可能无法正常使用或者会看到类似 “your organization has disabled claude subscription access for claude code” 的提示。1.2 DeepSeek 是什么DeepSeek 是由深度求索公司开发的大语言模型系列特点是推理能力强、中文支持好、API 价格相对较低。DeepSeek 提供了 OpenAI 兼容的 API 接口这意味着很多原本为 OpenAI 设计或兼容 OpenAI 协议的工具都可以通过修改 base_url 和模型名来接入 DeepSeek。这个“OpenAI 兼容”特性非常关键。Claude Code 虽然不直接支持 DeepSeek但我们可以通过一些代理层或兼容层把 Claude Code 的请求转发到 DeepSeek API。市面上已经有类似 Claude Code Router、claude-code-proxy 这类开源工具在做这件事社区里也有开发者通过环境变量或本地代理实现接入。1.3 为什么要让 Claude Code 接入 DeepSeek成本更低DeepSeek 的 API 定价相比 Claude 商业 API 便宜很多。国内访问更友好DeepSeek API 服务部署在国内网络延迟更低。模型能力强DeepSeek 在代码生成、逻辑推理方面表现不错适合日常开发。绕开订阅限制如果你没有 Claude 订阅但想用 Claude Code 的工作流接入 DeepSeek 是常见替代方案。这里要说明一下Claude Code 默认的很多高级能力比如特殊工具调用、长上下文管理是围绕 Claude 模型优化的接入第三方模型后部分功能可能不如原生体验。文章后面会提到哪些功能受影响。2. 环境准备与版本说明在开始安装之前先确认你的电脑环境。以下是本文示例使用的环境你可以根据自己的系统做调整项目推荐环境操作系统macOS / Linux / WindowsWSL 2 或 Git BashNode.js18.0 或更高版本包管理器npm 或 pnpmClaude Code最新版本 CLIDeepSeek API需要在 DeepSeek 开放平台申请 API Key编辑器VSCode可选用于安装扩展2.1 Node.js 环境检查Claude Code 是基于 Node.js 的 CLI 工具所以第一步是确认 Node.js 已经安装。打开终端执行node -v npm -v如果输出类似v18.20.4和10.7.0的版本号说明环境没问题。如果提示command not found需要先安装 Node.js。推荐使用 nvm 管理 Node.js 版本方便切换curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端执行nvm install 18 nvm use 182.2 DeepSeek API Key 准备DeepSeek 的 API Key 需要去 DeepSeek 开放平台申请。大致流程是注册账号 → 实名认证如果需要→ 创建 API Key → 充值或领取免费额度。拿到 API Key 后建议先保存到一个安全的位置。后面配置环境变量时会用到。要注意的是DeepSeek 平台的具体页面可能调整以官网实际展示为准。本文重点讲解接入流程不绑定某个固定页面路径。2.3 关于版本的提醒Claude Code 的更新速度比较快DeepSeek 的模型版本也在迭代。你在实际操作时可能会遇到新旧版本参数不一致的情况。比如社区里有人遇到 “deepseek-v4-pro is not a model this version of claude code recognizes” 这样的报错说明你配置的模型名在当前 Claude Code 版本中还没被内置识别或者代理层不认识这个模型名。遇到这类问题时不要死扣网上的某个旧教程而是去查当前版本的模型列表和配置方式。文章第 5 节会专门讲这个问题。3. 核心原理解析3.1 Claude Code 的配置机制Claude Code 的配置主要分几个层级项目级配置放在项目根目录的.claude文件夹中。用户级配置放在用户主目录下的~/.claude文件夹中。环境变量通过 shell 环境变量或.env文件注入。当我们想接入第三方模型时通常需要做两件事告诉 Claude Code 使用哪个 API 地址base_url。告诉 Claude Code 使用哪个模型model。这两个信息一般通过环境变量传递或者通过代理工具映射。3.2 OpenAI 兼容接口的作用DeepSeek 的 API 兼容 OpenAI 协议所以请求格式基本是POST https://api.deepseek.com/chat/completions { model: deepseek-chat, messages: [...] }但 Claude Code 发送的请求是 Anthropic 格式不是 OpenAI 格式。直接让 Claude Code 请求 DeepSeek API 通常是不行的因为两者的消息结构、参数名、鉴权方式都不一样。因此社区做法是引入一个“转换层”把 Anthropic 格式的请求转换成 OpenAI 格式再把 OpenAI 格式的响应转换成 Anthropic 格式。这就是很多代理工具的本质。3.3 常见接入架构为了让 Claude Code 使用 DeepSeek常见的架构有两种方案 A通过本地代理工具转换协议。Claude Code - 本地代理 (格式转换) - DeepSeek API方案 B通过支持模型映射的 Router 工具。Claude Code - Router (模型路由 格式转换) - DeepSeek API这两种方案在社区里都有对应实现。有的工具叫 Claude Code Router有的叫 DeepSeek Harness有的叫 Claude Code Proxy。它们的目标是一致的让 Claude Code 能“说” DeepSeek “听得懂”的话。需要注意的是这些工具很多是社区项目更新频率和稳定性不一。使用时建议先看 GitHub 仓库的 README 和 issues确认它支持你当前的 Claude Code 版本。4. 完整安装与配置实战下面进入正题。我会从零开始演示 Claude Code 的安装、DeepSeek 的接入、VSCode 配置以及最终的启动验证。4.1 安装 Claude Code4.1.1 全局安装 CLInpm install -g anthropic-ai/claude-code安装完成后检查版本claude --version如果能看到版本号说明安装成功。4.1.2 验证可执行文件which claude在 macOS/Linux 上通常输出/usr/local/bin/claude或 nvm 对应的路径。在 Windows 上如果使用 Git Bash 或 WSL路径可能不同。4.2 配置 DeepSeek API在终端中临时设置环境变量export ANTHROPIC_BASE_URLhttp://localhost:8080 export ANTHROPIC_AUTH_TOKENyour-deepseek-api-key export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat这里简单解释一下ANTHROPIC_BASE_URLClaude Code 请求的 API 地址。如果使用本地代理就指向本地代理端口如果使用云端转换服务就指向对应服务地址。ANTHROPIC_AUTH_TOKEN鉴权 Token。在接入 DeepSeek 时这里可以填 DeepSeek API Key。ANTHROPIC_MODEL主模型名称。ANTHROPIC_SMALL_FAST_MODEL轻量快速模型名称常用于小任务。有的工具还支持ANTHROPIC_API_KEY但为了不和 Claude 官方 API 混淆建议按代理工具的文档来。如果你不希望每次打开终端都手动 export可以写到~/.zshrc或~/.bashrc中echo export ANTHROPIC_BASE_URLhttp://localhost:8080 ~/.zshrc echo export ANTHROPIC_AUTH_TOKENyour-deepseek-api-key ~/.zshrc echo export ANTHROPIC_MODELdeepseek-chat ~/.zshrc然后执行source ~/.zshrc4.3 使用本地代理接入 DeepSeek为了更贴近真实使用我以“本地代理”思路为例。假设我们有一个代理服务运行在localhost:8080它负责把 Claude Code 的请求转发给 DeepSeek。先准备一个简单的 Node.js 代理思路// 文件路径proxy.js // 这是一个极简示例用于说明 Claude Code 到 DeepSeek 的格式转换思路 // 实际使用时建议使用社区成熟工具或完善错误处理和流式响应支持 const http require(http); const https require(https); const DEEPSEEK_API_URL https://api.deepseek.com; const DEEPSEEK_API_KEY process.env.DEEPSEEK_API_KEY; http.createServer((req, res) { let body ; req.on(data, chunk (body chunk)); req.on(end, () { // 这里需要根据实际请求格式做转换 // Claude Code 发来的是 Anthropic Messages API 格式 // DeepSeek 接收的是 OpenAI Chat Completions 格式 console.log(收到 Claude Code 请求:, req.url); // 简化处理直接透传到 DeepSeek 的 /chat/completions const payload JSON.parse(body); const openAIPayload { model: payload.model || deepseek-chat, messages: payload.messages, max_tokens: payload.max_tokens, stream: payload.stream || false }; const postData JSON.stringify(openAIPayload); const options { hostname: api.deepseek.com, path: /chat/completions, method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${DEEPSEEK_API_KEY}, Content-Length: Buffer.byteLength(postData) } }; const upstreamReq https.request(options, upstreamRes { res.writeHead(upstreamRes.statusCode, { Content-Type: application/json }); upstreamRes.pipe(res); }); upstreamReq.on(error, err { console.error(上游请求失败:, err.message); res.writeHead(502); res.end(JSON.stringify({ error: Bad Gateway })); }); upstreamReq.write(postData); upstreamReq.end(); }); }).listen(8080, () { console.log(Claude Code DeepSeek 代理已启动: http://localhost:8080); });运行代理export DEEPSEEK_API_KEYyour-deepseek-api-key node proxy.js这个示例代码只是为了让你理解转换层的原理并不是一个完整的生产级代理。实际使用中流式响应、错误处理、鉴权、模型映射都需要做更多处理。社区中已经有相对成熟的工具可以直接使用建议优先参考那些项目。4.4 在 VSCode 中安装与配置 Claude CodeClaude Code 除了终端 CLI还可以通过 VSCode 扩展使用。社区中有一些第三方扩展安装后可以在 VSCode 侧边栏或集成终端中调用 Claude Code。在 VSCode 扩展市场搜索 “Claude Code”找到对应扩展后点击安装。安装后需要确保 VSCode 的终端能够继承前面设置的环境变量。常见做法是在 VSCode 的settings.json中添加终端环境变量{ terminal.integrated.env.linux: { ANTHROPIC_BASE_URL: http://localhost:8080, ANTHROPIC_AUTH_TOKEN: your-deepseek-api-key, ANTHROPIC_MODEL: deepseek-chat }, terminal.integrated.env.osx: { ANTHROPIC_BASE_URL: http://localhost:8080, ANTHROPIC_AUTH_TOKEN: your-deepseek-api-key, ANTHROPIC_MODEL: deepseek-chat }, terminal.integrated.env.windows: { ANTHROPIC_BASE_URL: http://localhost:8080, ANTHROPIC_AUTH_TOKEN: your-deepseek-api-key, ANTHROPIC_MODEL: deepseek-chat } }配置完成后重启 VSCode打开集成终端输入claude即可启动。4.5 启动 Claude Code 并验证在配置好环境变量和代理后进入你的项目目录cd /path/to/your/project claude如果一切正常你会看到 Claude Code 的交互界面并可以通过对话让它操作文件或执行命令。可以试试让它“查看当前项目结构”或“写一个 Python 快速排序函数”看它是否能正确响应。4.6 使用 DeepSeek Harness 等社区工具除了自己写代理社区中也有一些封装好的工具例如 DeepSeek Harness、Claude Code Router 等。它们的安装方式一般是在 GitHub 仓库中提供 Release 包或 npm 包。使用时注意确认支持你的 Claude Code 版本。确认是否支持 DeepSeek 最新模型名。确认是否需要额外配置模型映射。这些工具很多处于快速迭代阶段建议以官方仓库的最新 README 为准不要照搬旧教程里的命令。5. 常见问题与排查思路接入过程中最容易踩的坑集中在模型名、代理配置、鉴权方式、版本兼容这几个方面。下面整理成表格方便快速定位。问题现象常见原因解决思路deepseek-v4-pro is not a model this version of claude code recognizes当前 Claude Code 版本或代理层不认识该模型名换成 DeepSeek 官方 API 文档中确认存在的模型名如deepseek-chat升级代理工具版本检查模型映射配置deepseek-v4-flash is not a model this version of claude code recognizes模型名写错或工具版本过旧参考 DeepSeek 平台可用的模型列表不要使用网上流传的未发布模型名请求返回 HTTP 400提示reasoning_content必须回传DeepSeek 思考模式参数与 Claude Code 请求格式冲突升级代理工具确保能正确处理reasoning_content字段关闭 DeepSeek 侧思考模式或调整参数cc switch local proxy failed while handling codex endpoint /responses代理配置不正确或代理端口未启动确认代理服务正在运行检查ANTHROPIC_BASE_URL是否正确查看代理日志定位具体错误your organization has disabled claude subscription access for claude code当前账号没有 Claude 订阅权限检查是否使用了代理或第三方转换层是否正确设置ANTHROPIC_AUTH_TOKEN如果是组织账号联系管理员开通权限输入claude提示命令找不到Node.js 未安装或全局安装路径不在 PATH 中重新安装 Node.js检查 npm 全局 bin 路径使用npx anthropic-ai/claude-code临时运行代理启动成功但 Claude Code 无响应代理未处理流式响应或请求格式不兼容查看代理日志换用较成熟的社区代理工具降低模型请求参数复杂度5.1 模型名报错的深入分析“模型名不被识别”是出现频率最高的问题。原因主要有两个第一Claude Code 内置了模型白名单或默认模型列表。如果你把ANTHROPIC_MODEL设置成一个它不认识的字符串启动时或请求时就会报错。这并不代表 DeepSeek 模型不存在而是 Claude Code 没有识别。第二代理层有自己的模型映射表。代理工具需要知道“Claude Code 请求的 model 字段”应该映射到“DeepSeek 的哪个模型”。如果映射表过旧或者没有配置 fallback 规则就会报错。解决方案优先顺序查官方文档确定 DeepSeek 当前可用的模型名。换用官方推荐的模型名比如deepseek-chat。升级代理工具到最新版本。如果使用开源代理检查其模型映射配置必要时手动加一行映射。这里特别提醒不要轻信网上流传的“隐藏模型名”或“未发布模型”。很多模型名看起来很像 DeepSeek 未来版本但 DeepSeek 平台根本还没有开放强行配置只会浪费时间。5.2 HTTP 400 的排查示例假设你遇到下面这个错误cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the reasoning_content in the thinking mode must be passed back to the api.这句话的关键信息是provider: deepseek请求被路由到了 DeepSeek。model: deepseek-v4-flash使用的模型名。upstream_status: http 400DeepSeek API 返回 400。reasoning_content in the thinking mode must be passed back to the apiDeepSeek 要求思考模式中的reasoning_content必须原样回传。出现这种问题说明代理层在转发多轮对话时把上一轮模型返回的reasoning_content丢掉了。DeepSeek 的对话接口在开启思考模式时要求客户端在下一轮请求中带上这个字段否则报 400。排查步骤关闭思考模式去 DeepSeek 平台或 API 参数中关闭思维链相关开关看是否恢复正常。更新代理工具检查代理工具的版本看 issue 里是否有人反馈同样问题。查看完整请求日志在代理层打印完整请求体确认messages数组中是否包含reasoning_content。5.3 关于 Claude Code 529 错误“claude code 529” 这个关键词在社区里也比较常见。529 通常表示服务过载或限流。当你把 Claude Code 接入 DeepSeek 后如果代理层没有正确转换请求也可能出现 529 或类似错误。解决思路检查请求是否真的到达 DeepSeek还是被某个中间层拦截。查看代理日志中的上游状态码如果上游返回 529说明 DeepSeek 侧限流需要降低请求频率或稍后重试。如果 529 来自 Claude Code 本身说明它可能在尝试访问官方服务检查ANTHROPIC_BASE_URL是否配置成功。5.4 排查清单如果你已经按教程操作但依然卡住建议按以下顺序排查确认 Node.js 版本大于等于 18。确认claude --version能输出版本号。确认 DeepSeek API Key 格式正确且在平台上有余额或额度。确认ANTHROPIC_BASE_URL指向的地址能访问用 curl 测试。确认代理服务日志中有请求进来。确认代理服务日志中上游返回的状态码是 200。如果返回 400检查请求体中的 model 字段和 messages 结构。如果返回 401检查 Authorization 头是否带上了 DeepSeek API Key。如果返回 404检查接口路径是否正确。最后再检查 Claude Code 版本和代理工具版本是否兼容。6. 最佳实践与工程建议6.1 使用版本管理工具锁定 Node 版本Claude Code 对 Node.js 版本有要求不同版本的行为也可能有差异。建议在项目目录中维护.nvmrc文件echo 18 .nvmrc使用时执行nvm use即可自动切换到对应版本。这能减少因为 Node 版本不一致导致的奇怪问题。6.2 合理管理 API KeyDeepSeek API Key 是敏感信息不要硬编码在代码或提交到 Git 仓库。建议使用.env文件并在.gitignore中忽略它。使用系统的密钥管理工具或 CI/CD 的 secret 配置。定期轮换 API Key防止泄露。例如在.gitignore中添加.env6.3 学会看日志无论是 Claude Code 还是代理工具日志都是排查问题的第一手资料。很多代理工具支持DEBUG环境变量来自动输出详细日志export DEBUG*开启后你能看到完整的请求和响应内容。通过日志理解“Claude Code 实际发了什么”和“DeepSeek 实际返回了什么”比盲目猜测高效得多。6.4 保持代理层薄而专一如果使用本地代理尽量让代理层只做“协议转换”不要在里面堆叠太多业务逻辑。代理越复杂越难排查问题。社区中的成熟项目通常已经处理好了流式、超时、错误码映射优先复用。6.5 模型选型建议DeepSeek 平台通常会提供不同定位的模型比如对话模型、推理模型、代码模型。在 Claude Code 中配置主模型和轻量模型时建议根据任务类型选择需要复杂代码生成和重构使用能力强的主模型。简单问答、格式化、补全使用快速轻量模型。模型名称和定位以 DeepSeek 官方文档为准因为不同时期的模型命名差异较大这里不写死具体名称。6.6 注意流式响应Claude Code 的交互体验依赖流式输出。如果代理层不支持 Server-Sent EventsSSE流式响应每次请求都要等完整结果返回体验会非常差。选择代理工具时确认它支持流式转发。6.7 安全与合规提示本教程涉及的 API 调用、本地代理等操作都属于正常的开发工具配置。在实际生产环境中使用时注意不要在公共网络传输未经加密的 API Key。涉及公司项目代码时确认模型服务的数据处理条款是否满足合规要求。如果使用第三方代理工具先评估其代码可信度不要随意向不明服务发送项目代码。7. 总结与下一步这篇文章从 Claude Code 和 DeepSeek 的基础概念讲起解释了 Claude Code 为什么默认不能直接使用 DeepSeek以及如何通过环境变量、本地代理或社区工具实现接入。核心流程可以概括为四步安装 Node.js 和 Claude Code。申请 DeepSeek API Key。配置ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL等环境变量。启动代理或使用社区 Router 工具让 Claude Code 的请求能正确转发到 DeepSeek。同时我还整理了模型名不识别、HTTP 400、529 报错、组织订阅限制等高频问题的排查思路。遇到问题不要急着换工具先看日志再定位是网络、鉴权还是格式转换的问题。完成基础接入后你可以继续探索在 Claude Code 中编写自定义 Skill技能提升特定场景下的自动化能力。对比 Claude Code 使用 DeepSeek 和官方 Claude 模型的差异找到最适合自己项目的配置。深入研究 Anthropic Messages API 和 OpenAI Chat Completions 的协议差异自己改造代理层。结合 CI/CD 流水线在自动化环境中使用 Claude Code 进行代码审查或文档生成。这套接入方案并不是“银弹”。如果你需要极致的代码生成质量或完整的工具链体验原生 Claude 模型仍然是更稳妥的选择但如果你追求成本和国内网络环境下的可用性DeepSeek 确实是一个很好的平替方案。建议先在测试项目中跑通流程再逐步放大到真实项目。技术选型没有绝对的正确只有适不适合你的场景。
手把手教你安装 Claude Code 并接入 DeepSeek配置、排错、实战全纪录最近在尝试把 Claude Code 接入 DeepSeek 时踩了不少坑版本不匹配、模型名识别不了、代理配置报 400、甚至还有组织订阅限制的提示。网上的资料要么只讲一半要么直接用旧版本参数照着配很容易卡住。这篇文章我把完整的安装流程、DeepSeek API 接入方式、VSCode 配置方法、常见报错排查思路整理成一套可复现的实操教程适合刚接触 Claude Code 的开发者也适合已经在用但想切换到 DeepSeek 模型的朋友。先明确一下本文要解决的问题Claude Code 是 Anthropic 官方推出的终端编程助手默认情况下它面向 Claude 模型设计DeepSeek 是国产开源大模型API 兼容性做得比较好。我们要做的就是通过配置让 Claude Code 调用 DeepSeek 的 API从而用更低的成本获得代码补全、文件读写、命令执行等能力。整个过程会涉及 Node.js 环境安装、Claude Code CLI 安装、DeepSeek API Key 申请、环境变量配置、VSCode 扩展设置以及常见的 400、529、模型名不识别等错误处理。文章不会局限于“能跑通”这个层面还会解释每个配置项的含义帮助你理解 Claude Code 的工作方式。这样即使后续版本更新你也能根据自己的情况调整。1. 背景与核心概念1.1 Claude Code 是什么Claude Code 是 Anthropic 提供的一款命令行编程助手工具。它运行在终端里可以读取项目文件、生成代码、执行命令、修改文件并基于当前项目的上下文提供建议。和 ChatGPT 网页版不同Claude Code 更贴近“本地开发工具”的定位适合在真实项目中直接使用。它的核心工作方式可以理解为你通过终端对话Claude Code 会根据上下文调用工具比如读文件、写文件、执行 shell 命令然后把结果反馈给你。这种模式比单纯复制粘贴代码更高效尤其适合重构、批量修改、写测试等场景。不过要注意Claude Code 原生设计是围绕 Claude 模型走的。如果你没有 Claude 的订阅或 API 权限直接安装后可能无法正常使用或者会看到类似 “your organization has disabled claude subscription access for claude code” 的提示。1.2 DeepSeek 是什么DeepSeek 是由深度求索公司开发的大语言模型系列特点是推理能力强、中文支持好、API 价格相对较低。DeepSeek 提供了 OpenAI 兼容的 API 接口这意味着很多原本为 OpenAI 设计或兼容 OpenAI 协议的工具都可以通过修改 base_url 和模型名来接入 DeepSeek。这个“OpenAI 兼容”特性非常关键。Claude Code 虽然不直接支持 DeepSeek但我们可以通过一些代理层或兼容层把 Claude Code 的请求转发到 DeepSeek API。市面上已经有类似 Claude Code Router、claude-code-proxy 这类开源工具在做这件事社区里也有开发者通过环境变量或本地代理实现接入。1.3 为什么要让 Claude Code 接入 DeepSeek成本更低DeepSeek 的 API 定价相比 Claude 商业 API 便宜很多。国内访问更友好DeepSeek API 服务部署在国内网络延迟更低。模型能力强DeepSeek 在代码生成、逻辑推理方面表现不错适合日常开发。绕开订阅限制如果你没有 Claude 订阅但想用 Claude Code 的工作流接入 DeepSeek 是常见替代方案。这里要说明一下Claude Code 默认的很多高级能力比如特殊工具调用、长上下文管理是围绕 Claude 模型优化的接入第三方模型后部分功能可能不如原生体验。文章后面会提到哪些功能受影响。2. 环境准备与版本说明在开始安装之前先确认你的电脑环境。以下是本文示例使用的环境你可以根据自己的系统做调整项目推荐环境操作系统macOS / Linux / WindowsWSL 2 或 Git BashNode.js18.0 或更高版本包管理器npm 或 pnpmClaude Code最新版本 CLIDeepSeek API需要在 DeepSeek 开放平台申请 API Key编辑器VSCode可选用于安装扩展2.1 Node.js 环境检查Claude Code 是基于 Node.js 的 CLI 工具所以第一步是确认 Node.js 已经安装。打开终端执行node -v npm -v如果输出类似v18.20.4和10.7.0的版本号说明环境没问题。如果提示command not found需要先安装 Node.js。推荐使用 nvm 管理 Node.js 版本方便切换curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端执行nvm install 18 nvm use 182.2 DeepSeek API Key 准备DeepSeek 的 API Key 需要去 DeepSeek 开放平台申请。大致流程是注册账号 → 实名认证如果需要→ 创建 API Key → 充值或领取免费额度。拿到 API Key 后建议先保存到一个安全的位置。后面配置环境变量时会用到。要注意的是DeepSeek 平台的具体页面可能调整以官网实际展示为准。本文重点讲解接入流程不绑定某个固定页面路径。2.3 关于版本的提醒Claude Code 的更新速度比较快DeepSeek 的模型版本也在迭代。你在实际操作时可能会遇到新旧版本参数不一致的情况。比如社区里有人遇到 “deepseek-v4-pro is not a model this version of claude code recognizes” 这样的报错说明你配置的模型名在当前 Claude Code 版本中还没被内置识别或者代理层不认识这个模型名。遇到这类问题时不要死扣网上的某个旧教程而是去查当前版本的模型列表和配置方式。文章第 5 节会专门讲这个问题。3. 核心原理解析3.1 Claude Code 的配置机制Claude Code 的配置主要分几个层级项目级配置放在项目根目录的.claude文件夹中。用户级配置放在用户主目录下的~/.claude文件夹中。环境变量通过 shell 环境变量或.env文件注入。当我们想接入第三方模型时通常需要做两件事告诉 Claude Code 使用哪个 API 地址base_url。告诉 Claude Code 使用哪个模型model。这两个信息一般通过环境变量传递或者通过代理工具映射。3.2 OpenAI 兼容接口的作用DeepSeek 的 API 兼容 OpenAI 协议所以请求格式基本是POST https://api.deepseek.com/chat/completions { model: deepseek-chat, messages: [...] }但 Claude Code 发送的请求是 Anthropic 格式不是 OpenAI 格式。直接让 Claude Code 请求 DeepSeek API 通常是不行的因为两者的消息结构、参数名、鉴权方式都不一样。因此社区做法是引入一个“转换层”把 Anthropic 格式的请求转换成 OpenAI 格式再把 OpenAI 格式的响应转换成 Anthropic 格式。这就是很多代理工具的本质。3.3 常见接入架构为了让 Claude Code 使用 DeepSeek常见的架构有两种方案 A通过本地代理工具转换协议。Claude Code - 本地代理 (格式转换) - DeepSeek API方案 B通过支持模型映射的 Router 工具。Claude Code - Router (模型路由 格式转换) - DeepSeek API这两种方案在社区里都有对应实现。有的工具叫 Claude Code Router有的叫 DeepSeek Harness有的叫 Claude Code Proxy。它们的目标是一致的让 Claude Code 能“说” DeepSeek “听得懂”的话。需要注意的是这些工具很多是社区项目更新频率和稳定性不一。使用时建议先看 GitHub 仓库的 README 和 issues确认它支持你当前的 Claude Code 版本。4. 完整安装与配置实战下面进入正题。我会从零开始演示 Claude Code 的安装、DeepSeek 的接入、VSCode 配置以及最终的启动验证。4.1 安装 Claude Code4.1.1 全局安装 CLInpm install -g anthropic-ai/claude-code安装完成后检查版本claude --version如果能看到版本号说明安装成功。4.1.2 验证可执行文件which claude在 macOS/Linux 上通常输出/usr/local/bin/claude或 nvm 对应的路径。在 Windows 上如果使用 Git Bash 或 WSL路径可能不同。4.2 配置 DeepSeek API在终端中临时设置环境变量export ANTHROPIC_BASE_URLhttp://localhost:8080 export ANTHROPIC_AUTH_TOKENyour-deepseek-api-key export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat这里简单解释一下ANTHROPIC_BASE_URLClaude Code 请求的 API 地址。如果使用本地代理就指向本地代理端口如果使用云端转换服务就指向对应服务地址。ANTHROPIC_AUTH_TOKEN鉴权 Token。在接入 DeepSeek 时这里可以填 DeepSeek API Key。ANTHROPIC_MODEL主模型名称。ANTHROPIC_SMALL_FAST_MODEL轻量快速模型名称常用于小任务。有的工具还支持ANTHROPIC_API_KEY但为了不和 Claude 官方 API 混淆建议按代理工具的文档来。如果你不希望每次打开终端都手动 export可以写到~/.zshrc或~/.bashrc中echo export ANTHROPIC_BASE_URLhttp://localhost:8080 ~/.zshrc echo export ANTHROPIC_AUTH_TOKENyour-deepseek-api-key ~/.zshrc echo export ANTHROPIC_MODELdeepseek-chat ~/.zshrc然后执行source ~/.zshrc4.3 使用本地代理接入 DeepSeek为了更贴近真实使用我以“本地代理”思路为例。假设我们有一个代理服务运行在localhost:8080它负责把 Claude Code 的请求转发给 DeepSeek。先准备一个简单的 Node.js 代理思路// 文件路径proxy.js // 这是一个极简示例用于说明 Claude Code 到 DeepSeek 的格式转换思路 // 实际使用时建议使用社区成熟工具或完善错误处理和流式响应支持 const http require(http); const https require(https); const DEEPSEEK_API_URL https://api.deepseek.com; const DEEPSEEK_API_KEY process.env.DEEPSEEK_API_KEY; http.createServer((req, res) { let body ; req.on(data, chunk (body chunk)); req.on(end, () { // 这里需要根据实际请求格式做转换 // Claude Code 发来的是 Anthropic Messages API 格式 // DeepSeek 接收的是 OpenAI Chat Completions 格式 console.log(收到 Claude Code 请求:, req.url); // 简化处理直接透传到 DeepSeek 的 /chat/completions const payload JSON.parse(body); const openAIPayload { model: payload.model || deepseek-chat, messages: payload.messages, max_tokens: payload.max_tokens, stream: payload.stream || false }; const postData JSON.stringify(openAIPayload); const options { hostname: api.deepseek.com, path: /chat/completions, method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${DEEPSEEK_API_KEY}, Content-Length: Buffer.byteLength(postData) } }; const upstreamReq https.request(options, upstreamRes { res.writeHead(upstreamRes.statusCode, { Content-Type: application/json }); upstreamRes.pipe(res); }); upstreamReq.on(error, err { console.error(上游请求失败:, err.message); res.writeHead(502); res.end(JSON.stringify({ error: Bad Gateway })); }); upstreamReq.write(postData); upstreamReq.end(); }); }).listen(8080, () { console.log(Claude Code DeepSeek 代理已启动: http://localhost:8080); });运行代理export DEEPSEEK_API_KEYyour-deepseek-api-key node proxy.js这个示例代码只是为了让你理解转换层的原理并不是一个完整的生产级代理。实际使用中流式响应、错误处理、鉴权、模型映射都需要做更多处理。社区中已经有相对成熟的工具可以直接使用建议优先参考那些项目。4.4 在 VSCode 中安装与配置 Claude CodeClaude Code 除了终端 CLI还可以通过 VSCode 扩展使用。社区中有一些第三方扩展安装后可以在 VSCode 侧边栏或集成终端中调用 Claude Code。在 VSCode 扩展市场搜索 “Claude Code”找到对应扩展后点击安装。安装后需要确保 VSCode 的终端能够继承前面设置的环境变量。常见做法是在 VSCode 的settings.json中添加终端环境变量{ terminal.integrated.env.linux: { ANTHROPIC_BASE_URL: http://localhost:8080, ANTHROPIC_AUTH_TOKEN: your-deepseek-api-key, ANTHROPIC_MODEL: deepseek-chat }, terminal.integrated.env.osx: { ANTHROPIC_BASE_URL: http://localhost:8080, ANTHROPIC_AUTH_TOKEN: your-deepseek-api-key, ANTHROPIC_MODEL: deepseek-chat }, terminal.integrated.env.windows: { ANTHROPIC_BASE_URL: http://localhost:8080, ANTHROPIC_AUTH_TOKEN: your-deepseek-api-key, ANTHROPIC_MODEL: deepseek-chat } }配置完成后重启 VSCode打开集成终端输入claude即可启动。4.5 启动 Claude Code 并验证在配置好环境变量和代理后进入你的项目目录cd /path/to/your/project claude如果一切正常你会看到 Claude Code 的交互界面并可以通过对话让它操作文件或执行命令。可以试试让它“查看当前项目结构”或“写一个 Python 快速排序函数”看它是否能正确响应。4.6 使用 DeepSeek Harness 等社区工具除了自己写代理社区中也有一些封装好的工具例如 DeepSeek Harness、Claude Code Router 等。它们的安装方式一般是在 GitHub 仓库中提供 Release 包或 npm 包。使用时注意确认支持你的 Claude Code 版本。确认是否支持 DeepSeek 最新模型名。确认是否需要额外配置模型映射。这些工具很多处于快速迭代阶段建议以官方仓库的最新 README 为准不要照搬旧教程里的命令。5. 常见问题与排查思路接入过程中最容易踩的坑集中在模型名、代理配置、鉴权方式、版本兼容这几个方面。下面整理成表格方便快速定位。问题现象常见原因解决思路deepseek-v4-pro is not a model this version of claude code recognizes当前 Claude Code 版本或代理层不认识该模型名换成 DeepSeek 官方 API 文档中确认存在的模型名如deepseek-chat升级代理工具版本检查模型映射配置deepseek-v4-flash is not a model this version of claude code recognizes模型名写错或工具版本过旧参考 DeepSeek 平台可用的模型列表不要使用网上流传的未发布模型名请求返回 HTTP 400提示reasoning_content必须回传DeepSeek 思考模式参数与 Claude Code 请求格式冲突升级代理工具确保能正确处理reasoning_content字段关闭 DeepSeek 侧思考模式或调整参数cc switch local proxy failed while handling codex endpoint /responses代理配置不正确或代理端口未启动确认代理服务正在运行检查ANTHROPIC_BASE_URL是否正确查看代理日志定位具体错误your organization has disabled claude subscription access for claude code当前账号没有 Claude 订阅权限检查是否使用了代理或第三方转换层是否正确设置ANTHROPIC_AUTH_TOKEN如果是组织账号联系管理员开通权限输入claude提示命令找不到Node.js 未安装或全局安装路径不在 PATH 中重新安装 Node.js检查 npm 全局 bin 路径使用npx anthropic-ai/claude-code临时运行代理启动成功但 Claude Code 无响应代理未处理流式响应或请求格式不兼容查看代理日志换用较成熟的社区代理工具降低模型请求参数复杂度5.1 模型名报错的深入分析“模型名不被识别”是出现频率最高的问题。原因主要有两个第一Claude Code 内置了模型白名单或默认模型列表。如果你把ANTHROPIC_MODEL设置成一个它不认识的字符串启动时或请求时就会报错。这并不代表 DeepSeek 模型不存在而是 Claude Code 没有识别。第二代理层有自己的模型映射表。代理工具需要知道“Claude Code 请求的 model 字段”应该映射到“DeepSeek 的哪个模型”。如果映射表过旧或者没有配置 fallback 规则就会报错。解决方案优先顺序查官方文档确定 DeepSeek 当前可用的模型名。换用官方推荐的模型名比如deepseek-chat。升级代理工具到最新版本。如果使用开源代理检查其模型映射配置必要时手动加一行映射。这里特别提醒不要轻信网上流传的“隐藏模型名”或“未发布模型”。很多模型名看起来很像 DeepSeek 未来版本但 DeepSeek 平台根本还没有开放强行配置只会浪费时间。5.2 HTTP 400 的排查示例假设你遇到下面这个错误cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the reasoning_content in the thinking mode must be passed back to the api.这句话的关键信息是provider: deepseek请求被路由到了 DeepSeek。model: deepseek-v4-flash使用的模型名。upstream_status: http 400DeepSeek API 返回 400。reasoning_content in the thinking mode must be passed back to the apiDeepSeek 要求思考模式中的reasoning_content必须原样回传。出现这种问题说明代理层在转发多轮对话时把上一轮模型返回的reasoning_content丢掉了。DeepSeek 的对话接口在开启思考模式时要求客户端在下一轮请求中带上这个字段否则报 400。排查步骤关闭思考模式去 DeepSeek 平台或 API 参数中关闭思维链相关开关看是否恢复正常。更新代理工具检查代理工具的版本看 issue 里是否有人反馈同样问题。查看完整请求日志在代理层打印完整请求体确认messages数组中是否包含reasoning_content。5.3 关于 Claude Code 529 错误“claude code 529” 这个关键词在社区里也比较常见。529 通常表示服务过载或限流。当你把 Claude Code 接入 DeepSeek 后如果代理层没有正确转换请求也可能出现 529 或类似错误。解决思路检查请求是否真的到达 DeepSeek还是被某个中间层拦截。查看代理日志中的上游状态码如果上游返回 529说明 DeepSeek 侧限流需要降低请求频率或稍后重试。如果 529 来自 Claude Code 本身说明它可能在尝试访问官方服务检查ANTHROPIC_BASE_URL是否配置成功。5.4 排查清单如果你已经按教程操作但依然卡住建议按以下顺序排查确认 Node.js 版本大于等于 18。确认claude --version能输出版本号。确认 DeepSeek API Key 格式正确且在平台上有余额或额度。确认ANTHROPIC_BASE_URL指向的地址能访问用 curl 测试。确认代理服务日志中有请求进来。确认代理服务日志中上游返回的状态码是 200。如果返回 400检查请求体中的 model 字段和 messages 结构。如果返回 401检查 Authorization 头是否带上了 DeepSeek API Key。如果返回 404检查接口路径是否正确。最后再检查 Claude Code 版本和代理工具版本是否兼容。6. 最佳实践与工程建议6.1 使用版本管理工具锁定 Node 版本Claude Code 对 Node.js 版本有要求不同版本的行为也可能有差异。建议在项目目录中维护.nvmrc文件echo 18 .nvmrc使用时执行nvm use即可自动切换到对应版本。这能减少因为 Node 版本不一致导致的奇怪问题。6.2 合理管理 API KeyDeepSeek API Key 是敏感信息不要硬编码在代码或提交到 Git 仓库。建议使用.env文件并在.gitignore中忽略它。使用系统的密钥管理工具或 CI/CD 的 secret 配置。定期轮换 API Key防止泄露。例如在.gitignore中添加.env6.3 学会看日志无论是 Claude Code 还是代理工具日志都是排查问题的第一手资料。很多代理工具支持DEBUG环境变量来自动输出详细日志export DEBUG*开启后你能看到完整的请求和响应内容。通过日志理解“Claude Code 实际发了什么”和“DeepSeek 实际返回了什么”比盲目猜测高效得多。6.4 保持代理层薄而专一如果使用本地代理尽量让代理层只做“协议转换”不要在里面堆叠太多业务逻辑。代理越复杂越难排查问题。社区中的成熟项目通常已经处理好了流式、超时、错误码映射优先复用。6.5 模型选型建议DeepSeek 平台通常会提供不同定位的模型比如对话模型、推理模型、代码模型。在 Claude Code 中配置主模型和轻量模型时建议根据任务类型选择需要复杂代码生成和重构使用能力强的主模型。简单问答、格式化、补全使用快速轻量模型。模型名称和定位以 DeepSeek 官方文档为准因为不同时期的模型命名差异较大这里不写死具体名称。6.6 注意流式响应Claude Code 的交互体验依赖流式输出。如果代理层不支持 Server-Sent EventsSSE流式响应每次请求都要等完整结果返回体验会非常差。选择代理工具时确认它支持流式转发。6.7 安全与合规提示本教程涉及的 API 调用、本地代理等操作都属于正常的开发工具配置。在实际生产环境中使用时注意不要在公共网络传输未经加密的 API Key。涉及公司项目代码时确认模型服务的数据处理条款是否满足合规要求。如果使用第三方代理工具先评估其代码可信度不要随意向不明服务发送项目代码。7. 总结与下一步这篇文章从 Claude Code 和 DeepSeek 的基础概念讲起解释了 Claude Code 为什么默认不能直接使用 DeepSeek以及如何通过环境变量、本地代理或社区工具实现接入。核心流程可以概括为四步安装 Node.js 和 Claude Code。申请 DeepSeek API Key。配置ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL等环境变量。启动代理或使用社区 Router 工具让 Claude Code 的请求能正确转发到 DeepSeek。同时我还整理了模型名不识别、HTTP 400、529 报错、组织订阅限制等高频问题的排查思路。遇到问题不要急着换工具先看日志再定位是网络、鉴权还是格式转换的问题。完成基础接入后你可以继续探索在 Claude Code 中编写自定义 Skill技能提升特定场景下的自动化能力。对比 Claude Code 使用 DeepSeek 和官方 Claude 模型的差异找到最适合自己项目的配置。深入研究 Anthropic Messages API 和 OpenAI Chat Completions 的协议差异自己改造代理层。结合 CI/CD 流水线在自动化环境中使用 Claude Code 进行代码审查或文档生成。这套接入方案并不是“银弹”。如果你需要极致的代码生成质量或完整的工具链体验原生 Claude 模型仍然是更稳妥的选择但如果你追求成本和国内网络环境下的可用性DeepSeek 确实是一个很好的平替方案。建议先在测试项目中跑通流程再逐步放大到真实项目。技术选型没有绝对的正确只有适不适合你的场景。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
