DeepSeek接入Claude Code：完整配置教程
还是那个终端，还是那些快捷键、斜杠命令、你已经习惯成自然的工作流。驾驶舱里什么都没变——但掀开引擎盖，底下的发动机换了。回答你的模型现在是 DeepSeek V4，跑在你自己的 API 余额上。
这就是 DeepSeek接入Claude Code 的全部卖点，而且动静比想象中小得多：不需要代理层，不需要魔改客户端，不需要包装脚本。DeepSeek 官方开放了一个说 Claude 原生协议的端点，你只要用几个环境变量把 Claude Code 的请求改道过去，所有使用习惯原样保留。这篇教程走完整条路——安装、配置、验证、排错——官方配方放前面，社区实测的真相放后面。这套搭配我自己从春天用到现在，下面的笔记就是我第一天时希望有人递给我的东西。
DeepSeek Claude Code 连接是怎么工作的
想象一个电源转接头：电器不用改，插座不用改，转接头负责在中间翻译。DeepSeek 在 https://api.deepseek.com/anthropic 跑着一个 Anthropic 兼容 API，专门为了让 Claude 生态里的工具即插即用。Claude Code 只认一个变量——ANTHROPIC_BASE_URL——一旦指向 DeepSeek，所有请求就此改道。
两个细节让这套接入比看上去更稳。
其一，Claude Code 在设置了自定义 base URL 时不校验模型名。模型字符串原样透传给供应商，所以你可以在官方预期填 Claude 名字的槽位里写 deepseek-v4-pro[1m]——客户端不管，转发就是。
其二，DeepSeek 服务端会兜底接住漏网之鱼。claude-opus 开头的名字映射到 deepseek-v4-pro，claude-sonnet、claude-haiku 开头的映射到 deepseek-v4-flash；完全不认识的名字不报错，直接落到 v4-flash。所以哪怕配置只做了一半，多半也能跑——只是悄悄地全线用了轻量模型。
同样重要的是"什么没变"。你的 CLAUDE.md 项目指令、斜杠命令、权限规则、MCP 服务器、钩子、子代理定义——这些全在客户端本地，换后端一根毫毛都动不了。服务端看到的只是模型请求、返回的只是模型响应。有人反馈某模型"不理 CLAUDE.md"，那是模型听不听话的问题，不是文件没加载——指令每次请求都随行。
开始之前：API Key 与前置条件
备齐三样东西：
- DeepSeek API Key。 在 DeepSeek 开放平台创建，
sk-开头。计费按 token 用量走，先充几美元额度再开第一次会话——余额见底请求会直接失败。 - Node.js 18 或更高（走 npm 安装的话）。Windows 用户还要装 Git for Windows，它提供 Claude Code 依赖的 bash 环境。
- 想好 Key 放哪。 这个 Key 有账户级消费权限，别提交进 git 仓库——放进
.gitignore的 env 文件或系统的密钥管理工具才是正路。
第 1 步 — 安装 Claude Code
两条官方安装路径，任选其一：
# 原生安装器（Anthropic 当前推荐，macOS/Linux/WSL）
curl -fsSL https://claude.ai/install.sh | bash
# npm 包（DeepSeek 文档给出的路径，需 Node.js 18+）
npm install -g @anthropic-ai/claude-code用 claude --version 验证——能打出版本号，说明二进制已经在 PATH 上。
先埋一句忠告：只保留一种安装。如果原生二进制和一个旧 npm 副本同时存在，shell 可能解析到过期的那个，之后你会追着幽灵 bug 打转。npm 在你的网络太慢的话，装的时候临时切镜像源、装完切回来，是社区里走熟了的路子。
第 2 步 — 把 Claude Code 指向 DeepSeek
DeepSeek接入Claude Code 的核心就在这一步，做法有三种。终点相同，区别在改动能活多久、谁能读到它。
方法一：环境变量
官方接入文档给出九个变量的配方。Linux 和 macOS：
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<你的 DeepSeek API Key>
export ANTHROPIC_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-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"——在即将启动工具的那个窗口里执行。
每行到底在干什么：
| 变量 | 作用 |
|---|---|
ANTHROPIC_BASE_URL | 改道开关。所有请求发往 DeepSeek 兼容端点 |
ANTHROPIC_AUTH_TOKEN | 你的 sk- Key，作认证令牌 |
ANTHROPIC_MODEL | 主对话用的模型 |
ANTHROPIC_DEFAULT_OPUS_MODEL | "opus" 档位解析到谁 |
ANTHROPIC_DEFAULT_SONNET_MODEL | "sonnet" 档位解析到谁 |
ANTHROPIC_DEFAULT_HAIKU_MODEL | 轻量 "haiku" 档位解析到谁 |
CLAUDE_CODE_SUBAGENT_MODEL | 后台子代理用的模型 |
CLAUDE_CODE_EFFORT_LEVEL | 思考强度，官方配方钉死 max |
CLAUDE_CODE_AUTO_COMPACT_WINDOW | 自动压缩阈值（token 数，786432 ≈ 768K） |
export 只活一个终端会话。日常使用就追加到 ~/.bashrc 或 ~/.zshrc（或 PowerShell profile）再 source 一次——经典的"怎么设置又忘了"问题，本质就是会话作用域在正常工作——我第一周问了两次，习惯才养成。
方法二：settings.json 配置文件
DeepSeek 自家的集成仓库更推荐配置文件：Linux/macOS 放 ~/.claude/settings.json，Windows 放 C:\Users\<你>\.claude\settings.json。没有就新建：
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "<你的 DeepSeek API Key>",
"ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash[1m]",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"CLAUDE_CODE_EFFORT_LEVEL": "max"
}
}为什么优先用文件？Claude Code 的每个形态都读它——CLI 和 VS Code 扩展通吃——配置跟着工具走，而不是跟着某一个 shell 走。你的 dotfiles 也能保持干净。
诚实脚注：两个官方源发布的变量集不完全一样。API 文档含子代理和自动压缩两个变量；仓库版多了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC，少了那两个。都是官方，都没错——多数实际部署最后是合并着用（文件为主，再补两个环境变量）。
方法三：CC Switch
如果你要轮换后端——今天 DeepSeek、明天另一家——GUI 切换器比手改 JSON 舒服。CC Switch 是开源桌面工具（GitHub 5 万多星），统一管理 Claude Code 和同类 CLI 的多家供应商：预设列表里选 DeepSeek，粘贴 Key，加上模型 ID deepseek-v4-pro[1m]，点启用，再点一下"测试"发个验证请求。它底层写的就是方法二那个 settings.json——本质是个友好的编辑器，不是另一套机制。
快速决策：临时试水 → 方法一；日常主力 → 方法二；多后端切换 → 方法三。
第 3 步 — 验证连接
三块仪表，从便宜到权威。
油表： 在项目里启动工具，跑 /status。配置正确会显示三行——Base URL: https://api.deepseek.com/anthropic、你钉的模型、以及 Small fast model: deepseek-v4-flash。
自检灯： claude doctor 检查安装本身——PATH 问题、工具损坏、版本异常。命令能启动但行为古怪时跑它。
万用表： 绕开客户端直接测端点：
curl -X POST https://api.deepseek.com/anthropic/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <你的 key>" \
-d '{"model":"deepseek-v4-flash","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'返回 JSON，说明 Key、端点、网络全通；报认证错，问题在 Claude Code 上游。
一个预期要先立好：DeepSeek 控制台里同时出现 v4-pro 和 v4-flash 用量是正确的，不是配错了——后台子代理本来就跑 Flash。拿不准时，以供应商用量日志里的 model ID 为准，别信终端显示。
[1m] 后缀与上下文窗口
deepseek-v4-pro[1m] 里那个方括号后缀不是装饰。按 Claude Code 自家配置文档的命名规则，[1m] 表示选用百万 token 上下文窗口——同一个模型的长会话档。官方 DeepSeek 配方在所有主力槽位都钉了它，并配套把自动压缩阈值设为 786432 token：约 768K，在 1M 窗口里留出余量，让压缩赶在你掉下悬崖之前发生。
不带后缀的裸名呢？社区说法不一。一派报告裸 deepseek-v4-pro 默认给较小的窗口，加 [1m] 才解锁百万；另一派坚持官方 API 下两个模型都给 1M。两种说法都没有官方文档背书，所以务实的选择很无聊也很安全：逐字照抄官方配方，括号留着，模型串别自由发挥。
长窗口的实况，来自真把它跑满的人：400K token 的代码库分析，延迟出乎意料地接近原生；但过了 ~500K 就陆续出现"走神"报告。百万窗口是真的；指望它在整段窗口内同样锐利，就乐观了。
什么时候这个后缀真正值回票价？恰恰是 Claude Code 天然制造的那些场景：整仓级提问（"这个函数在哪被调用？"）、连续数小时滚雪球的超长重构、还有那种你一次次 resume 就是不肯重启的长会话。如果只是停在十万 token 以内的常规功能分支，标准窗口根本不会被发现——这也解释了官方配方为什么主力会话给大窗口、子代理给快模型：经济账算得通。
哪个模型接哪类请求
Claude Code 内部排着一张值班表：主对话一个模型，后台子代理（文件搜索、快速摘要、agent 团队）另一个，而 opus/sonnet/haiku 这些别名只是"班次"，排到谁由你钉的变量决定。你的配置就是排班表：
| Claude Code 槽位 | 官方 DeepSeek 配方 |
|---|---|
| 主会话（opus/sonnet 档） | deepseek-v4-pro[1m] |
| 轻量调用（haiku 档） | deepseek-v4-flash |
| 子代理 | deepseek-v4-flash |
| 未映射名称（服务端兜底） | deepseek-v4-flash |
为什么拆开配？钱和速度。有开发者把这套组合连跑一周，发现 Flash 接住了约 80% 的日常活——重构、堆栈报错分析、写新函数——延迟大多在个位数秒，真正难的规划才留给 Pro。对真实会话的分析估计，省钱的大头恰恰来自 haiku 档的路由：每一次轻量内部调用都落在 Flash 的低价档，而不是旗舰价。
还有两个行为值得知道。思考强度 CLAUDE_CODE_EFFORT_LEVEL 控制模型每一步想多深，配方钉在 max（社区观察称 Agent 流量反正会自动拿到 max）。Web Search 原生可用：模型判断问题需要新鲜信息时，会通过 DeepSeek 的 API 调搜索工具，代价是总结检索结果要多花一些 token。
用的是 Claude Desktop 桌面版而不是终端？同一套服务端映射照常生效——它的开发者模式接受自定义 base URL 和 Key，名字翻译交给映射。（这些名字背后的完整模型阵容，见什么是 DeepSeek。）
兼容层到底支持什么
转接头的比喻一直成立到请求字段级。DeepSeek 的 Anthropic 格式端点公开了一份兼容矩阵，知道它的形状，大多数"为什么 X 行为不一样"的疑惑就有了答案：
| 请求字段 | DeepSeek 端点状态 |
|---|---|
temperature（0.0–2.0）、top_p、stop_sequences、stream、system、max_tokens | 完整支持 |
工具定义、tool_choice、工具结果 | 完整支持 |
thinking | 支持——budget_tokens 被忽略 |
| 图像输入（base64、URL、文件） | 支持 |
top_k | 忽略 |
cache_control（提示缓存标记） | 忽略 |
| 文档块、代码执行结果、MCP 工具块 | 不支持 |
日常真正要留意的只有两行。thinking 那行意味着推理深度走 effort 设置而非 token 预算——和配方里的 effort 变量对得上。缓存那行意味着 Anthropic 式缓存标记是空操作；DeepSeek 在计费侧自己做输入缓存命中折扣，不需要你标注缓存断点。Claude Code 默认发出的请求全部落在"支持"列里——这就是为什么这套接入感觉是原生而非硬拼的。
排错：一张表覆盖常见故障
下面每个坑都有人公开踩过。对症状，上解法：
| 症状 | 可能原因 | 解法 |
|---|---|---|
claude: command not found | 二进制不在 PATH，或装了多份 | 重开 shell；which -a claude 和 npm -g ls @anthropic-ai/claude-code 揪出多余副本；只留一份 |
| 登录提示反复出现 | 启动的 shell 没加载变量 | 在启动它的那个 shell 里确认 env；~/.claude.json 写 hasCompletedOnboarding 是社区偏方 |
| WSL 里提示 "Not logged in" | WSL 调到了 Windows 侧的二进制 | 检查 PATH，确保跑的是 Linux 侧安装 |
| 首次请求 401 | Key 错，或余额为零 | 重贴 sk- Key；充值 |
| 403 | base URL 没指到 DeepSeek | 核对 ANTHROPIC_BASE_URL 拼写 |
| 404 | 模型串拼错 | 逐字符照抄 deepseek-v4-pro[1m]——括号也在内 |
| 该出 Pro 的地方出了 Flash | 子代理本来就用 Flash | 先看供应商日志里的请求角色，再下结论 |
| vim 存盘报 E212 | ~/.claude 属主不对 | mkdir -p ~/.claude && chown -R $USER ~/.claude && chmod -R 755 ~/.claude |
| npm install 龟速或失败 | 网络到 registry 不通 | 装时切镜像源，装完切回 |
其中三个值得多说一句。PATH 冲突最阴险——两份二进制、旧的赢了，症状像什么都像，就是不像安装问题。curl 测试是最干净的二分法：一条命令把"Key 和端点"从"客户端和配置"里剥出来。而 404 几乎全是模型名里的隐形字符或丢了括号——所以配方值得粘贴，不值得手打。
预期管理：诚实的利弊账
换过去到底什么体感？公开过的数字形状很一致。
成本：一位知名开发者用 v4-pro 高强度跑 Agent，大约每小时烧 1 美元。一位安全研究员记下了一整个工作日——412 次工具调用、三道专家级 Web 挑战加一个真实 Android 应用——6.84 美元。对照 Anthropic 旗舰上线时点的输出价，v4-pro 每 token 大约便宜七倍，盲测榜单上两者 SWE-bench Verified 相差 0.2 分。（这些是 2026 年 4–5 月窗口的数字，自己算账前先看现价。）
能力：几周社区用下来，公允的概括是"约十分之一的价格，换来 Claude 八成到八成五的体验"。Flash 速度的活几乎无感，Pro 上的硬规划也扛得住。
糙边也是真的。一位长跑用户的清单：有时不理 CLAUDE.md 的指令、要反复提醒才看记忆笔记和编码规则、还做过无人监督的改动，最后靠 git 才捞回来。结论是"便宜，但得盯着"——这个结论我自己的 git reflog 可以作证。两个习惯能拆掉大部分雷：一次只换一个模型槽位，出回归时嫌疑犯明确；凡是让它无人监督改文件的，终端放在眼皮底下。
一个被低估的好处：按 token 计费让每轮成本可见。那条六千 token 的 CLAUDE.md、那三个你早忘了的 MCP 服务器，都变成账单行项——配置文件很快就被清理干净了。
谁该三思？会话真的超过五十万 token、且要求全程高一致性的那类人——漂移报告正是聚在这个区间，旗舰 Claude 模型在这里仍有真实优势。其他人——功能开发、重构、代码评审、日常拉锯——这笔交易怎么算都是赚的。
常见问题
这套方案需要 Anthropic 账号或 API Key 吗？不需要。这条路只用 ANTHROPIC_BASE_URL 加 ANTHROPIC_AUTH_TOKEN 里的 DeepSeek Key，没有任何东西向 Anthropic 认证。如果弹出登录流程，说明启动它的 shell 没加载变量。
免费吗？不免费——DeepSeek API 按量计费，按 token 结算，输入有缓存命中折扣。充个几十块就够跑很久，但空账户会拒绝请求。有新账号赠金的说法，别指望它。
Web Search 能用吗？能，原生支持。模型判断问题需要新鲜资料时，会经 DeepSeek 的 API 调搜索工具。总结检索结果要花额外 token，重度搜索会体现在账单上。
怎么切回官方 Claude 模型？清掉覆盖项即可——删掉环境变量（或 settings.json 里的 env 块），正常登录。用 CC Switch 的话，供应商列表里点一下。
日常写代码用哪个模型？按官方拆法：主会话和难题用 v4-pro，轻量档和子代理用 Flash。社区实测 Flash 一个就能接住约八成日常请求；给两个模型调提示词的话，DeepSeek 提示词技巧里的方法直接通用。
VS Code 扩展里能用吗？能。扩展读的就是同一个 ~/.claude/settings.json——Claude Code配置DeepSeek 的每一处入口都吃这份文件，这正是长期配置优先用文件而不是 shell 变量的原因。
整个迁移就三步：平台拿 Key，把官方九变量配方贴进 shell 或配置文件，/status 确认 base URL 生效。DeepSeek接入Claude Code 这件事，难的不是配置，是知道每个变量在干什么——现在你知道了。之后，驾驶舱还是你的：命令照旧、手感照旧，引擎盖底下换了一台养得起的发动机，油表敢看了。