Claude Code 接入 DeepSeek 完整教程 - V3、R1 编程实战

很多人选 Claude Code 是冲着它的工具调用和文件编辑能力，但官方 Anthropic API 的账单太肉痛。claudecode 接入 deepseek 是国内最常见的省钱方案：DeepSeek V3、R1 的编码能力在国产模型里第一梯队，价格不到 Sonnet 的十分之一，国内直连还不用 claude code 接入国内模型必须要代理吗 这种问题——答案是不用。

本文不绕弯子，直接给两条可落地的路径：方案 A 用 LiteLLM 自建协议转换层（最稳、最干净），方案 B 用支持 Claude 协议的中转聚合站（懒人路径，有风险）。两条路都给完整配置和踩坑清单。如果你还没装 Claude Code，先看 Claude Code 国内安装教程。

为什么要把 DeepSeek 接进 Claude Code

抛开”省钱”这个最大动机，还有几个真实的工程理由：

动机	Anthropic 官方	DeepSeek 接入
价格	输入 $3 / 百万 token 起	输入约 ¥1-2 / 百万 token
国内延迟	200-800ms（需代理）	50-150ms（直连）
合规	数据出境	国内厂商，业务数据不出境
限流	5h 配额机制	按量计费，配额宽松
模型选择	Opus / Sonnet / Haiku	V3 / R1 / Coder

claude code 国内模型 真正解决的是合规和成本，能力上要诚实承认有差距。下面会专门列差距清单。

DeepSeek V3 / R1 / Sonnet 编程能力简评

不是基准跑分，是日常用 Claude Code 跑活儿的主观感受：

模型	单文件代码生成	跨文件重构	Agentic 多步骤	工具调用稳定性	中文沟通
Claude Sonnet	优秀	优秀	优秀	顶级	优秀
DeepSeek V3	优秀	良好	中等	良好	优秀
DeepSeek R1	顶级（推理）	中等	中等偏弱	一般	优秀
DeepSeek-Coder	良好（专一）	中等	一般	良好	优秀

R1 适合做”想清楚再写”的任务，比如算法题、复杂 bug 定位；但它的 thinking token 在 Claude Code 这种交互式场景下偶尔会让响应变慢，工具调用前犹豫太久。V3 更适合做 Claude Code 默认替代品，平衡推理深度和速度。

协议差异：为什么不能直接换 base URL

这是大多数新手踩的第一个坑。Claude Code 客户端发出的请求是 Anthropic Messages API 格式：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "messages": [
    {"role": "user", "content": "..."}
  ],
  "tools": [...],
  "system": "..."
}

DeepSeek 提供的是 OpenAI Chat Completions 兼容协议：

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."}
  ],
  "tools": [...]
}

两者差异不止换字段名：

• system 在 Anthropic 里是顶层参数，OpenAI 里是 messages[0]
• 工具调用返回结构完全不同（Anthropic 用 tool_use block，OpenAI 用 tool_calls）
• 流式 SSE 事件类型不一样（message_delta vs chunk.delta）
• max_tokens 在 Anthropic 是必填，OpenAI 是可选

所以必须有协议转换层。你直接把 ANTHROPIC_BASE_URL 指向 https://api.deepseek.com，连第一次 hello 都过不去。

---

方案 A：LiteLLM 自建本地代理（推荐）

LiteLLM 是开源的 LLM 网关，原生支持 Anthropic 协议入站 + 任意厂商出站。优点是完全自己掌控、所有日志可见、想加自定义中间件也方便。

第 1 步：安装 LiteLLM

# 推荐用虚拟环境，避免污染系统 Python
python -m venv litellm-env
source litellm-env/bin/activate     # macOS / Linux
# Windows PowerShell:
# litellm-env\Scripts\Activate.ps1

pip install "litellm[proxy]"

如果 pip 慢，国内可以加镜像：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple "litellm[proxy]"

验证安装：

litellm --version

第 2 步：拿到 DeepSeek API Key

去 platform.deepseek.com 注册账号，实名认证后在 “API Keys” 页面创建一个 key，形如 sk-xxxxxxxxxxxxxxxxxx。第一次注册通常有免费额度，做测试足够。

第 3 步：写 LiteLLM 配置文件

新建 litellm_config.yaml：

model_list:
  # Claude Code 会以 "claude-sonnet-4-6" 之类的名字请求
  # 我们把它映射到 DeepSeek 后端
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY
      api_base: https://api.deepseek.com

  - model_name: claude-opus-4-7
    litellm_params:
      model: deepseek/deepseek-reasoner
      api_key: os.environ/DEEPSEEK_API_KEY
      api_base: https://api.deepseek.com

  - model_name: claude-haiku-4-5
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY
      api_base: https://api.deepseek.com

litellm_settings:
  drop_params: true              # 丢弃 DeepSeek 不认的字段，避免 400
  set_verbose: false             # 调试时改 true 看完整请求
  num_retries: 2
  request_timeout: 120

general_settings:
  master_key: sk-litellm-local   # Claude Code 端用这个当 API key

几个关键点：

• model_name 必须包含 Claude Code 实际会发送的模型 ID。drop_params: true 是救命选项，DeepSeek 不接受 top_k、stop_sequences 等字段会直接报错。
• deepseek-chat 对应 V3 系列，deepseek-reasoner 对应 R1 系列。具体模型名称以 platform.deepseek.com 文档为准。
• master_key 是本地代理的访问凭证，不是 DeepSeek 的 key，可以随便设。

第 4 步：启动 LiteLLM 代理

export DEEPSEEK_API_KEY=sk-你的真实-deepseek-key

# macOS / Linux
litellm --config litellm_config.yaml --port 4000

# Windows PowerShell
$env:DEEPSEEK_API_KEY = "sk-你的真实-deepseek-key"
litellm --config litellm_config.yaml --port 4000

输出里看到 LiteLLM: Proxy initialized 就算成功。

另开一个终端测试连通：

curl -X POST http://localhost:4000/v1/messages \
  -H "x-api-key: sk-litellm-local" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "用一句话介绍你自己"}]
  }'

返回里如果模型自报家门是 DeepSeek，桥接就成功了。

第 5 步：配置 Claude Code

编辑 ~/.claude/settings.json（Windows 是 %USERPROFILE%\.claude\settings.json）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-local"
  },
  "model": "claude-sonnet-4-6"
}

或者临时用环境变量：

export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=sk-litellm-local
claude

启动 claude 后问一句 “你是哪家公司训练的模型”，如果回答里出现 “DeepSeek”，整条链路就跑通了。更多 base URL 细节看 Claude Code 代理配置教程。

---

方案 B：用 Claude 协议中转聚合站

市面上有不少 claude code 接入其他模型 的中转服务（这里不点名具体服务商），它们把多家国产模型统一封装成 Anthropic 协议端点，你只要拿到一个 API key 就能用。

配置极简：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://中转服务商域名",
    "ANTHROPIC_AUTH_TOKEN": "sk-中转服务商的key"
  }
}

优点是省去自建网关的麻烦，缺点要诚实告知：

• 请求会经过第三方，你的代码片段、prompt 都路过他们的服务器，敏感项目千万别用
• 中转服务的稳定性看运营方良心，跑路、限速、私自换模型都发生过
• 多一层加价，长期成本不一定比直接付 DeepSeek 便宜
• 一旦出问题你完全没排查权限

如果是个人小项目、玩票尝鲜，方案 B 能省事；公司代码、长期使用一定走方案 A 或正规 Claude API 中转聚合站 文章里讨论的合规渠道。

---

DeepSeek V3 在 Claude Code 里的实测体验

跑了一个真实场景：在一个约 300 文件的 TypeScript 项目里让它修一个 React 状态同步 bug，要求读 5-6 个相关文件、改 2 个文件、跑测试。

维度	表现
流式响应	顺畅，无明显卡顿
工具调用（Read/Edit/Bash）	90% 调用正确，偶尔 Edit 的 old_string 缺尾随空格导致匹配失败
多文件理解	比 Sonnet 弱一档，需要更明确地告诉它”先读 X、再读 Y”
代码风格一致性	良好，能模仿原项目风格
中文注释	优秀，比 Sonnet 更地道
单次任务总耗时	比 Sonnet 慢约 30%，但成本只有 1/10

结论：DeepSeek V3 可以做 Claude Code 的日常替代，但要做好”偶尔需要手动纠错”的心理预期。复杂的跨文件重构、大型 Agentic 任务，体感还是不如 Sonnet 顺手。

---

已知坑与排查

坑 1：工具调用参数对不上

DeepSeek 偶尔会把 Anthropic 期望的 tool_use block 翻译成略有不同的字段名，比如把 input 错放成 parameters。表现是 Claude Code 报 “tool_use block invalid” 或者工具调用静默失败。

排查：

# 在 LiteLLM 启动时打开 verbose
litellm --config litellm_config.yaml --port 4000 --debug

看完整请求/响应日志，定位是 LiteLLM 没翻译对，还是 DeepSeek 返回就有问题。LiteLLM 大版本每隔几周更新一次工具调用转换逻辑，老版本经常踩这个坑：

pip install -U "litellm[proxy]"

坑 2：长上下文被截断

DeepSeek V3 上下文窗口（截至本文撰写时）约 128K，比 Claude Sonnet 的 200K 小一档。在 Claude Code 里跑大项目时，长对话或多文件读取很快会超限。

表现是请求被静默截断、模型”忘记”前面对话、或者直接报 400 context length exceeded。

应对：

• 频繁用 /compact 命令压缩历史
• 大型重构任务拆成小步骤
• 在 LiteLLM 配置里限制 max_input_tokens，提前在网关拦掉超长请求

坑 3：流式响应字段错位

Claude Code 是流式 UI，强依赖 SSE 事件顺序。LiteLLM 把 OpenAI delta 翻译成 Anthropic 的 message_delta / content_block_delta 时，偶发字段顺序错乱，表现是 UI 上文字”卡半秒一坨”地出来，而不是丝滑流式。

这个坑短期没完美解，部分缓解方案：

litellm_settings:
  drop_params: true
  stream_options:
    include_usage: true

实在不能忍的话改用非流式（修改 Claude Code settings 是不可行的，只能通过中间层强制 buffer），但会牺牲交互体验。

坑 4：DeepSeek-Reasoner 的 thinking 内容

R1 系列输出会先有一大段 <thinking>...</thinking> 推理过程。LiteLLM 较新版本会自动剥离或映射到 Anthropic 的 thinking content block，老版本会原样塞进正文，Claude Code 渲染时会把推理过程当成正常输出，体验糟糕。

升级 LiteLLM 到最新版能解决大部分情况：

pip install -U "litellm[proxy]"

坑 5：local proxy 没启动 Claude Code 报 connection refused

最常见的”小白错误”。每次重启电脑、关掉终端，LiteLLM 进程就没了。建议用 pm2、systemd、launchctl 或 Windows 任务计划设置开机自启。

简单的 pm2 启动：

npm install -g pm2
pm2 start "litellm --config /path/to/litellm_config.yaml --port 4000" --name litellm-deepseek
pm2 save
pm2 startup

---

排查接入失败的标准流程

链路：Claude Code → 本地 LiteLLM → DeepSeek API。三个环节挨个验证。

1. LiteLLM 是否在跑

curl http://localhost:4000/health

2. LiteLLM 能否打到 DeepSeek

curl -X POST http://localhost:4000/v1/messages \
  -H "x-api-key: sk-litellm-local" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'

返回 401 是 LiteLLM master_key 错；返回 5xx 是 DeepSeek key 错或网络问题；返回 200 但内容奇怪，看 LiteLLM 日志。

3. Claude Code 是否读到正确配置

claude --print "echo your base url"

或者在 Claude Code 内 /config 看当前生效的 ANTHROPIC_BASE_URL。优先级：环境变量 > settings.json，如果环境里有残留的 ANTHROPIC_BASE_URL 会覆盖 settings.json。

清干净：

# macOS / Linux
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN

# Windows PowerShell
Remove-Item Env:ANTHROPIC_BASE_URL
Remove-Item Env:ANTHROPIC_API_KEY
Remove-Item Env:ANTHROPIC_AUTH_TOKEN

---

切回 Claude 官方的命令

折腾完 DeepSeek 想切回 Anthropic 原生：

# macOS / Linux
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_API_KEY=sk-ant-你的官方key

# Windows PowerShell
Remove-Item Env:ANTHROPIC_BASE_URL
Remove-Item Env:ANTHROPIC_AUTH_TOKEN
$env:ANTHROPIC_API_KEY = "sk-ant-你的官方key"

claude

或者把 ~/.claude/settings.json 改回默认（删掉 env 块）：

{
  "model": "claude-sonnet-4-6"
}

更多模型切换姿势看 Claude Code 切换模型完整教程。

---

FAQ

claudecode 接入 deepseek 真的能省钱吗？

按 token 单价是显著省，但实际使用要看你的工作流。如果你接 DeepSeek 后用得更频繁、更敢”试错”，总账单可能没降多少。真正省钱的策略是分级：日常代码用 DeepSeek V3，疑难杂症切回 Sonnet。

不想自建 LiteLLM，有没有更简单的方案？

有，方案 B 中转聚合站就是。但要接受第三方读你 prompt 的风险，并且服务稳定性不可控。再懒一点的话用 Claude Code 私有化部署 里说的企业方案，但那个面向团队不面向个人。

DeepSeek V3 和 R1 在 Claude Code 里选哪个？

日常编码选 V3。算法、推理、复杂 bug 定位偶尔切 R1。R1 的 thinking 在交互式场景下偶尔让人难受，但拼复杂逻辑确实是国产里最强的之一。

接入后 Claude Code 的 /cost 命令准吗？

不准。/cost 是按 Anthropic 定价表算的，接入 DeepSeek 后那个数字毫无意义。真实成本要看 LiteLLM 日志或 DeepSeek 平台账单。

能同时配多个国产模型，按需切换吗？

可以。在 LiteLLM 的 model_list 里多写几个 model_name，然后在 Claude Code 里用 /model 命令切换。比如把 claude-sonnet-4-6 映射到 DeepSeek V3，claude-opus-4-7 映射到 GLM 4.6，看心情选。

工具调用一直失败怎么办？

按这个顺序排查：升级 LiteLLM → 升级 Claude Code → 改 drop_params: true → 在 LiteLLM 开 debug 看完整请求 → 把模型换成最新版 deepseek-chat（DeepSeek 有时悄悄升版本，旧别名工具调用会退化）。如果还不行，建议先用 V3 而非 R1，工具调用稳定性差距比想象中大。

Claude Code 用 DeepSeek 时 sub-agent 会工作吗？

Sub-agent 高度依赖工具调用准确性和长上下文，DeepSeek 在这块比 Sonnet 弱明显。简单的 sub-agent 任务能跑，但复杂编排（比如 /agents 自定义的多层调度）容易在中途出错。重要的 sub-agent 工作流强烈建议留在 Anthropic 官方。