DeepSeek API 接入 Claude Code 完整指南 — 志趣 ZhiQu 返回首页DeepSeek 节点DeepSeek API 接入 Claude Code 完整指南
DeepSeek API 接入 Claude Code 完整指南
> 把 DeepSeek 作为 Claude Code 的后端模型，享受更低的价格和更快的响应速度。
适配版本：Claude Code CLI v1.0+ · DeepSeek V4 系列 · 2026-06-21
一、简介 & 为什么选 DeepSeek？
| 对比维度 | DeepSeek V4 Pro | Claude Sonnet 4.6（官方） |
|---|
| 编程能力 | 顶尖 | 顶尖 |
| 每百万 Token 价格 | 输入 ¥2 / 输出 ¥8 | 输入 $3 / 输出 $15 |
| 首字响应速度 | Flash 模式约 200-500ms | 约 300-800ms |
| 国内网络 | 直接访问，无需代理 | 需要代理 |
| API 格式 | OpenAI 原生 + Anthropic 兼容 | 原生 Anthropic |
| 图片/文件识别 | 不支持 | 支持 |
> 核心优势：每月编码成本约 ¥18（vs 官方 Claude ≈¥210），节省超过 90%。
二、前置准备：注册 & 获取 API Key
2.1 注册与认证
- 打开 platform.deepseek.com
- 注册并登录（支持国内手机号、微信扫码）
- 进入控制台 → API Keys → 点击「创建 API Key」
- 输入名称（如
claude-code），复制 Key（格式：sk-xxxxxxxxxxxxxxxxxxxxxxxx）
> ⚠️ API Key 只显示一次，请立即保存。绝对不要将含 Key 的配置文件提交到 Git。
2.2 免费额度与账户说明
| 项目 | 说明 |
|---|
| 新用户免费额度 | 注册即送，有效期以控制台显示为准 |
| 余额/用量查询 | 控制台 → Billing |
| 额度耗尽表现 | API 返回 429 或 insufficient_balance |
| 充值入口 | 控制台 → Billing → 充值 |
2.3 API Key 安全守则 ⚠️
# ✅ 推荐：用 .env 文件管理（不提交 Git）
echo 'DEEPSEEK_API_KEY=sk-xxx' > .env
echo '.env' >> .gitignore
# ❌ 禁止：硬编码到 Shell 配置文件后上传 Git
# echo 'export DEEPSEEK_API_KEY=sk-xxx' >> ~/.zshrc # 仅限本地，绝对不要提交！
# ❌ 禁止：写死在代码中
# const API_KEY = "sk-xxx"
> Key 泄露应急：立即登录 DeepSeek 控制台 → API Keys → 点击泄露 Key 的「Revoke」→ 创建新 Key → 更新本地 .env 文件。
三、安装 Claude Code
3.1 前置依赖
# Node.js >= 18（推荐 LTS 22.x）
node --version
# 版本不够？用 nvm：
nvm install 22 && nvm use 22
3.2 国内用户：npm 镜像加速
npm config set registry https://registry.npmmirror.com
npm config get registry # 验证：应输出 npmmirror.com
3.3 macOS
brew install claude-code # Homebrew（推荐）
npm install -g @anthropic-ai/claude-code # 或 npm
claude --version
3.4 Windows
# 1. 安装 Node.js LTS：https://nodejs.org（国内：https://npmmirror.com/mirrors/node/）
# 2. 设置 npm 镜像
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
claude --version
> 💡 提示：Windows 资源管理器需勾选「查看 → 显示 → 隐藏项目」才能看到 .claude 配置文件夹。
$npmPath = npm config get prefix
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$npmPath", "User")
# 重开 PowerShell
3.5 Linux
# Debian/Ubuntu
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# CentOS/RHEL — 国内用镜像直链（NodeSource 源易超时）
wget https://npmmirror.com/mirrors/node/v22.12.0/node-v22.12.0-linux-x64.tar.xz
tar -xf node-v22.12.0-linux-x64.tar.xz
sudo mv node-v22.12.0-linux-x64 /usr/local/node
echo 'export PATH=/usr/local/node/bin:$PATH' >> ~/.bashrc && source ~/.bashrc
# 安装
npm install -g @anthropic-ai/claude-code
claude --version
echo "export PATH=\"$(npm config get prefix)/bin:\$PATH\"" >> ~/.$(basename $SHELL)rc
source ~/.$(basename $SHELL)rc
3.6 WSL2
npm config set registry https://registry.npmmirror.com
sudo apt update && sudo apt install -y nodejs npm
npm install -g @anthropic-ai/claude-code
> ⚠️ 项目文件放在 Linux 文件系统（~/project），不要放 /mnt/c/，否则 Windows 文件权限异常导致读写失败。
3.7 Docker 容器
FROM node:22-slim
RUN npm config set registry https://registry.npmmirror.com && \
npm install -g @anthropic-ai/claude-code
ENV ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ENV ANTHROPIC_DEFAULT_MODEL=deepseek-v4-pro # ⚠️ 必须设置，否则默认请求 Claude 原生模型
WORKDIR /workspace
CMD ["claude"]
docker build -t claude-ds .
# 本地开发
docker run -it --rm \
-e ANTHROPIC_API_KEY=$DEEPSEEK_API_KEY \
-v $(pwd):/workspace \
claude-ds
# 生产环境：限定挂载路径
docker run -it --rm \
-e ANTHROPIC_API_KEY=$DEEPSEEK_API_KEY \
-v $(pwd)/src:/workspace/src:ro \
-v $(pwd)/.claude:/workspace/.claude \
claude-ds
> ⚠️ 生产环境不要挂载完整宿主机目录（-v $(pwd):/workspace）。使用只读子目录挂载，防止容器内恶意命令篡改宿主机文件。
四、连通性预检（配置前必须先跑通 ⭐）
# === 步骤 1：测试 DeepSeek 标准端点 ===
curl -s -w "\nHTTP %{http_code}\n" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}' \
https://api.deepseek.com/chat/completions
# 预期：HTTP 200 + JSON 响应
# === 步骤 2：测试 Anthropic 兼容端点 ===
curl -s -w "\nHTTP %{http_code}\n" \
-H "x-api-key: $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-v4-flash","max_tokens":100,"messages":[{"role":"user","content":"say hi"}]}' \
https://api.deepseek.com/anthropic/v1/messages
# 预期：HTTP 200
> 步骤 1 成功但步骤 2 失败 → Key 无 /anthropic 端点权限。
> 两步都成功 → 配置无误，可以启动 Claude Code。
五、全局环境配置
⚠️ 关键兼容性限制（必读）
| 限制 | 说明 | 影响 |
|---|
| 不支持图片/文件输入 | V4 系列无多模态能力 | 截图、PDF、架构图全部失效 |
| system 角色可能 400 | 超长 system 提示被截断或拒绝 | 部分 Claude Code 内置功能报错 |
| 不支持 1M 长上下文 | 开启后携带不兼容参数 | 直接 400 |
| 推理模式限制 | temperature/top_p 自动忽略 | 调参无效果 |
5.1 macOS
# 编辑 ~/.zshrc，添加：
export DEEPSEEK_API_KEY="sk-your-key"
alias claude-ds='ANTHROPIC_API_KEY="$DEEPSEEK_API_KEY" \
ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" \
claude'
alias claude-ds-fast='ANTHROPIC_API_KEY="$DEEPSEEK_API_KEY" \
ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" \
ANTHROPIC_DEFAULT_MODEL="deepseek-v4-flash" \
claude'
source ~/.zshrc
5.2 Windows PowerShell
# 编辑 $PROFILE
$env:DEEPSEEK_API_KEY="sk-your-key"
function claude-ds {
$env:ANTHROPIC_API_KEY=$env:DEEPSEEK_API_KEY
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
claude
}
5.3 Linux
# 编辑 ~/.bashrc（同 macOS Zsh 格式，用 source ~/.bashrc 生效）
5.4 新手极简启动（3 行命令，跳过所有别名）
npm install -g @anthropic-ai/claude-code # 安装
ANTHROPIC_API_KEY="sk-your-key" \
ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" \
claude # 启动
/model sonnet # 开始对话
六、项目独立配置 ⭐
6.1 基础配置
// .claude/settings.json
{
"apiKeyHelper": "echo $DEEPSEEK_API_KEY",
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"
}
}
6.2 实战案例：全局官方 Claude + 单项目强制 DeepSeek
# ~/.zshrc — 全局用官方 Claude
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"
# 项目 A（~/work/project-a）— 强制用 DeepSeek 省钱
mkdir -p ~/work/project-a/.claude
cat > ~/work/project-a/.claude/settings.json << 'EOF'
{
"apiKeyHelper": "echo $DEEPSEEK_API_KEY",
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"
},
"model": "deepseek-v4-pro"
}
EOF
# 项目 B（~/work/project-b）— 用官方 Claude（无需额外配置，继承全局）
> 效果：cd ~/work/project-a && claude → 自动用 DeepSeek；cd ~/work/project-b && claude → 用官方 Claude。
七、模型参数详解
7.1 DeepSeek V4 系列
| 模型 | 定位 | 适用场景 |
|---|
deepseek-v4-pro | 深度推理 | 复杂架构、难题排查 |
deepseek-v4-flash | 快速经济 | 日常编码、简单问答 |
> ⚠️ deepseek-chat 和 deepseek-reasoner 将于 2026/07/24 下线，下线后 API 直接返回 model not found。
sed -i '' 's/deepseek-chat/deepseek-v4-flash/g' ~/.zshrc
sed -i '' 's/deepseek-reasoner/deepseek-v4-pro/g' ~/.zshrc
source ~/.zshrc
7.2 企业网关适配
部分企业代理强制校验模型前缀（如只放行 claude-*），直接填 deepseek-v4-pro 会被拦截：
# 方案：在网关层添加白名单
# 联系网关管理员添加：
# - deepseek-v4-pro
# - deepseek-v4-flash
# 或使用别名绕过（如果网关支持）
ANTHROPIC_DEFAULT_MODEL="deepseek-v4-pro" # 不变
八、工作原理 & 架构图
┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Claude │────▶│ Anthropic │────▶│ DeepSeek │
│ Code CLI │ │ Compatible │ │ API Server │
│ │◀────│ Format │◀────│ │
└─────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
│ 正常：Anthropic 格式 正常：返回响应
│ 异常：system角色/1M 异常：400/401/429
│ 上下文 → 400 → 检查第四章节
九、快速上手
cd ~/my-project && claude-ds
/model # 查看当前模型
> 帮我写一个 Python 异步 WebSocket 服务端
> 分析 src/utils/auth.ts 的安全问题
| 命令 | 说明 |
|---|
/help | 所有可用命令 |
/clear | 清空上下文 |
/cost | Token 消耗（区分输入/输出/思考 token 计价） |
/doctor | 诊断：Key 有效性、端点可达性、模型可用性 |
exit | 退出 |
> /doctor 输出重点看：api_key_valid（Key 有效）、base_url_reachable（端点连通）、model_available（模型名正确）。任一项 false 则连接失败。
>
> /cost 输出：input_tokens（输入）、output_tokens（输出）、reasoning_tokens（思考 token，单独计费）。
十、进阶技巧
10.1 多模型一键切换
function claude-switch() {
case "${1:-pro}" in
pro) export ANTHROPIC_DEFAULT_MODEL="deepseek-v4-pro"; echo "→ Pro" ;;
flash) export ANTHROPIC_DEFAULT_MODEL="deepseek-v4-flash"; echo "→ Flash" ;;
*) echo "用法: claude-switch pro|flash" ;;
esac
}
10.2 长对话优化
| 问题 | 对策 |
|---|
| 上下文太长，响应变慢 | /clear + 重新描述任务 |
| Token 消耗过高 | 切换到 Flash；设置 taskBudget |
| 模型「失忆」 | 手动总结：「以上结论是 A、B，现在处理 C」 |
| 上下文太大无法一次性处理 | 分步：「先读文件 A」「基于 A 处理文件 B」 |
| 需保留上下文但换话题 | 将关键上下文写入文件，/clear 后引用 |
10.3 安全权限配置
// .claude/settings.json — 本地开发用
{
"permissions": {
"allow": [
"Bash(curl:*)", "Bash(git:*)", "Bash(npm:*)", "Bash(node:*)",
"Bash(ls:*)", "Bash(cat:*)", "Bash(mkdir:*)",
"Read", "Write", "Edit", "Grep", "Glob"
],
"deny": [
"Bash(rm -rf /:*)",
"Bash(shutdown:*)"
]
}
}
> ⚠️ 生产环境收紧权限：移除 Bash(rm:*)、Write 仅限特定目录，禁止在 CI/服务器上使用全量权限配置。
十一、与 Cursor 配合使用 ⚠️
> Claude Code 和 Cursor 使用不同的 API 端点，绝对不能混用！
| 工具 | Base URL | 格式 |
|---|
| Claude Code | https://api.deepseek.com/anthropic | Anthropic 兼容 |
| Cursor | https://api.deepseek.com | OpenAI 兼容 |
Cursor 设置 → Models → 添加：
Model name: deepseek-v4-pro
Base URL: https://api.deepseek.com（无 /anthropic 后缀！）
API Key: sk-your-key
十二、网络与重试方案
国内高峰期 API 波动处理
# 带超时和重试的启动别名
alias claude-ds-retry='ANTHROPIC_API_KEY="$DEEPSEEK_API_KEY" \
ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" \
ANTHROPIC_TRANSPORT_TIMEOUT=120000 \
ANTHROPIC_MAX_RETRIES=3 \
claude'
# 如果仍然超时，配置 HTTP 代理
export HTTPS_PROXY=http://your-proxy:port
十三、CI/CD 自动代码评审 ⭐
# .github/workflows/ai-review.yml
name: AI Code Review
on: [pull_request]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '22' }
- run: npm install -g @anthropic-ai/claude-code
- name: Run AI Review
run: |
claude -p "审查当前 PR 的改动，输出 Markdown 格式的审查报告。\
重点检查：安全漏洞、性能问题、代码规范。\
改动文件：$(git diff --name-only origin/main)" \
--output-format markdown > review.md
env:
ANTHROPIC_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic
ANTHROPIC_DEFAULT_MODEL: deepseek-v4-pro
- name: Post Review
run: gh pr comment ${{ github.event.pull_request.number }} --body-file review.md
env:
GH_TOKEN: ${{ github.token }}
十四、完整配置文件
macOS / Linux（~/.zshrc 精简版）
export DEEPSEEK_API_KEY="sk-your-key"
alias claude-ds='ANTHROPIC_API_KEY="$DEEPSEEK_API_KEY" \
ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" claude'
alias claude-ds-fast='ANTHROPIC_API_KEY="$DEEPSEEK_API_KEY" \
ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" \
ANTHROPIC_DEFAULT_MODEL="deepseek-v4-flash" claude'
项目配置（.claude/settings.json）
{
"apiKeyHelper": "echo $DEEPSEEK_API_KEY",
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"
},
"model": "deepseek-v4-pro",
"taskBudget": 50000,
"maxTurns": 25
}
十五、费用对比
| 模型 | 输入/1M tok | 输出/1M tok | 月费（日常） |
|---|
| deepseek-v4-flash | ¥1 | ¥4 | ≈¥9 |
| deepseek-v4-pro | ¥2 | ¥8 | ≈¥18 |
| Claude Sonnet 4.6 | $3 | $15 | ≈¥210 |
| Claude Opus 4.8 | $15 | $75 | ≈¥1050 |
> 500万输入+100万输出/月估算。汇率：1 USD≈7 CNY。思考 token 单独计费。
十六、常见问题排查（按错误码分类）
400 Bad Request
Q1：400 invalid_request_error
原因 1：system 角色消息与 DeepSeek /anthropic 端点冲突。
修复：检查是否开启了需要 system 消息的 Claude Code 功能（如某些 MCP 配置）。精简 system 提示内容。
原因 2：开启了 1M 长上下文。
修复：关闭扩展上下文，恢复默认 200K。
curl -s -w "\nHTTP %{http_code}\n" \
-H "x-api-key: $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek-v4-flash","max_tokens":100,"messages":[
{"role":"user","content":"test"}]}' \
https://api.deepseek.com/anthropic/v1/messages
401 Unauthorized
echo $DEEPSEEK_API_KEY # 确认 Key 存在且未过期
# 或检查 Key 是否在控制台被 Revoke
404 Not Found
> deepseek-chat/deepseek-reasoner 已于 2026/07/24 下线。确保使用 deepseek-v4-pro 或 deepseek-v4-flash（全部小写）。
429 Too Many Requests
Q4：429 或 insufficient_balance
- 控制台 Billing 检查余额
- 减少并发 Claude Code 实例
- 推理 token 单独计费，日常用 Flash 更省
网络问题
# 诊断
curl -s --connect-timeout 10 --max-time 30 \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
https://api.deepseek.com/chat/completions \
-d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}]}'
# 修复：增加超时 + 重试
alias claude-ds-retry='ANTHROPIC_TRANSPORT_TIMEOUT=120000 \
ANTHROPIC_MAX_RETRIES=3 claude-ds'
export HTTPS_PROXY=http://your-proxy:port # 配置代理
配置问题
Q7：claude: command not found
# macOS/Linux 一键修复
echo "export PATH=\"$(npm config get prefix)/bin:\$PATH\"" >> ~/.$(basename $SHELL)rc && source ~/.$(basename $SHELL)rc
# Windows
$npmPath = npm config get prefix
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$npmPath", "User")
- macOS/Linux：
source ~/.zshrc 或重开终端
- Windows：
. $PROFILE 或重开终端
- 检查项目
settings.json 是否覆盖了环境变量
Q9：Windows 看不到 .claude 文件夹
模型行为
DeepSeek /anthropic 端点不支持图片。用文字描述替代，或临时切回官方 Claude。
deepseek-v4-pro 推理模式下偶发。改用 deepseek-v4-flash。
项目移到 ~/project（Linux 文件系统），不要用 /mnt/c/。
费用问题
- 推理模式（pro）的思考 token 单独计费
- 用量明细：控制台 → Billing → Usage
- 建议日常用 Flash 模式节省
总结
npm install -g @anthropic-ai/claude-code
ANTHROPIC_API_KEY="sk-your-key" \
ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" claude
/model sonnet
- 注册 DeepSeek，获取 API Key（第二章）
- 安装 Claude Code（第三章）
- 运行连通性预检（第四章）
- 配置环境变量，启动
claude-ds（第五章）
- 遇到问题按错误码查找（第十六章）