国内 Windows 11 使用 Claude Code 完整教程

GaryYoung_

409人浏览 · 2026-09-06 11:20:47

GaryYoung_ · 2026-09-06 11:20:47 发布

一、先搞懂原理：Claude Code 是什么

很多新手卡在第一步，是因为没搞明白一件事：

一句话核心

Claude Code 只是一个“终端壳子 / 操作界面”，它本身不会思考。真正回答问题、写代码的是背后的“大模型”。

我们在国内的任务，就是把 Claude Code 这个壳子，连接到国内能用的大模型（本文用阿里百炼的通义千问 Qwen）。

1.1 整体连接关系

角色	是什么	本文对应
Claude Code	终端里的 AI 编程助手客户端（命令行界面）	npm 全局安装，命令 claude
大模型（LLM）	真正思考、回答、写代码的“大脑”	阿里百炼 Qwen3-Coder
API Key	调用大模型的“钥匙 / 密码”	百炼控制台创建的 sk-ws-... 密钥
Base URL	告诉 Claude Code 去哪里找大模型	百炼的 Anthropic 兼容地址

所以整套流程就是四件事，做完就能用：

安装 Node.js（给 Claude Code 运行环境）
用 npm 安装 Claude Code
注册阿里百炼、创建 API Key（拿到“大脑”和“钥匙”）
把 Key 和地址填进 Windows 系统环境变量（让壳子连上大脑）

二、安装 Node.js 并配置环境变量

2.1 下载 Node.js

打开浏览器，访问官网：

https://nodejs.org（建议选 LTS 长期支持版，本文以 v24 为例）

首页会看到两个大按钮，点 “LTS” 那一边的下载（Windows Installer .msi，64-bit）。

小白提醒

下载的是 .msi 安装包，双击一路“下一步”即可，不用手动配置 PATH。

Node.js 自带 npm（包管理器），安装 Node 就一起装好了。

2.2 安装 Node.js

双击下载好的 .msi 文件。

安装向导一路点 “Next”。
到 “Tools for Native Modules” 这一步时，勾选 “Automatically install the necessary tools”（自动装构建工具，以后装某些包需要）。
点 “Install”，等待完成，点 “Finish”。

2.3 验证安装 + 配置 npm 全局目录（推荐）

默认情况下 npm 会把全局包装在 C 盘用户目录下。为了避免权限问题、也方便管理，建议把全局目录改到你自己的位置（本文沿用 C:\Tools\nodejs\npm-global）。

以管理员身份打开 CMD（命令提示符）：

按 Win 键，搜索 “cmd”，右键 “以管理员身份运行”

依次执行下面命令（每行回车一次）：

mkdir C:\Tools\nodejs\npm-global mkdir C:\Tools\nodejs\npm-cache npm config set prefix "C:\Tools\nodejs\npm-global" npm config set cache "C:\Tools\nodejs\npm-cache"

命令解释

prefix = 全局包安装到哪（claude 命令就会在这里）

cache = 下载缓存放哪

改成你喜欢的位置也可以，但下文 PATH 要对应修改。

2.4 把 npm 全局目录加入系统 Path（全局生效关键）

这一步决定你能否在任何目录输入 claude 都生效，是“全局配置”的核心。

Win + R，输入 sysdm.cpl，回车 → “高级” 选项卡 → 右下角 “环境变量”。

在 “系统变量”（下半区）里找到变量 Path，双击编辑。
点 “新建”，添加两行：

C:\Tools\nodejs\npm-global
C:\Tools\nodejs\npm-global\node_modules\.bin

一路确定保存，关闭所有终端。

重要区分（小白必看）

“系统变量” = 整台电脑所有用户都生效（本文要的全局）

“用户变量” = 只有当前用户（如 YONG）生效（不要配在这里）

Path 里不要重复添加 npm-global\node_modules（顶层目录即可）。

2.5 验证 Node 与 npm

重新打开 CMD（不用管理员也行），输入：

node -v npm -v

如果分别输出类似 v24.x.x 和 11.x.x 的版本号，说明成功。

三、安装 Claude Code

确保上一步 node / npm 都正常后，用 npm 全局安装（一次即可，整台电脑可用）：

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

包名千万别写错

正确：@anthropic-ai/claude-code

错误：claude-code（这是个仿冒/无关包）

3.1 验证 Claude 命令

关闭再重开 CMD，确保 PATH 生效，执行：

claude --version where claude

期望输出：

2.1.261 (Claude Code) C:\Tools\nodejs\npm-global\claude.cmd

只要 where claude 能找到 claude.cmd，说明安装到位。

3.2 前置依赖：Git（强烈建议安装）

Claude Code 内部工具依赖 Git Bash，Windows 下建议先装 Git：

下载：https://git-scm.com ，一路默认下一步

装完后新开 CMD 验证：

git --version

有版本号输出即可。若需要，可显式告诉 Claude Code Git 路径：

claude config set env.CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"

四、注册阿里百炼并创建 API Key

因为国内不能直接用 Anthropic 官方 Claude，我们用兼容接口把 Claude Code 接到阿里百炼的通义千问（Qwen）模型上。百炼有免费额度，注册用手机号 + 支付宝实名即可，不用海外卡。

4.1 注册并实名

打开 https://www.aliyun.com ，点 “免费注册”。

用手机号注册，或用支付宝/淘宝一键登录。
登录后右上角头像 → “实名认证” → 选 “个人实名” → 支付宝刷脸（几分钟完成）。

为什么必须实名？

阿里云创建 API Key 要求账号已完成实名认证，否则按钮是灰色的。

只需要个人实名，不需要绑卡或付费。

4.2 开通百炼服务（自动送免费额度）

进入百炼控制台：https://bailian.console.aliyun.com

首次进入会提示 “开通服务”，勾选协议 → “立即开通 / 免费体验”。
开通后系统自动发放新人免费额度（各模型约 100 万 token，有效期 90 天）。

4.3 创建 API Key（核心步骤）

在百炼控制台首页左侧/常用功能，找到并点击 “API Key”。

点击右上角 “创建 API Key”。
业务空间选 “默认业务空间”，归属账号选主账号，确认创建。
立即复制以 sk- 开头的密钥！

⚠️ 密钥只显示一次

关闭弹窗后就再也看不到完整 Key，只能删掉重建。

建议立刻粘贴到记事本 / 密码管理器妥善保存。

你的 Key 形如：sk-ws-H.PMYYIPP.xxx...（很长一串）

4.4 记下你的专属 Base URL

创建 Key 的弹窗或 API Key 管理页，会显示你的业务空间专属地址。Claude Code 用其中的 Anthropic 兼容路径：

https://<你的专属域名>.cn-beijing.maas.aliyuncs.com/apps/anthropic

例如你截图里的：

https://ws-soybyah8eliuiuiz.cn-beijing.maas.aliyuncs.com/apps/anthropic

URL 铁律

以 /apps/anthropic 结尾，不要再加 /v1 或 /v1/messages。

Claude Code 会自动拼接后面的路径。

用你自己账号显示的专属域名，不要照抄别人的。

五、Windows 系统级全局配置（不限于当前用户）

目标：把 Base URL 和 API Key 写进 Windows “系统变量”，让这台电脑任何用户、任何终端打开 claude 都能用。

5.1 先弄懂两个容易混的变量（重点）

变量名	给谁用	本文要不要设
ANTHROPIC_API_KEY	Anthropic 官方（美国原版 Claude，sk-ant- 开头）	不要设 / 有就删掉
ANTHROPIC_AUTH_TOKEN	国内兼容服务（百炼、DeepSeek、智谱等，sk-ws- 开头）	要设，填百炼 Key

一句话记忆

连美国原版 Claude → 用 ANTHROPIC_API_KEY

连阿里百炼（本文）→ 用 ANTHROPIC_AUTH_TOKEN，并且不能留着 ANTHROPIC_API_KEY

两个同时存在 → 100% 报 401 认证错误。

5.2 配置系统环境变量（图形界面法，推荐小白）

Win + R → 输入 sysdm.cpl → 回车。

“高级” 选项卡 → 右下角 “环境变量”。
下半区 “系统变量” → “新建”，逐条添加下面变量：

变量名	变量值
ANTHROPIC_BASE_URL	https://<你的专属域名>.cn-beijing.maas.aliyuncs.com/apps/anthropic
ANTHROPIC_AUTH_TOKEN	sk-ws-你的完整密钥
ANTHROPIC_MODEL	qwen3-coder-plus
ANTHROPIC_DEFAULT_SONNET_MODEL	qwen3-coder-plus
ANTHROPIC_DEFAULT_HAIKU_MODEL	qwen3-coder-flash
ANTHROPIC_DEFAULT_OPUS_MODEL	qwen3-coder-plus
CLAUDE_CODE_SUBAGENT_MODEL	qwen3-coder-flash
API_TIMEOUT_MS	300000
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC	1

在 “系统变量” 里搜索是否已有 ANTHROPIC_API_KEY，有就删除 / 置空。
一路确定保存 → 关闭所有 CMD / PowerShell / VS Code → 重新打开 CMD。

5.3 或用 PowerShell 一键写入（管理员）

不想一个个手填，可用管理员 PowerShell 执行（把 Key 换成你自己的）：

$v = [System.EnvironmentVariableTarget]::Machine [System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://<你的域名>/apps/anthropic", $v) [System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-ws-你的完整密钥", $v) [System.Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "qwen3-coder-plus", $v) [System.Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_SONNET_MODEL", "qwen3-coder-plus", $v) [System.Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_HAIKU_MODEL", "qwen3-coder-flash", $v) [System.Environment]::SetEnvironmentVariable("ANTHROPIC_DEFAULT_OPUS_MODEL", "qwen3-coder-plus", $v) [System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_SUBAGENT_MODEL", "qwen3-coder-flash", $v) [System.Environment]::SetEnvironmentVariable("API_TIMEOUT_MS", "300000", $v) [System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1", $v) [System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $null, $v)

5.4 跳过 Anthropic 官方登录（必须）

Claude Code 启动会检查是否完成官方引导，国内没账号会卡住。需创建一个状态文件跳过。

关于必须用一次用户目录的说明

这一步只需做一次，且只是跳过官方登录，模型配置仍是系统级全局。

用记事本新建 C:\Users\YONG\.claude.json，内容为：

{ "hasCompletedOnboarding": true }

若文件已存在（里面有 firstStartTime 等内容），不要覆盖，只在末尾加逗号后补一行：

"hasCompletedOnboarding": true

5.5 验证环境变量

在重新打开的 CMD 里执行：

echo %ANTHROPIC_BASE_URL% echo %ANTHROPIC_AUTH_TOKEN% echo %ANTHROPIC_MODEL% echo %ANTHROPIC_API_KEY%

期望：前三个有值，最后一个为空（无输出）。

六、启动 Claude Code 并验证连通

6.1 先做一次连通测试

不要直接在 C:\Windows\System32 下启动，先切到一个工作目录：

cd /d D:\ClaudeWork claude -p "你好，用一句话说你背后接的是哪个模型"

若返回中文、并提到 Qwen / 通义千问，说明整条链路已通。

6.2 进入交互模式

cd /d D:\ClaudeWork claude

首次进入某文件夹，会出现安全确认：

安全确认：Trust this folder

Claude Code 会问：是否信任此文件夹（它可读取/编辑/执行其中文件）。

用方向键选 “Yes, I trust this folder”，按 Enter。

陌生/下载的代码目录不要随便信任。

6.3 进入后必敲的两个命令

命令	作用
/status	查看当前 Auth token、Base URL、Model 是否正确指向百炼
/init	扫描项目、生成 CLAUDE.md，让 AI 了解你的项目
/model	查看/切换模型
/help	查看全部斜杠命令
/compact	压缩上下文，省 token
/clear	清空当前对话，换任务时用
/exit 或 /quit	退出 Claude Code

6.4 日常怎么下指令（直接用中文说话即可）

解释当前项目结构
给 src/app.js 加上中文注释
写一个 Express 的 GET /api/hello 接口，返回 JSON
为什么 npm start 报错？帮我定位和修复
按项目现有代码风格重构这个函数

也可以指定具体文件，更省 token：

@src/auth.py 给这个文件写单元测试

七、注意事项与常见报错速查

7.1 安全与习惯

只在自己信任的项目目录使用，重要项目先用 git 提交一次再让 AI 改。
让 AI 先分析、出方案，确认后再改文件（说 “先只分析，不要修改”）。
涉及 npm install / rm -rf / git push --force 等危险操作，先看它要执行什么。
不要把真实密钥、密码、内部数据粘贴进对话。
不要照抄网络教程里的 sk- 密钥，那都是假的/失效的，用自己的。

7.2 黄色模型提示要不要管？

关于 qwen3-coder-plus 未识别提示

启动时若提示 “qwen3-coder-plus isn't described by this version's model catalog”，

这只是 Claude Code 本地不认识 Qwen 模型名，不影响实际调用。

只要 /status 显示 model 正确、claude -p 能正常回答，就可以忽略。

7.3 常见报错速查表

报错 / 现象	原因	解决办法
401 authentication_error	用了 ANTHROPIC_API_KEY，或两者共存	删掉 API_KEY，只用 AUTH_TOKEN
fetch failed / ENOTFOUND	Base URL 拼错、多了 /v1	还原为 .../apps/anthropic
404 model not found	模型名写错	核对平台实际可用模型 ID
还提示登录 Claude / 弹浏览器	环境变量未加载 / 未跳过引导	重开终端；设 hasCompletedOnboarding
claude 不是内部命令	PATH 没包含 npm-global	检查系统变量 Path 并重开
超时无响应	网络慢	设 API_TIMEOUT_MS=300000