本文将一步步讲清楚：如何让 Claude Code 终端客户端通过 DeepSeek 提供的 Anthropic 兼容 API 网关来工作。

你将学到：

  • 如何按 Anthropic 推荐方式原生安装 Claude Code
  • 如何为 DeepSeek 网关正确配置环境变量
  • 如何验证路由是否生效
  • 哪些功能可用、哪些不支持
  • 模型命名与路由行为、超时与限流、价格差异以及常见错误的解决思路

所有内容都基于 DeepSeek 当前 Anthropic API 文档和 Anthropic 官方 Claude Code 文档，并在原始资料基础上做了整理与归纳。

一、“在 Claude Code 中使用 DeepSeek”到底是什么意思？

这套配置并不会把 DeepSeek 变成 Claude 的官方一方提供方。

它做的事情是：让 Claude Code 终端客户端，把原本发往 Anthropic 的 Messages API 请求，改为发送到 DeepSeek 的 Anthropic 兼容端点：

https://api.deepseek.com/anthropic

根据 DeepSeek 当前文档，这个端点是为了兼容 Anthropic API 生态而提供的，目前列出的模型包括：

  • deepseek-chat
  • deepseek-reasoner

它们对应 DeepSeek-V3.2 API 模型，支持 128K 上下文，与网页/App 版本有区别。

Anthropic 在自己的 API 概览中，把这种“改路由到第三方端点”的方式视为第三方 / 代理式访问模式，而不是直接使用 Claude 官方 API。更广泛的 DeepSeek API 能力可以参考我们的《DeepSeek API 指南》。

这个区别很重要，因为 Claude Code 的行为取决于它看到的 API 能力面：

  • Anthropic 网关文档说明：Claude Code 需要一个 Anthropic Messages 兼容的接口面，
  • 如果某些头信息或请求体字段没有被正确转发或保留，功能可能会打折甚至失效。

DeepSeek 提供了兼容端点，但也明确标注了若干被忽略的字段和不支持的内容类型。因此更合理的预期是：

“非常适合以文本为主的 CLI 编码工作流”，而不是“与直连 Anthropic 功能完全等价”。

二、开始前的准备条件

在动手之前，你需要：

  • 一份最新版本的 Claude Code 安装
  • 一个可用的 DeepSeek API Key
  • 一个正常可用的终端环境（macOS / Linux / WSL / Windows PowerShell 等）

Anthropic 网关文档要求：

  • Claude Code 需为最新版本
  • 官方推荐优先使用“原生安装”方式
  • Windows 需要先安装 Git for Windows
  • DeepSeek 的错误码文档中也会提示：若没有 API Key，需要先在控制台创建

Anthropic 还特别强调了一个“使用面”的区别：

  • 终端 CLI 和 VS Code 支持第三方提供方
  • ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY 只对 终端 CLI 会话 生效
  • Claude Desktop 与远程会话使用 OAuth，不读取这些 API Key 环境变量

因此本文只聚焦 CLI 终端场景。

三、推荐安装路径：原生安装 Claude Code

截至 2026 年 3 月 31 日，DeepSeek 的 Anthropic 指南中仍示例：

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

但 Anthropic 最新的 Quickstart 与高级配置文档都推荐：

  • 优先使用原生安装脚本
  • 并明确说明 npm 安装已被标记为“弃用”
  • 原生安装支持后台自动更新，而 Homebrew / WinGet 不会自动更新

因此，原生安装是默认首选，npm 仅作为兼容性兜底方案。

3.1 原生安装示例

macOS / Linux / WSL：

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

以上命令均来自 Anthropic 当前 Quickstart 与安装文档。Windows 额外要求安装 Git for Windows。

Claude Code version check showing v1.0.16 installed via native method

3.2 npm 兜底安装示例

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

仅在确有兼容性需求时使用 npm：

  • Anthropic 文档已将 npm 安装标记为“deprecated”
  • 推荐将旧的 npm 安装迁移到原生安装
  • 使用 npm 时需 Node.js 18+，且不要使用 sudo npm install -g

四、DeepSeek 相关环境变量配置

DeepSeek 官方 Claude Code 示例使用的是：

  • ANTHROPIC_AUTH_TOKEN（而不是 ANTHROPIC_API_KEY）

这与 Anthropic 的认证文档一致：

  • ANTHROPIC_AUTH_TOKEN：用于网关 / 代理场景的 Bearer Token
  • ANTHROPIC_API_KEY：用于直连 Claude 官方 API 的密钥

其他关键变量：

  • ANTHROPIC_BASE_URL：将客户端路由到 DeepSeek 端点
  • ANTHROPIC_MODEL：启动时默认模型
  • ANTHROPIC_DEFAULT_HAIKU_MODEL：控制 Claude Code 内部“Haiku 类”轻量模型槽位（用于后台任务）
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1：关闭更新检查、反馈、错误上报和遥测等非必要流量

这些变量的含义综合自 DeepSeek 当前指南与 Anthropic 的环境变量、模型配置和认证文档。

五、macOS / Linux 配置示例

在 shell 中执行：

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=YOUR_DEEPSEEK_API_KEY
export API_TIMEOUT_MS=600000
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-chat
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

claude --version
claude doctor
claude

这是当前文档下，对 macOS / Linux / WSL 最干净、最直接的 CLI 配置路径。

六、Windows（PowerShell）配置示例

irm https://claude.ai/install.ps1 | iex

$env:ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_DEEPSEEK_API_KEY"
$env:API_TIMEOUT_MS = "600000"
$env:ANTHROPIC_MODEL = "deepseek-chat"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "deepseek-chat"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"

claude --version
claude doctor
claude

Anthropic 安装文档推荐在 Windows 上使用 PowerShell，并再次强调需要 Git for Windows。

七、首次启动与验证步骤

配置好环境变量后，先运行：

claude --version
claude doctor

Claude Code doctor output showing all health checks passed with DeepSeek endpoint configured

如果客户端行为异常，Anthropic 故障排查文档建议：

  • macOS / Linux 使用 which -a claude
  • Windows 使用 where.exe claude

检查是否存在多个 Claude 安装路径，清理多余版本，确保只保留一个首选安装。

进入会话后，可以使用 /status 命令，确认：

  • 当前使用的是哪种认证方式（Bearer Token / API Key / OAuth）
  • Claude Code 认为自己正在使用哪个模型

Claude Code status command showing bearer-token auth and deepseek-chat model active via DeepSeek API endpoint

一个最小“健全性测试”可以这样做：

  1. 在一个小型代码仓库中启动 Claude Code
  2. 让它先解释目录结构
  3. 再让它做一个很小的修改，并检查生成的 diff

由于 Claude Code 的核心价值在于本地文件访问和命令执行，这种以文本为主的仓库任务，比图片、浏览器或重度 MCP 工作流更适合作为首测场景。

Claude Code sanity test explaining a Node.js project directory structure using DeepSeek model

八、哪些好用，哪些不适合走这条路

基于 DeepSeek 的 Anthropic 兼容性说明和 Anthropic 当前认证、Chrome 等文档，可以简单概括为：

  • 适合：

    • 终端内的文本向导式编码
    • 代码解释、重构、小规模重写
    • 以 CLI 为中心的工程工作流

  • 不适合：

    • 严重依赖 Anthropic Beta 特性
    • 重度 MCP（Model Context Protocol）工具链
    • 强依赖官方 Chrome 集成或桌面 OAuth 场景

九、Anthropic 兼容性限制：通俗解释

真正的限制不在“语法是否兼容”，而在于“功能是否对等”。

DeepSeek 文档中提到：

  • 忽略 anthropic-beta、anthropic-version
  • 忽略字段：container、mcp_servers、metadata、service_tier、top_k 以及部分 cache_control 字段
  • 支持 thinking，但忽略其中的 budget_tokens
  • 在 tool_choice 中忽略 disable_parallel_tool_use

Anthropic 网关文档也提醒：

  • 若某些头或请求体字段未被正确转发或保留，可能会削弱功能甚至导致特性不可用

用更直白的话说：

把它当作“文本为主的 CLI 编码路线”是安全的； 把它当作“覆盖所有 Anthropic 特性”的替代品，就不现实了。

关于 MCP，还有一个细节：

  • 当 ANTHROPIC_BASE_URL 指向非官方主机时，Anthropic 文档说明 MCP 工具搜索会有不同处理方式，可能需要额外配置
  • 但 DeepSeek 的兼容性表中又标注 mcp_servers、mcp_tool_use、mcp_tool_result 为忽略或不支持

因此，如果你有非常复杂、重度依赖 MCP 的工作流，不建议走这条路作为主力方案。

十、模型命名与路由行为

这里有两个官方参考点：

  1. Claude Code 支持通过 ANTHROPIC_MODEL 设置启动模型
  2. Anthropic 还提供 ANTHROPIC_CUSTOM_MODEL_OPTION，用于在网关场景下往 /model 选择器中添加自定义模型 ID
    • 文档说明：这个自定义选项会跳过模型 ID 校验，因此可以填入任何端点接受的模型字符串

另一方面，DeepSeek 文档指出：

  • 如果向 Anthropic 兼容端点发送了不支持的模型名，后端会自动映射到 deepseek-chat

这意味着：

  • 不要依赖 Anthropic 的别名（如 sonnet、opus）
  • 应该显式设置真实的 DeepSeek 模型 ID，例如 deepseek-chat

如果你希望在 /model 选择器中直接看到 DeepSeek 模型，而不是依赖“暗中映射”，可以增加自定义模型选项：

export ANTHROPIC_CUSTOM_MODEL_OPTION="deepseek-chat"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="DeepSeek Chat"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="DeepSeek via Anthropic-compatible endpoint"

Claude Code model picker showing deepseek-chat as active model with custom DeepSeek Chat option

Anthropic 文档明确指出：

  • 这个自定义模型选项是专门为网关部署设计的
  • Claude Code 会跳过对你提供的模型 ID 的校验

如果你想试试 deepseek-reasoner：

  • DeepSeek 文档将其列为当前可用 API 模型，并支持 thinking
  • 但官方 Claude Code 示例仍固定在 deepseek-chat
  • 兼容性说明中也提到 thinking 中的 budget_tokens 会被忽略

因此：

  • deepseek-reasoner 更适合作为实验路径
  • 稳定生产 CLI 工作流仍建议以 deepseek-chat 为默认

十一、超时、限流与性能注意事项

DeepSeek 在 Claude Code 示例中显式设置：

API_TIMEOUT_MS=600000

即 600 秒（10 分钟）超时，目的是避免长输出导致客户端超时，尤其是在：

  • 长推理链
  • 大型仓库大范围修改 等场景下。

DeepSeek 还说明：

  • 账号级限流是动态的，取决于实时流量和短期历史使用情况
  • 当前不支持为单个账号单独提升限流
  • 遇到 429 或 503 时，优先把它当作“节奏 / 重试问题”，而不是“配置一定错了”

实践建议：

  • 先用 deepseek-chat 跑通基础工作流
  • 控制输出长度与任务规模
  • 在基础路由稳定后，再逐步尝试更重的推理任务
  • 若单次调用耗时过长，优先缩小任务、减少输出或稍后重试，而不是立刻怀疑字段格式

十二、费用对比：DeepSeek vs 原生 Claude API

从标价来看，这条路在成本上具有吸引力。

DeepSeek 当前 API 文档中：

  • deepseek-chat / deepseek-reasoner
    • 输入（缓存命中）：$0.028 / MTok
    • 输入（缓存未命中）：$0.28 / MTok
    • 输出：$0.42 / MTok

Anthropic 当前官方定价：

  • Claude Haiku 4.5：
    • 输入：$1 / MTok
    • 缓存命中：$0.10 / MTok
    • 输出：$5 / MTok
  • Claude Sonnet 4.6：
    • 输入：$3 / MTok
    • 缓存命中：$0.30 / MTok
    • 输出：$15 / MTok
  • Claude Opus 4.6：
    • 输入：$5 / MTok
    • 缓存命中：$0.50 / MTok
    • 输出：$25 / MTok

需要强调：

  • 这只是路由成本对比，并不代表能力完全等价
  • 具体能力差异可参考《DeepSeek vs Claude 对比》与 DeepSeek API 成本计算器

DeepSeek 也提醒：价格可能调整，建议定期查看最新价格页面。

整体权衡可以这样理解：

  • 如果你更在意：更低的 Token 成本 + 熟悉的 CLI 工作流 → DeepSeek 路由很有吸引力
  • 如果你更在意：直连 Anthropic 计费 + 官方支持 + 功能覆盖最完整 → 仍应优先使用原生 Claude API

Anthropic 自己的 API 概览也说明：

  • 直连 Claude API 会优先获得最新模型与新特性

十三、常见错误与排查思路

这套配置出问题时，通常集中在几类：

  1. 认证错误

    • 使用了错误的变量（把 ANTHROPIC_API_KEY 当成网关 Token 用）
    • Token 过期或写错

  2. 内容类型不支持

    • 发送了 DeepSeek 端点当前不支持的内容类型或字段

  3. 模型选择不明确

    • 使用了 Anthropic 模型别名（如 sonnet、opus），被自动映射到 deepseek-chat，但你误以为在用别的模型

  4. 多重 Claude 安装冲突

    • 系统 PATH 中存在多个 claude 可执行文件

排查时可以按以下顺序：

  • 用 claude --version 和 claude doctor 检查基础健康状态
  • 用 which -a claude / where.exe claude 检查是否有多重安装
  • 清理多余安装，确保只保留一个
  • 确认环境变量只保留一套清晰配置：
    • 一个 ANTHROPIC_BASE_URL
    • 一个 ANTHROPIC_AUTH_TOKEN
    • 一个明确的 ANTHROPIC_MODEL

更全面的排查可以参考《DeepSeek 无法使用排错指南》。

十四、API Key 安全与认证优先级

关于密钥安全，建议：

  • 优先使用环境变量或 apiKeyHelper 脚本
  • 避免把 Token 写进共享仓库或配置文件

Anthropic 文档说明：

  • apiKeyHelper 可用于动态获取凭证
  • 在通过网关或代理路由时，应使用 ANTHROPIC_AUTH_TOKEN 进行 Bearer Token 认证
  • ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY 仅对终端 CLI 有效

还有一个容易踩坑的点：

Anthropic 的认证优先级为：

  1. ANTHROPIC_AUTH_TOKEN
  2. ANTHROPIC_API_KEY
  3. 正常订阅的 OAuth（如 Desktop）

如果你在 shell 中遗留了旧的环境变量：

  • 可能会在不知情的情况下，实际走的是另一个提供方或旧路由

因此在测试前务必：

  • 清理旧的环境变量
  • 确保“一个安装、一个认证方式、一个明确模型”

十五、什么时候适合用这套 DeepSeek 路由？

推荐使用本方案的场景：

  • 你想要：
    • Claude Code 的“代理式终端工作流”（本地文件 + 命令执行）
    • 更低的 API 成本
    • 以文本为主的编码循环
  • 同时你可以接受：
    • 放弃部分 Anthropic 原生特性
    • 不追求与官方 API 完全一致的功能覆盖

它非常适合：

  • 原型开发
  • 内部工具
  • 重构与代码走查
  • 对成本敏感的工程工作

十六、什么时候仍应优先使用原生 Claude？

以下情况更适合直接使用 Claude 官方 API / 产品：

  • 需要：
    • 直接与 Anthropic 结算与支持
    • 第一时间使用最新模型与特性
    • Chrome 集成
    • 依赖 OAuth 的产品形态（如 Desktop、远程会话）

Anthropic API 概览与认证、Chrome 文档都明确：

  • 某些产品面与功能仍与官方计划或 OAuth 流程强绑定

十七、总结

如果你把“在 Claude Code 中使用 DeepSeek”理解为：

通过 Anthropic 兼容网关，把 Claude Code 终端工作流接到 DeepSeek 模型上， 以文本为主、成本友好，而不是追求 100% 功能对等，

那么这套方案是值得使用的。

实践建议归纳如下：

  1. 使用 原生方式安装 Claude Code
  2. 使用 ANTHROPIC_AUTH_TOKEN 而不是 ANTHROPIC_API_KEY 作为网关 Token
  3. 显式指定真实 DeepSeek 模型 ID（如 deepseek-chat），不要依赖 Anthropic 别名
  4. 用 claude doctor 与 /status 验证当前路由与模型
  5. 保持配置简单清晰：
    • 一个安装
    • 一种认证方式
    • 一个明确模型

配置越干净，这条路在日常 CLI 编码中的价值就越大。

如需了解 DeepSeek 的其他能力（聊天、应用、模型与价格等），可前往 DeepSeek AI 相关页面进一步探索。