Claude Code 接入 DeepSeek V4 API 完整教程

Claude Code + DeepSeek V4 API 的核心思路很简单：保留 Claude Code 的终端开发体验，把模型请求通过 DeepSeek 提供的 Anthropic 兼容接口发出去。对已经习惯 Claude Code 的开发者来说，这是一条很有性价比的 AI 编程方案，尤其适合日常改代码、读仓库、跑测试、整理实现方案和处理小型重构。

这篇教程以 DeepSeek 官方提供的 Claude Code 接入方式为主，完整走一遍从准备环境、配置环境变量、启动验证到排查冲突的流程。ccSwitch 可以作为管理多个 provider 的可选工具，但不是本文重点。

开始前需要准备什么

你需要先准备好这些条件：

如果你只是想先验证链路，不建议直接在生产仓库里测试。找一个小项目，或者新建一个临时目录，确认 Claude Code 能正常启动、能显示模型信息、能完成简单问答后，再放到真实项目里使用。

这套方案怎么工作

Claude Code 支持通过环境变量控制认证、模型选择和请求地址。DeepSeek 官方提供的接入方式，就是把 Claude Code 的请求地址改到 DeepSeek 的 Anthropic 兼容接口，并把模型槽位映射到 DeepSeek V4 系列：

DeepSeek 官方价格页在 2026-05-25 可见的信息显示，deepseek-v4-flash 和 deepseek-v4-pro 都支持 1M 上下文，输出长度上限为 384K，并支持 JSON Output 和 Tool Calls。价格会随官方策略调整，长期使用前要重新查看价格页，不要把某篇教程里的旧价格当成永久价格。

第一步：安装或检查 Claude Code

如果你已经能在终端里运行 claude --version，可以跳到下一步。

还没有安装时，可以按 DeepSeek 官方接入文档中的方式安装：

npm install -g @anthropic-ai/claude-code

安装完成后检查版本：

claude --version

如果提示 claude 命令不存在，通常是全局 npm 安装目录没有加入 PATH，或者安装后没有重新打开终端。Windows 用户还要注意：PowerShell 和 CMD 的命令语法不同，不能混用 irm、curl、&& 等写法。

第二步：获取 DeepSeek API Key

进入 DeepSeek Platform 后，创建一个新的 API Key。Key 创建后通常只完整展示一次，建议立即保存到密码管理器或本机安全凭据工具中。

不要把 API Key 写进项目仓库，也不要把包含 Key 的终端输出、截图、日志发到公开平台。后面验证配置时，也尽量只检查模型名和 Base URL，不要把认证变量直接打印出来。

第三步：用环境变量接入 DeepSeek

这是本文推荐的主流程。它不需要修改 Claude Code 的项目配置，也不需要安装额外切换工具，适合先把链路跑通。

macOS、Linux 或 WSL 用户，在启动 Claude Code 的同一个终端里执行：

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

Windows PowerShell 用户执行：

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<你的 DeepSeek API Key>"
$env:ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_EFFORT_LEVEL="max"

这些变量只对当前终端会话生效。关闭终端后需要重新设置。第一次测试时这样反而更安全，因为你可以随时关闭窗口恢复原来的 Claude Code 使用方式。

第四步：进入项目并启动 Claude Code

进入你准备测试的项目目录：

cd /path/to/my-project
claude

第一次进入某个目录时，Claude Code 可能会询问是否信任当前工作目录。只在你确认这是自己的测试项目或可控项目时选择信任。

进入 Claude Code 后，可以先做三个检查：

/status
/model
/context

/status 用来查看当前会话加载了哪些设置来源；/model 用来确认当前模型；/context 用来观察上下文状态。然后可以输入一个低风险问题，例如：

请用三句话说明当前项目的主要结构，不要修改任何文件。

如果 Claude Code 能正常响应，并且模型信息显示为 DeepSeek V4 系列，说明基础接入已经跑通。

旧配置用户要特别检查 settings.json

如果你之前用过 Claude Code，或者曾经按照其他教程改过 ~/.claude/settings.json，这里要多做一步检查。Claude Code 支持把环境变量写在 settings.json 的 env 字段里；用户级 ~/.claude/settings.json 会影响每个项目，项目级 .claude/settings.json 或 .claude/settings.local.json 也可能影响当前仓库。

重点检查这些同名配置：

• ANTHROPIC_BASE_URL
• ANTHROPIC_AUTH_TOKEN
• ANTHROPIC_API_KEY
• ANTHROPIC_MODEL
• ANTHROPIC_DEFAULT_OPUS_MODEL
• ANTHROPIC_DEFAULT_SONNET_MODEL
• ANTHROPIC_DEFAULT_HAIKU_MODEL
• CLAUDE_CODE_SUBAGENT_MODEL

建议先备份，再清理或统一这些配置。不要同时在 shell 环境变量、用户级 settings、项目级 settings 里维护多套模型和 Key，否则排查时很容易误以为 DeepSeek 配置没有生效。

一个比较稳妥的做法是：

1. 先用当前终端环境变量跑通 DeepSeek。
2. 跑通后再决定是否写入 ~/.claude/settings.json。
3. 项目仓库里的 .claude/settings.json 不要写入个人 API Key。
4. 私人配置优先放在用户级 settings 或本机环境变量里。
5. 如果要提交项目级配置，只提交权限、工作流和团队约定，不提交密钥。

如果你需要长期默认使用 DeepSeek，可以把非敏感配置写入 settings，把 API Key 交给系统环境变量或安全凭据工具管理。这样既减少重复输入，也能降低误提交风险。

可选：用 settings.json 固化配置

如果你已经确认当前方案可用，可以把配置写进用户级 ~/.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",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_EFFORT_LEVEL": "max"
  }
}

这里的 Key 不要写进项目级 .claude/settings.json。如果你希望团队共享 DeepSeek 接入方式，也应该只共享模型名、Base URL 和注意事项，让每个人自己配置 Key。

可选：什么时候考虑 ccSwitch

ccSwitch 更适合已经同时使用多个 AI 编程 CLI 的用户。比如你希望在 Claude Code、Codex、OpenCode、Gemini CLI 之间统一管理 provider，或者经常在 DeepSeek、Anthropic、其他兼容接口之间切换，就可以考虑用 ccSwitch 管理配置。

但如果你的目标只是让 Claude Code 调用 DeepSeek V4 API，DeepSeek 官方环境变量方案已经足够。先跑通官方方案，再引入 ccSwitch，会比一开始就叠加多个工具更容易排查问题。

使用 ccSwitch 时，核心配置仍然是：

配置完成后先用 ccSwitch 的测试功能确认 API 可用，再重启 Claude Code。很多模型切换工具需要重新打开 CLI 才能让新 provider 生效。

常见问题与处理方式

成本使用建议

Claude Code + DeepSeek V4 API 的性价比，来自按量计费和模型槽位的灵活映射。但这不代表可以完全不看成本。AI 编程任务常常会读取大量上下文，大仓库、长日志、重复尝试和多轮修复都会增加 token 消耗。

建议采用这样的策略：

1. 日常编码、复杂修改和架构判断优先用 deepseek-v4-pro[1m]。
2. 轻量问答、简单解释、子代理任务可以交给 deepseek-v4-flash。
3. 第一次在大仓库里使用时，先让 Claude Code 只解释结构，不要直接改文件。
4. 对涉及生产配置、数据库迁移、支付、权限的任务，先要求它输出计划，再人工确认。
5. 定期到 DeepSeek Platform 查看用量和余额，不要只依赖本地工具的感知。

最终检查清单

开始正式使用前，建议确认：

• claude --version 可以正常输出版本号。
• 已经获取并妥善保存 DeepSeek API Key。
• 当前会话设置了 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。
• /model 能看到 DeepSeek V4 相关模型。
• ~/.claude/settings.json 和项目 .claude 配置里没有冲突的旧模型或旧 Key。
• 测试项目里完成过一次只读问答或低风险修改。
• 没有把 API Key 写入可提交的项目文件。

什么时候适合采用这套方案

如果你已经习惯 Claude Code 的终端工作流，又希望降低 AI 编程的长期使用成本，Claude Code + DeepSeek V4 API 是值得尝试的组合。它的优势不是“一键全自动开发”，而是让你用更低门槛保留 Claude Code 的项目理解、命令执行、多文件修改和交互式开发体验。

更稳妥的落地方式是：先用官方环境变量方案跑通，再清理旧 settings 冲突，最后根据自己的使用频率决定是否固化到 ~/.claude/settings.json 或交给 ccSwitch 管理。这样既能尽快开始使用，也能把密钥、配置和成本风险控制在可排查的范围内。