Claude Code 接 DeepSeek 这件事，在 2026 年 10 月 17 日 DeepSeek 推出 V4.1-Flash-1017 checkpoint 之后，官方接入指南做了一次实打实的升级：主推模型名换成了 deepseek-flash，配置从早年的两个核心变量扩成了九项环境变量，Claude Code 的 Web Search 工具也被官方原生支持。好消息是，官方直连的路径比以往任何时候都清楚；坏消息是，你现在搜到的不少教程还停在旧版本上——有的还在教已经退休的模型名，有的把 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 混着写，照抄一遍，配了等于白配。
先做分工声明。本站 2026 年 9 月那篇 Claude Code 接 DeepSeek 的最小配置 SOP，写的是 V4-Pro-0813 时代「2 个环境变量」的最小配置思路，解决的是「最快跑通」；本稿对应的是 1017 checkpoint 上线之后的官方现役全量指南——九项环境变量、模型映射、Web Search 计费、effort 与 compact 配置一次给全。两篇不互相替代：赶时间验证可行性看旧文，要长期稳定接 DeepSeek 干活看这篇。另外提醒一句，市面旧教程里还在用 deepseek-chat 这类已退休的模型名，抄之前先核对本文第二节的官方写法。本文所有命令与变量名均以 DeepSeek 官方「接入 Claude Code」指南现行版为准（api-docs.deepseek.com/quick_start/agent_integrations/claude_code，本站实测抓取），价格为官方定价页口径，未独立复测。
一、动手前先认清三个事实
第一，deepseek-flash 现在指的是 DeepSeek-V4.1-Flash-1017，也就是 1017 发布的那一代 Flash。官方 news 页明确写了它是现役模型名，官方指南的九项变量里主模型用的就是它。
第二，模型名有退休机制。deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 已经退休，但官方仍然接受这两个名字的请求，按 Flash 价格计费——所以那些老配置暂时不会报错，这也正是旧教程「看起来还能用」的原因。至于 deepseek-chat 这类名字，属于更早一代的残留，新接入手别再往配置里写。
第三，配置的复杂度变了。早期两个变量（base URL 加 AUTH_TOKEN）确实能跑通，但官方现在的推荐配置是九项：主模型、opus/sonnet/haiku 三档映射、subagent 模型、effort 等级、自动压缩窗口，各占其位。少配几项不一定会立刻报错，但会以两种不易察觉的方式还债：一是默认映射把贵的模型算到你账上（第四节细说），二是长会话被过早压缩、缓存被击穿，token 费用悄悄涨。
这三个事实合起来其实指向同一个结论：接 DeepSeek 这件事，官方已经把路铺好了，剩下的风险全部来自「照抄了过时的路」。所以本文的写法是先给官方原文配置，再解释每一项为什么存在，最后把社区踩过的坑摆在明面上——你按顺序操作即可，不需要自己再去各处拼教程。
二、迁移路径：已装 Claude Code，补齐九项环境变量
如果你机器上已经有能跑的 Claude Code，迁移不需要重装任何东西，只需要重新设置环境变量。以下为官方指南原文的九项，先给 Linux / Mac 版（终端直接执行）：
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<DeepSeek API Key>
export ANTHROPIC_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-flash
export CLAUDE_CODE_EFFORT_LEVEL=max
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=786432Windows PowerShell 对应写法（变量名完全一致，语法换成 $env 赋值）：
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<DeepSeek API Key>"
$env:ANTHROPIC_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-flash[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-flash"
$env:CLAUDE_CODE_EFFORT_LEVEL="max"
$env:CLAUDE_CODE_AUTO_COMPACT_WINDOW="786432"九项变量逐个说一句。ANTHROPIC_BASE_URL 指向 DeepSeek 的 Anthropic 兼容端点，这是整条链路的入口，原样照抄即可。ANTHROPIC_AUTH_TOKEN 填你的 DeepSeek API Key，注意变量名是 AUTH_TOKEN，不是 API_KEY，这两者的区别在第七节展开。ANTHROPIC_MODEL 设定主模型为 deepseek-flash[1m]，[1m] 这个后缀是官方指南的原文写法，照抄即可。ANTHROPIC_DEFAULT_OPUS_MODEL 和 ANTHROPIC_DEFAULT_SONNET_MODEL 都显式钉到 deepseek-flash[1m]，这一步直接决定你在 Claude Code 里选 opus、sonnet 档位时实际调的是哪个模型、按哪个价计费，是控成本的关键。ANTHROPIC_DEFAULT_HAIKU_MODEL 与 CLAUDE_CODE_SUBAGENT_MODEL 用不带 [1m] 后缀的 deepseek-flash，轻量任务和后台子 agent 不需要长上下文档位。CLAUDE_CODE_EFFORT_LEVEL=max 把推理努力拉满，这是官方推荐值。CLAUDE_CODE_AUTO_COMPACT_WINDOW=786432，约 75 万 token 的自动压缩窗口，长会话场景尤其重要。
变量设完，进入项目目录启动：
cd 你的项目目录 && claude还要说明一点：无论 export 还是 $env 赋值，都只对当前这个终端会话有效，关掉窗口就失效。所以推荐的操作节奏是：验证阶段用临时变量，确认整条链路跑通、模型映射符合预期之后，再把九项按第七节坑三的方式固化到 shell 配置文件或系统环境变量里。先验证再固化，能避免把错误配置写成长期状态。
三、从零安装：四步跑通
还没装过 Claude Code 的读者走这四步。
第一步，准备运行环境：Node.js 18 及以上版本；Windows 用户另外需要装 Git for Windows。这两项是官方指南写明的前置条件，装齐再往下走，能省掉后面环境报错的排查时间。
第二步，全局安装 Claude Code：
npm install -g @anthropic-ai/claude-code第三步，验证安装：
claude --version能打印出版本号即安装成功。
第四步，取 key、配变量、启动。API Key 在 DeepSeek 开放平台创建（platform.deepseek.com/api_keys），创建后只显示一次，先复制保存好；然后按第二节的代码块配好九项环境变量；最后进入你的项目目录，执行 claude 启动会话。
四、模型映射：opus 默认走 deepseek-v4-pro，按 Pro 价计费
这一节是整篇里最影响账单的部分，官方口径原文给出：在 Anthropic 兼容端点上，Claude Code 发出的 claude-opus 系列请求会被映射到 deepseek-v4-pro，并且按 V4 Pro 的价格计费——Pro 比 Flash 贵。如果你不主动改映射，opus 档位的每一次调用都在按贵的那个价走。claude-haiku 与 claude-sonnet 系列则默认映射到 deepseek-flash，这部分没有价差问题。
这就是为什么第二节九项变量里，ANTHROPIC_DEFAULT_OPUS_MODEL 和 ANTHROPIC_DEFAULT_SONNET_MODEL 要显式写成 deepseek-flash[1m]：显式映射就是你的成本手闸。当然，如果你的场景确实需要 Pro 的能力上限，保留默认映射、让 opus 走 deepseek-v4-pro 也说得通，前提是你清楚这条线的计价口径，知道账单会往哪个方向走。
怎么选，给一个可操作的判断框架。日常编码、改 bug、写测试这类任务，Flash 档位配合 effort=max 已经足够应付，这也是官方指南把主模型钉在 deepseek-flash[1m] 的原因；真正吃重推理的场景——比如大型重构的方案设计、跨模块的架构决策——才值得考虑让 opus 映射到 Pro。还有一条折中路：平时把三档映射全钉在 Flash 上跑日常，遇到确需重火力的任务，再临时改回默认映射单独跑那一单，改完记得改回来。映射是变量级别的开关，切起来没有成本，成本只出现在账单上。
官方指南还提到一个同端点的用法：Claude Desktop APP 的开发者模式里改 base_url 和 api_key，可以绕过 APP 内置的模型名限制接 DeepSeek。这属于官方明说的能力，但走这条路时模型行为与计费同样遵循上面的映射规则，该按 Pro 价算的还是按 Pro 价算。
五、Web Search 能用，但搜索是单独计费的
DeepSeek API 原生支持 Claude Code 的 Web Search 工具，你不需要额外装任何搜索插件。但官方把账算得很清楚，一共两条线：搜索请求本身按 Search API 计费；对检索到的内容做摘要，还会产生额外的 LLM token 费用。两条费用叠加，搜索越频繁，账单涨得越快。
给 agent 配了联网搜索之后，建议养成两个习惯：一是留意账单曲线，发现搜索费用占比异常再回头看是不是搜索触发得太随意；二是在提示词里约束搜索时机，把「随手一搜」变成「确认需要再搜」，不然联网搜索很容易变成固定开销的大头。
六、价格口径：off-peak 与 peak 两个价
按官方定价页口径（未独立复测），deepseek-flash 的 off-peak 价格为：输入每百万 token 0.15 美元（cache miss 情形），cache hit 每百万 token 0.003 美元，输出每百万 token 0.60 美元。peak 时段为工作日 UTC 01:00 至 04:00 与 06:00 至 10:00，价格翻倍；周末与中国法定节假日全天按 off-peak 计。
agent 场景对缓存特别敏感。Claude Code 的长会话每一轮都携带大量重复前缀，cache hit 与 cache miss 之间的价差是五十倍，同一份系统提示词和上下文，命中缓存与未命中是两个价。九项变量里把 AUTO_COMPACT_WINDOW 调大到 786432，本质上也是为了减少长会话被切碎、缓存前缀失效的次数。跑批任务尽量落在 off-peak 时段，同样的活，账单差距可以直接拉开一倍。
粗算一笔账感受量级：off-peak 时输入一百万 token，cache miss 花 0.15 美元，peak 花 0.30 美元，翻倍；而这百万 token 里如果绝大部分命中缓存，cache hit 价只需 0.003 美元，与 miss 相差五十倍。Claude Code 一次会话动辄几十轮、每轮重复携带完整上下文，命中与不命中的差距乘上轮数，就是月末账单上的实在数字。所以 agent 时代看价格，不能只看输入输出单价的绝对值，缓存策略和时段选择同样是账单的一部分。
七、常见坑：五个都在配置与验证环节
坑一，AUTH_TOKEN 与 API_KEY 不是一回事。Claude Code 要的是 ANTHROPIC_AUTH_TOKEN；ANTHROPIC_API_KEY 是 Anthropic SDK 场景用的变量。把 key 填进错误的变量，客户端不会提示「变量名错了」，而是直接鉴权失败——这是本站旧文里实际踩过并验证过的教训，也是接入失败案例里最常见的一类。
坑二，新旧环境变量并存可能引发鉴权冲突。如果你之前接过别的 Anthropic 兼容服务，shell 配置文件里很可能残留旧的 ANTHROPIC 相关变量，客户端取到哪个就听哪个，结果就是明明配了新端点却连到旧服务。建议只保留本次的新变量，把旧的清干净（此条为社区教程口径，二手信息，供参考）。
坑三，密钥不要进 git。把 key 写进项目的 settings.json 再提交仓库，是真实发生过的泄露路径，公开仓库被爬是分分钟的事。固化方式用 ~/.bashrc 或 ~/.zshrc（Linux / Mac），Windows 用系统环境变量，让密钥只留在本机。
坑四，接好先做最小任务验证。不同模型的工具调用能力有差异，直接上真活，容易把「模型不行」和「没配好」搅在一起，排查起来两眼一抹黑。先跑一个最小任务：让 agent 读一个文件、再改一个文件，确认 Write、Bash、Read 三类工具调用都正常，再交付真实工作。
坑五，用 /status 查当前生效模型。配置是否真的生效，不要靠感觉，会话里跑一次 /status，看到当前生效模型是 deepseek-flash 系列才算数。这一步顺手就能做，能省掉大量「我明明配了」式的无效排查。
五个坑过完，给一份收尾验收清单，五项全过再算接完：一，/status 显示生效模型为 deepseek-flash 系列；二，最小任务里 Write、Bash、Read 三类工具调用各成功一次；三，终端配置文件里没有残留的旧 ANTHROPIC 变量；四，密钥只存在于 shell 配置或系统环境变量，未被写进任何会提交 git 的文件；五，看一眼账单页，确认计费模型与价格档位和你的映射预期一致。这份清单花不了五分钟，但能把事后排查的时间全部省下来。
FAQ
Q1：ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 到底有什么区别？
A1：Claude Code 识别的是 ANTHROPIC_AUTH_TOKEN，DeepSeek 官方指南用的也是它；ANTHROPIC_API_KEY 主要用于 Anthropic SDK 的开发场景。两者鉴权路径不同，混用或填错变量名是「配了没反应」的头号原因。接 Claude Code，就把 key 放进 AUTH_TOKEN。
Q2：旧教程里的 deepseek-chat、deepseek-v4-flash 这些模型名还能用吗？
A2：deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 已退休，但官方仍接受请求并按 Flash 价计费，所以旧配置暂时不会报错；deepseek-chat 这类名字属于旧教程残留，新接入手不要再用。照官方指南现行版写 deepseek-flash 即可。
Q3：不配 ANTHROPIC_DEFAULT_OPUS_MODEL 会怎样？
A3：会走官方默认映射，opus 系列请求映射到 deepseek-v4-pro 并按 V4 Pro 价计费，比 Flash 贵。想控成本，就按本文第二节把 opus、sonnet 显式钉到 deepseek-flash[1m]；确实需要 Pro 能力，可以留默认映射，但要清楚账单口径。
Q4：在 Claude Code 里用 Web Search 怎么收费？
A4：两条线叠加：搜索请求本身按 Search API 计费；对检索内容的摘要还会产生额外的 LLM token 费。搜索越频繁费用越高，建议留意账单并约束搜索触发时机。
Q5：API Key 想长期固化，写在哪里比较安全？
A5：不要写进会提交到 git 的 settings.json。Linux / Mac 固化在 ~/.bashrc 或 ~/.zshrc，Windows 用系统环境变量；如果此前残留过其他服务的 ANTHROPIC 变量，顺手清掉，避免鉴权冲突。
延伸阅读
- DeepSeek 又上新：权重免费下，任务账单砍六成：DeepSeek 又上新：权重免费下，任务账单砍六成
- 实战SOP｜一行 npx 跑起 DeepSeek Harness：安装、四种模式、轨迹回放到第一个插件：DeepSeek Harness 快速上手：官方 agent 环境第一条命令
- ## 实测背景与方法：Claude Code、Cursor、Codex 三家横评：终端、编辑器与云端各归各位