Claude Code 完整入门教程：从 Git Bash 到 cc-switch 的配置实践-开发者社区

1. Windows 上跑 Claude Code 到底卡在哪：从 Git Bash 到 Node.js 的完整链路

很多人第一次在 Windows 上装 Claude Code，卡住的地方往往不是 Claude Code 本身，而是它依赖的两个前置件：Git Bash 和 Node.js。Claude Code 是一个跑在终端里的 AI 编程助手，它能读你项目里的文件、执行命令、改代码，但它的运行方式是类 Unix 的，Windows 自带的 CMD 和 PowerShell 在路径处理、脚本执行策略上和它配合起来经常出岔子。Git Bash 提供了一套类 Linux 的命令行环境，Node.js 则是 Claude Code 的运行底座，缺一个都跑不起来。

这篇文章面向的是刚接触 Claude Code、想在 Windows 本地把第一个对话请求跑通的人。我会从 Git Bash 安装讲到 Node.js 环境验证，再到 cc-switch 多模型切换和 DeepSeek 接入，每一步都给可复制的命令和配置片段。你跟着做，最后能在终端里看到 Claude Code 正常回你话，并且知道它当前用的是哪个模型。

先说清楚这套链路的关系：你在 Git Bash 里敲claude命令，Claude Code 这个 Node.js 程序启动，它读取你的 settings 配置，拿到 API Base URL、API Key 和 Model ID，然后向对应的模型服务发请求。cc-switch 的作用是帮你管理多套这样的配置，一键切换不同模型提供商，不用每次手动改配置文件。理解了这个链路，后面每一步你都知道自己在干什么。

我实测下来，Windows 上最容易出问题的三个点：一是 Node.js 装完npm -v报执行策略错误；二是 Claude Code 装完claude -v找不到命令；三是 cc-switch 配好之后 Claude Code 还是走默认通道。这三个坑后面都会给排查方法。

2. 前置准备：Git Bash 与 Node.js 安装验证的完整步骤

2.1 安装 Git Bash

Git Bash 是 Git for Windows 自带的终端环境。打开 Git 官网下载页，选 64 位安装包，双击 exe 一路 Next 用默认选项即可。安装完成后在桌面空白处右键，菜单里出现 "Open Git Bash here" 就说明装好了。点开它，你会看到一个黑底白字的命令行窗口，这就是后面所有操作的入口。

验证 Git 是否可用，在 Git Bash 里输入：

git --version

能返回类似git version 2.4x.x就通过了。

2.2 安装 Node.js

Claude Code 基于 Node.js 开发，没有它跑不起来。去 Node.js 官网，选 LTS 长期支持版，不要选 Current 尝鲜版。下载 msi 安装包后双击，一路 Next，其中有一个 "Tools for Native Modules" 页面，把复选框勾上，它会顺带装一些编译工具，后面装某些 npm 包时用得到。

装完后回到 Git Bash，验证两条命令：

node -v npm -v

正常会返回v20.x.x和10.x.x这样的版本号。如果npm -v报错，提示类似 "无法加载文件，因为在此系统上禁止运行脚本"，这是 PowerShell 执行策略的问题。以管理员身份打开 PowerShell，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 回车，然后回到 Git Bash 重新跑npm -v即可。

2.3 安装 Claude Code

环境就绪后，安装 Claude Code 只需要一条命令。在 Git Bash 里输入：

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

-g表示全局安装，装完后在任何目录都能调用claude命令。如果下载慢，可以换国内镜像源：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

安装完成后验证：

claude --version

能返回版本号就说明 Claude Code 已经装好了。如果提示claude: command not found，检查 npm 全局安装路径是否在系统 PATH 里，可以用npm config get prefix查看全局路径，把它加到环境变量中。

2.4 整体环境自检

在进入配置之前，把四条命令依次跑一遍，全部返回版本号才算环境完整：

git --version node -v npm -v claude --version

这一步别跳过。我见过不少人 Claude Code 装完直接去配模型，结果请求发不出去，回头排查发现是 Node.js 版本太旧或者 Git Bash 没装对。先把地基打牢，后面省很多事。

3. cc-switch 配置 DeepSeek：可复制的 settings 与多模型切换实践

3.1 为什么需要 cc-switch

Claude Code 默认走 Anthropic 官方通道，需要海外支付方式和对应的 API Key，对国内用户门槛不低。cc-switch 是一个模型切换工具，它帮你管理多套模型提供商配置，一键切换。你可以同时配好 DeepSeek、其他兼容 OpenAI 格式的模型，需要哪个切哪个，不用手动改配置文件。

cc-switch 的安装包在 GitHub 上有发布，国内下载慢的话可以用镜像站。Windows 用户下载.msi安装包，双击一路 Next。装完后建议以管理员身份运行，因为它需要修改 Claude Code 的配置文件，权限不够会写不进去。

3.2 获取 DeepSeek API Key

打开 DeepSeek 官网注册登录，进入控制台，找到「API Keys」或「密钥管理」，点「创建 API Key」，起个名字比如claude-code，复制生成的密钥字符串。这个 Key 只显示一次，关掉就看不到了，先存好。新用户一般有免费额度，可以先体验。

模型选择上，DeepSeek 提供不同档位的模型，推理能力强的适合复杂重构和大型项目理解，响应快、价格低的适合日常编码和快速问答。根据你的场景选。

3.3 在 cc-switch 中配置

打开 cc-switch，点「添加提供商」，如果列表里有 DeepSeek 直接选，没有就选「自定义 Provider」或「OpenAI Compatible」，因为 DeepSeek 的接口兼容 OpenAI 格式。然后按顺序填三项：

配置项	填写内容
API Base URL	`https://api.deepseek.com`
API Key	你复制的 DeepSeek 密钥
Model ID	你选定的 DeepSeek 模型名称

填完点保存，然后在主界面把刚配的 DeepSeek 设为当前激活项。如果你希望 Claude Code 默认就走 DeepSeek，在设置里勾选「设为默认」。

3.4 Claude Code 的 settings 配置文件

cc-switch 本质上是在帮你写 Claude Code 的配置文件。你也可以手动配置，配置文件通常位于用户目录下的.claude/settings.json。一个可复制的配置片段如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com", "ANTHROPIC_API_KEY": "你的DeepSeek密钥", "ANTHROPIC_MODEL": "你的DeepSeek模型ID" } }

注意三个关键字段：ANTHROPIC_BASE_URL指向模型服务的接口地址，ANTHROPIC_API_KEY是你的密钥，ANTHROPIC_MODEL指定用哪个模型。这三件套配齐，Claude Code 才知道往哪发请求、用什么身份、调哪个模型。

如果你用的是 TaoToken 这类聚合服务，Base URL 填https://taotoken.net/api，Key 和 Model ID 从控制台获取。配置逻辑完全一样，只是地址和密钥换成对应平台的。

3.5 多模型切换的实际用法

cc-switch 的价值在多模型场景下才体现出来。比如你日常编码用响应快的模型，遇到复杂重构切到推理强的模型，两个配置都存好，点一下切换就行。切换后 Claude Code 下次启动就会读新的配置。

这里有个细节：切换配置后，已经打开的 Claude Code 会话不会自动生效，需要退出重进。我踩过的坑就是切了模型但当前会话还在用旧的，排查半天以为是配置没写对。

4. 验证请求：从启动 Claude Code 到看到模型回复

配置写好了不代表就能跑通，得实际发一个请求验证。打开 Git Bash，进入你的项目目录，输入：

claude

第一次启动可能会让你确认一些初始化选项，按提示走就行。进入交互界面后，直接问一个能暴露模型身份的问题：

你现在用的是什么模型？

如果它回答的模型名称和你配置的一致，说明请求链路通了。如果它报连接错误或者返回的模型不对，说明配置有问题，往下看排查部分。

再做一个更实际的验证，让它读一个文件：

帮我看看当前目录下有哪些文件，然后解释一下 package.json 的作用

这个请求会触发 Claude Code 读取文件系统，能验证它不只是能对话，还能实际操作你的项目。如果它能列出文件并解释内容，说明工具调用也正常。

验证成功后，你可以试试更复杂的指令，比如让它创建一个简单的脚本文件、修改某个配置、或者解释一段代码的逻辑。这些才是 Claude Code 作为 AI 编程助手的日常用法。

如果你在验证阶段想先确认模型本身是否可用，可以到模型对话页面直接发一条消息测试，排除是 Claude Code 配置问题还是模型服务问题。接入相关的文档里也有各平台的配置示例，对照检查更快定位。

5. 常见报错逐条排查：401、连接失败、模型不存在怎么解

5.1 401 认证失败

报错信息通常是401 Unauthorized或authentication_error。原因基本是 API Key 有问题：要么 Key 复制时带了空格，要么 Key 已失效或被删除，要么 Base URL 和 Key 不匹配（比如把 A 平台的 Key 填到了 B 平台的地址上）。排查方法：重新复制 Key，确认前后没有多余字符；到模型平台控制台确认 Key 状态正常；核对 Base URL 和 Key 是否属于同一平台。

5.2 连接失败或超时

报错可能是connection refused、ETIMEDOUT或local proxy failed。先检查 Base URL 是否拼写正确，有没有多写或少写路径。然后确认你的网络能访问该地址，可以在 Git Bash 里用curl测试：

curl -I https://api.deepseek.com

如果返回 HTTP 状态码说明网络通，问题在配置；如果直接超时，说明网络层有问题，检查代理设置或换个网络环境。

5.3 模型不存在

报错类似model not found或invalid model。这是 Model ID 拼写错误，或者你填的模型名称该平台不支持。回到模型平台的文档页，确认可用的模型 ID 列表，复制准确的名称填进去。注意大小写和连字符，deepseek-v4-pro和deepseek-v4-Pro可能就不一样。

5.4 Claude Code 命令找不到

claude: command not found说明 npm 全局路径没在 PATH 里。运行npm config get prefix拿到全局安装路径，把这个路径加到系统环境变量的 PATH 中，重启 Git Bash 再试。

5.5 cc-switch 切换后不生效

切换配置后 Claude Code 还在用旧模型，先退出当前 Claude Code 会话再重新启动。如果还是不生效，检查 cc-switch 是否以管理员权限运行，配置文件是否真的写入了。可以手动打开.claude/settings.json看内容有没有更新。

5.6 OAuth 相关报错

如果报错涉及OAuth或token refresh failed，说明 Claude Code 在尝试走官方认证流程，但你配置的是第三方通道。检查 settings 里是否正确设置了ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，这两个字段会覆盖默认的认证方式。配置对了就不会再走 OAuth。

排查的核心思路就一条：先确认网络能通，再确认 Key 有效，最后确认 Model ID 正确。这三样都没问题，请求基本能跑通。