梦开始的地方：Claude Code 在 Windows & DeepseekV4Pro上的国内环境安装与调试指南

Windows 10 · DeepSeek V4 Pro API · Node.js 22 LTS · Claude Code CLI v2.x · CC-Switch v3.14.1 · 2026-04-30

一、这篇教程解决什么问题

一句话定位：在 Windows 上从零搭建 Node.js 环境，配置国内镜像源加速 npm，安装 Claude Code 并借助 CC-Switch + 手动配置文件实现跳过 Anthropic 官方 OAuth 登录验证，使用 DeepSeek V4 Pro API 直接启动。

阅读前提：

• 使用 Windows 10 或 Windows 11 操作系统
• 拥有可用的 DeepSeek API Key（在 platform.deepseek.com 注册并创建）
• DeepSeek 账户余额 ≥ ¥1.00（V4-Pro 单次最低计费约 ¥0.98）
• 有基本的命令行操作经验（PowerShell 或 CMD）

读完能得到什么：一个在国内网络环境下可正常启动的 Claude Code Cli，底层由 DeepSeek V4 Pro 驱动，无需访问 claude.ai。

---

二、环境准备

2.1 依赖清单

组件	最低版本	说明
nvm-windows	1.1.12+	Node.js 版本管理器
Node.js	18.0+（推荐 22 LTS）	Claude Code 运行时
npm	10.x+	随 Node.js 自带
CC-Switch	v3.14.1+	多模型切换桌面工具

2.2 逐条验证

nvm version          # 应输出 1.1.12 或更高
node --version       # 应输出 v22.x.x 或 v20.x.x
npm --version        # 应输出 10.x.x 或更高

如果缺少某个组件：

• nvm-windows 安装则如下：前往 nvm-windows Releases，下载 nvm-setup.exe，双击安装，全部默认选项即可。

---

三、安装步骤

3.1 安装 nvm-windows

nvm-windows 是 Windows 上管理多版本 Node.js 的标准方案，相当于Python的conda，用于Node.js的版本隔离，开发环境隔离。由于本人存在Openclaw和claude code两个Agent，Openclaw的更新非常拉跨，所以使用Nvm进行版本管理。 Nvm按照安装包方式装完即用，不需要手动配环境变量。

前往 nvm-windows Releases，下载最新 nvm-setup.exe（如 nvm-setup-1.1.12.exe），双击安装。安装路径建议保持默认 C:\Users\用户名\AppData\Roaming\nvm。

装完后 重新打开一个 PowerShell 窗口（让 PATH 生效），验证：

nvm version

预期输出：

1.1.12

3.2 安装 Node.js 22 LTS

# 查看可安装的 LTS 版本列表
nvm list available

# 安装 Node.js 22 LTS
nvm install 22

# 切换到 22
nvm use 22

# 验证
node --version
npm --version

预期输出：

v22.14.0
10.9.2

如果 nvm list available 报错 "Could not retrieve..."，说明 nvm 无法访问 Node.js 官方分发地址。可以手动下载 Node.js 安装包后通过 nvm install 22 <本地路径> 安装，或者先配代理。

3.3 配置 npm 国内镜像源

npm 默认从 https://registry.npmjs.org 拉包，国内直连速度慢且容易超时。切换到 npmmirror（原淘宝镜像）即可解决。

# 设置镜像源
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry

预期输出：

https://registry.npmmirror.com

https://registry.npm.taobao.org 已于 2024 年停止服务，请使用新域名 https://registry.npmmirror.com。

（可选）同时建议配置几个常用二进制镜像，避免安装 Electron、node-sass 等包时卡住：

npm config set electron_mirror https://npmmirror.com/mirrors/electron/
npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass/
npm config set phantomjs_cdnurl https://npmmirror.com/mirrors/phantomjs/

3.4 安装 Claude Code

镜像源配好后，直接全局安装：

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

验证安装：

claude --version

预期输出：

v2.0.xx

如果提示 claude : 无法将"claude"项识别为 cmdlet...，说明 npm 全局 bin 目录不在 PATH 中，见 Debug #1。

3.5 安装 CC-Switch（Windows .msi 方式）

CC-Switch 是一个 GitHub 上 50K+ Star 的开源跨平台桌面应用，用于图形化管理 Claude Code、Codex、Gemini CLI 等多个 AI CLI 工具的模型供应商配置，内建 50+ Provider 预设。

下载安装：

1. 打开 CC-Switch Releases 页面
2. 找到最新版本（当前 v3.14.1），下载 CC-Switch-v3.14.1-Windows-x64.msi
3. 双击 .msi → 下一步 → 同意协议 → 保持默认路径 → 安装
4. 如遇 Windows SmartScreen 警告，点击"更多信息" → "仍要运行"
5. 完成后勾选"启动 CC-Switch" → 完成

桌面出现 CC-Switch 窗口即表示安装成功。

3.6 手动配置 Claude Code 免登录（关键前置步骤）

Claude Code v2.0.65+ 强制要求完成初次引导（Onboarding），即便配置了第三方 API 也会被卡住。需要手动修改两个 JSON 文件来跳过引导并指定 DeepSeek API。

文件一 ：C:\Users\<用户名>\.claude.json

作用：标记已完成初次引导，跳过 OAuth 登录弹窗。

如果文件不存在，手动创建，写入以下内容：

{
  "hasCompletedOnboarding": true
}

如果文件已存在，确保 JSON 中包含 "hasCompletedOnboarding": true（不要删除已有的其他字段）。

文件二 ：C:\Users\<用户名>\.claude\settings.json

作用：指定 Claude Code 使用 DeepSeek V4 Pro 的 Anthropic 兼容端点。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek-API-Key",
    "ANTHROPIC_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_SMALL_FAST_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-pro",
    "CLAUDE_CODE_EFFORT_LEVEL": "max",
    "API_TIMEOUT_MS": "3000000"
  },
  "model": "deepseek-v4-pro"
}

关键字段	值	说明
ANTHROPIC_BASE_URL	https://api.deepseek.com/anthropic	DeepSeek 的 Anthropic 兼容端点，末尾不要加 /v1 或斜杠
ANTHROPIC_AUTH_TOKEN	sk-xxxx	DeepSeek API Key，注意字段名是 AUTH_TOKEN 不是 API_KEY
ANTHROPIC_MODEL	deepseek-v4-pro	V4 Pro 旗舰模型，1.6T 参数，1M 上下文
ANTHROPIC_SMALL_FAST_MODEL	deepseek-v4-flash	V4 Flash 轻量模型，284B 参数，用于快速任务

⚠️ ANTHROPIC_AUTH_TOKEN 不是 ANTHROPIC_API_KEY 。DeepSeek 的 Anthropic 兼容端点校验的是 x-api-key header，但 Claude Code 通过 ANTHROPIC_AUTH_TOKEN 传递；DeepSeek 服务端做了映射，写错字段名会导致 401，见 Debug #5。

⚠️ DeepSeek 旧模型名 deepseek-chat / deepseek-reasoner 将于 2026-07-24 停用，务必使用 deepseek-v4-pro / deepseek-v4-flash。

3.7 在 CC-Switch 中配置 DeepSeek Provider（可选，与手动配置二选一）

如果你更习惯用 GUI 管理，CC-Switch 的配置会覆盖 settings.json 中的对应字段。两种方式效果等价------CC-Switch 本质上就是图形化的 settings.json 编辑器，所有数据存储在本地 SQLite，不上传。

1. 打开 CC-Switch 桌面应用
2. 点击主界面右上角 "+"（Add Provider）
3. 在预设列表中选择 DeepSeek （Base URL 自动填充为 https://api.deepseek.com/anthropic）
4. 填入你的 DeepSeek API Key
5. 模型选择 deepseek-v4-pro
6. 点击 Save ，然后在模型列表中点击 Enable 启用
7. Claude Code 一行在 CC-Switch 界面中显示为绿色对勾即表示生效

两种方式的关系：CC-Switch 修改的也是 C:\Users\<用户名>\.claude\settings.json。如果你已经按 3.6 手动编辑好了，CC-Switch 启动后会自动识别已有配置。如果你两边都做了，以最后写入的为准。

3.8 启动与验证

所有配置完成后，在任意项目目录下直接启动 Claude Code：

claude

预期终端出现：

  Claude Code v2.0.xx
  Anthropic's official CLI for Claude
  ------------------------------------
  > 输入 /help 查看可用命令，或直接输入问题开始对话

在 Claude Code 内确认当前模型：

> /model

预期输出：

Current model: deepseek-v4-pro

输入一个简单问题验证全链路：

> 你好，请简单介绍一下你自己

如果正常返回回复且 /model 显示 deepseek-v4-pro，说明全链路通了------Node.js 环境 → npm 镜像 → Claude Code → DeepSeek V4 Pro API 全线跑通。

---

四、Debug #1 --- claude 命令不可用（npm 全局 bin 不在 PATH）

报错日志

PS C:\Users\<用户名>> claude --version
claude : 无法将"claude"项识别为 cmdlet、函数、脚本文件或可运行程序的名称。

根因

npm 全局安装的可执行文件放在 C:\Users\<用户名>\AppData\Roaming\npm\ 目录下。nvm 管理的 Node.js 在切换版本时，PATH 环境变量中的 npm 全局 bin 路径可能不会被自动添加。Windows 的 PATH 配置分散在"系统变量"和"用户变量"两处，nvm 安装脚本只会更新用户变量中的 NVM_HOME 和 NVM_SYMLINK，不会主动追加 npm 全局 bin 路径。

一览对比表

对比维度	修复前	修复后
PATH 含 npm 全局 bin	❌ %APPDATA%\npm 不在 PATH	✅ 已追加
claude --version	无法将 claude 识别为 cmdlet	v2.0.xx
其他全局包（nrm 等）	全部不可用	全部可用

代码修复

步骤一：确认 npm 全局 bin 的实际路径。

npm config get prefix

预期输出：

C:\Users\<用户名>\AppData\Roaming\npm

步骤二：将该路径追加到用户 PATH 环境变量。

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Users\<用户名>\AppData\Roaming\npm", "User")

步骤三：重新打开 PowerShell，验证：

claude --version

验证

v2.0.xx

---

五、Debug #2 --- npm install 超时或速度极慢

报错日志

npm error code ETIMEDOUT
npm error errno ETIMEDOUT
npm error network request to https://registry.npmjs.org/@anthropic-ai/claude-code failed
npm error network This is a problem related to network connectivity.

根因

npm 默认向 https://registry.npmjs.org 发起请求。该域名托管在境外 CDN，国内直连延迟高、丢包率大，大包下载经常在中间断连。Claude Code 的包体积约几十 MB，网络抖动下几乎必超时。

一览对比表

对比维度	修复前	修复后
npm registry	https://registry.npmjs.org（境外默认）	https://registry.npmmirror.com（国内 CDN）
安装 50MB 包耗时	3~10 分钟（或直接超时）	10~30 秒
超时概率	高（大包几乎必超时）	极低

代码修复

# 检查当前源
npm config get registry

# 如果不是 npmmirror，切换
npm config set registry https://registry.npmmirror.com

# 再次确认
npm config get registry

验证

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

预期：30 秒内安装完成，无任何 timeout 或 network 错误。

---

六、Debug #3 --- Claude Code 提示 "Login required"（Onboarding 未跳过）

报错日志

Claude Code requires authentication.
Please run `claude login` or press Enter to open the login page in your browser.

After logging in via claude.ai, your session will be saved.

或者：

Unable to connect to Anthropic services.
Please check your network connection and try again.

根因

Claude Code v2.0.65 引入强制 Onboarding 检查。启动时读取 ~/.claude.json 中的 hasCompletedOnboarding 字段------如果该字段缺失或为 false，CLI 会进入登录引导流程，忽略 settings.json 中已配置的第三方 API 环境变量。这是一个已知 Bug（GitHub Issues #4714、#13827），社区反馈最后正常版本为 v2.0.64。

一览对比表

对比维度	修复前	修复后
C:\Users\<用户名>\.claude.json	文件不存在，或缺少 hasCompletedOnboarding	"hasCompletedOnboarding": true
启动行为	弹出 Login required → 阻塞	跳过引导，直接进入对话
settings.json 是否被读取	❌ 被引导流程覆盖忽略	✅ 正常读取 env 配置

代码修复

确认 C:\Users\<用户名>\.claude.json 存在且内容正确：

# 检查文件是否存在
Test-Path C:\Users\<用户名>\.claude.json

# 查看内容
Get-Content C:\Users\<用户名>\.claude.json

预期内容至少包含：

{
  "hasCompletedOnboarding": true
}

如果文件不存在或内容不对：

# 创建并写入
@"
{
  "hasCompletedOnboarding": true
}
"@ | Out-File -FilePath C:\Users\<用户名>\.claude.json -Encoding utf8

如果文件已存在且包含其他字段，用文本编辑器打开手动添加 "hasCompletedOnboarding": true 即可，不要覆盖已有的其他配置。

验证

重新执行 claude，应直接进入对话界面，不再出现 Login required。

---

七、Debug #4 --- API 调用返回 401 Unauthorized

报错日志

[ERROR] API request failed: 401 Unauthorized
  {"error":{"type":"authentication_error","message":"invalid x-api-key"}}

根因

Claude Code 通过 ANTHROPIC_AUTH_TOKEN 环境变量向 ANTHROPIC_BASE_URL 发送 x-api-key header。401 意味着服务端不认可这个 Key。常见原因有三个：

1. 字段名写错 ：settings.json 里写成了 ANTHROPIC_API_KEY 而非 ANTHROPIC_AUTH_TOKEN------DeepSeek 的 Anthropic 兼容端点只认 ANTHROPIC_AUTH_TOKEN 传递的值
2. API Key 无效：Key 拼写错误、已被撤销、或未在 DeepSeek 控制台勾选开通 V4-Pro 权限
3. 账户余额不足：V4-Pro 单次最低计费约 ¥0.98，余额需 ≥ ¥1.00

一览对比表

对比维度	修复前	修复后
环境变量名	ANTHROPIC_API_KEY（不被 DeepSeek 端点识别）	ANTHROPIC_AUTH_TOKEN（正确）
账户余额	可能不足 ¥1.00	≥ ¥1.00
服务端返回	401 Unauthorized	200 OK

代码修复

步骤一 ：确认 C:\Users\<用户名>\.claude\settings.json 中的字段名正确：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek-API-Key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"
  }
}

⚠️ 是 ANTHROPIC_AUTH_TOKEN，不是 ANTHROPIC_API_KEY。

步骤二 ：前往 DeepSeek Platform → API Keys 确认：

• Key 存在于API keys列表中
• 账户余额 ≥ ¥1.00

步骤三：用 curl 直接测试连通性：

$headers = @{
    "x-api-key" = "sk-你的DeepSeek-API-Key"
    "anthropic-version" = "2023-06-01"
}
$body = @{
    model = "deepseek-v4-pro"
    max_tokens = 100
    messages = @(@{role = "user"; content = "Hello"})
} | ConvertTo-Json -Depth 3

Invoke-RestMethod -Uri "https://api.deepseek.com/anthropic/v1/messages" `
    -Method Post -Headers $headers -Body $body `
    -ContentType "application/json"

验证

应正常返回 AI 回复，不再出现 401 错误。Claude Code 启动后 /model 显示 deepseek-v4-pro。

---

八、日常维护

8.1 启停命令

# 启动 Claude Code
claude

# 退出
# 在 Claude Code 交互界面中输入
/exit

# 或 Ctrl+C

CC-Switch 是桌面应用，不需要每次手动启停。开机后它在系统托盘运行，Claude Code 启动时自动读取其配置。

8.2 版本更新

更新 Claude Code：

npm update -g @anthropic-ai/claude-code
claude --version

更新 CC-Switch：

CC-Switch 内建自动更新------收到更新提示后点击更新即可。也可以去 Releases 页面 下载最新 .msi 覆盖安装。

升级 Node.js：

nvm install 22     # 22.x 内的最新补丁版本
nvm use 22

8.3 切换模型

CC-Switch 的热切换功能允许不重启 Claude Code 就换模型。在 CC-Switch 中切换 Provider 后，Claude Code 终端内 /model 即可看到更新。

也可以直接在 Claude Code 中临时指定模型：

/model deepseek-v4-flash

8.4 日志位置

Claude Code 日志：

C:\Users\<用户名>\.claude\logs\

关键搜索词：

# 错误
findstr "ERROR" C:\Users\<用户名>\.claude\logs\*.log

# API 请求
findstr "api.deepseek.com" C:\Users\<用户名>\.claude\logs\*.log

CC-Switch 日志：

CC-Switch 作为桌面应用，日志在应用内 Help → View Logs 查看。

---

九、速查卡

9.1 文件路径汇总

文件	绝对路径
nvm 安装根目录	C:\Users\<用户名>\AppData\Roaming\nvm\
Node.js（nvm 管理）	C:\Users\<用户名>\AppData\Roaming\nvm\v22.x.x\
npm 全局 bin 目录	C:\Users\<用户名>\AppData\Roaming\npm\
npm 全局 node_modules	C:\Users\<用户名>\AppData\Roaming\npm\node_modules\
npm 配置文件	C:\Users\<用户名>\.npmrc
Claude Code 可执行文件	C:\Users\<用户名>\AppData\Roaming\npm\claude.ps1
Claude Code 安装目录	C:\Users\<用户名>\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\
Claude Code 登录跳过	C:\Users\<用户名>\.claude.json
Claude Code API 配置	C:\Users\<用户名>\.claude\settings.json
Claude Code 日志目录	C:\Users\<用户名>\.claude\logs\
CC-Switch 安装目录	C:\Program Files\CC-Switch\
CC-Switch 数据存储	C:\Users\<用户名>\AppData\Roaming\CC-Switch\

9.2 关键配置字段速查

配置项	所属文件	说明
hasCompletedOnboarding: true	.claude.json	跳过 OAuth 登录引导
ANTHROPIC_BASE_URL	.claude/settings.json → env	DeepSeek 端点 https://api.deepseek.com/anthropic
ANTHROPIC_AUTH_TOKEN	.claude/settings.json → env	DeepSeek API Key（注意不是 API_KEY）
ANTHROPIC_MODEL	.claude/settings.json → env	默认模型 deepseek-v4-pro

9.3 常见报错 → 解决方案

报错	解决
claude 无法识别为 cmdlet	Debug #1：追加 npm 全局 bin 到 PATH
npm install ETIMEDOUT	Debug #2：切到 npmmirror 镜像源
Login required 弹窗	Debug #3：.claude.json 添加 hasCompletedOnboarding: true
API 401 Unauthorized	Debug #4：检查字段名是 ANTHROPIC_AUTH_TOKEN、Key 有效、余额充足
node --version 输出旧版本	nvm use 22 切换到安装的版本
CC-Switch 切换模型后不生效	Claude Code 支持热切换，/model 确认；若不生效，重启终端
deepseek-v4-pro 模型不可用	在 DeepSeek Platform 控制台勾选开通 V4-Pro 权限