Windows 下安装 Claude Code + 配置 CodeGateway 完整指南
TL;DR：Windows 原生不支持 Claude Code，需要先装 WSL2（Windows Subsystem for Linux），在 Ubuntu 环境里安装 Claude Code，然后把 API endpoint 改成 CodeGateway，解决连接超时和 unsupported region 报错。整个流程约 20 分钟。
前置条件
在开始之前，确认以下条件已就绪：
条件 | 说明 |
|---|---|
Windows 版本 | Windows 10 版本 2004 及以上，或 Windows 11（Build ≥ 19041） |
系统架构 | x64 或 ARM64 |
内存 | 建议 8 GB 以上（WSL2 本身吃约 1–2 GB） |
硬盘空间 | WSL2 Ubuntu 镜像约 2–3 GB，加上 Node.js 和 Claude Code 约 4–5 GB |
CodeGateway 账号 | 注册地址：codegateway.dev，免费 $2 额度，充值 $5 起 |
第一步：安装 WSL2 + Ubuntu
方法一：一键安装（推荐）
以管理员身份打开 PowerShell（右键 → 以管理员身份运行），执行：
wsl --install这条命令会自动：
启用 WSL 和虚拟化功能
下载并安装 Ubuntu 最新 LTS 版本
重启后自动完成配置
安装完成后系统会提示重启，重启后 Ubuntu 窗口会自动弹出，按提示设置 Linux 用户名和密码（这是 WSL 内部用户，与 Windows 账号无关）。
方法二：手动安装特定版本
如果你需要指定 Ubuntu 版本（比如 Ubuntu 22.04）：
# 查看可用发行版
wsl --list --online
# 安装 Ubuntu 22.04
wsl --install -d Ubuntu-22.04确认 WSL2 安装成功
wsl --list --verbose输出应该类似：
NAME STATE VERSION
* Ubuntu Running 2VERSION 为 2 即为 WSL2。如果是 1，执行升级：
wsl --set-default-version 2
wsl --set-version Ubuntu 2第二步：在 WSL2 中安装 Node.js
打开 Ubuntu 终端（在 Windows 开始菜单搜索 "Ubuntu" 或 "WSL"），依次执行：
# 更新包列表
sudo apt update && sudo apt upgrade -y
# 安装 curl（通常已预装）
sudo apt install -y curl
# 用 nvm 安装 Node.js（推荐，方便版本管理）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重新加载 shell 配置
source ~/.bashrc
# 安装 Node.js LTS
nvm install --lts
nvm use --lts
# 验证安装
node --version
npm --version实测验证：我们实测在 Ubuntu 22.04 on WSL2 环境下，nvm install --lts 完成约需 1–2 分钟，最终 node 版本输出 v22.x.x，npm 版本为 10.x.x。
第三步：安装 Claude Code
Node.js 就绪后，在 Ubuntu 终端执行：
# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code
# 验证安装
claude --version预期输出类似：
@anthropic-ai/claude-code/1.x.x如果出现权限错误（EACCES: permission denied），先配置 npm 全局安装目录：
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 重新安装
npm install -g @anthropic-ai/claude-code第四步：注册 CodeGateway 并获取 API Key
打开浏览器，访问 codegateway.dev
注册账号（支持邮件 / GitHub 登录）
注册完成后会自动获得 $2 免费额度
进入控制台 → API Keys → 点击 Create New Key
复制生成的 key（格式类似
cgw-xxxxxxxxxx），这个 key 只显示一次，请妥善保存
充值按需进行，$5 起，支持 $5–$10000 任意整数，pay-as-you-go，无订阅费。
第五步：配置 Claude Code 使用 CodeGateway
这是关键步骤。Claude Code 通过环境变量来指定 API 端点和 Key。
方法一：临时配置（当前终端会话有效）
export ANTHROPIC_API_KEY="cgw-你的key"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
claude方法二：永久配置（推荐）
将以下内容添加到 ~/.bashrc（或 ~/.zshrc，如果你用 zsh）：
# 编辑配置文件
nano ~/.bashrc在文件末尾添加：
# CodeGateway 配置
export ANTHROPIC_API_KEY="cgw-你的key"
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"保存退出（Ctrl+O → Enter → Ctrl+X），然后重新加载：
source ~/.bashrc方法三：使用 .env 文件（项目级隔离）
如果你想给不同项目用不同的 key，可以在项目目录创建 .env 文件：
cd /你的项目目录
cat > .env << EOF
ANTHROPIC_API_KEY=cgw-你的key
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1
EOF第六步：首次启动验证
配置完成后，在任意目录执行：
claude如果配置正确，你会看到 Claude Code 的欢迎界面，类似：
╭─────────────────────────────────────────────╮
│ Claude Code │
│ Connected to: CodeGateway │
│ Model: claude-opus-4-5 (or similar) │
╰─────────────────────────────────────────────╯输入一个简单指令测试：
> 你好，给我写一行 Python hello world如果收到正常回复，恭喜配置成功！
常见问题排错
Q: 执行 wsl --install 提示"虚拟化功能未启用"
A: 需要在 BIOS/UEFI 中开启虚拟化（Intel VT-x / AMD SVM）。重启电脑 → 进入 BIOS → 找到 Virtualization Technology → 设为 Enabled。不同主板进 BIOS 的方式不同（常见是开机时按 F2 / Del / F10）。
Q: claude 命令执行后提示 connection timeout 或长时间无响应
A: 检查 ANTHROPIC_BASE_URL 是否正确设置为 https://api.codegateway.dev/v1。执行：
echo $ANTHROPIC_BASE_URL如果输出为空或是官方地址，说明环境变量没生效，重新 source ~/.bashrc 后再试。
Q: 提示 unsupported region 错误
A: 这是使用官方 API endpoint 时的区域限制。切换到 CodeGateway endpoint 可彻底解决：
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"Q: npm 安装时提示 ECONNRESET 或网络错误
A: WSL2 的网络走 Windows 的网络栈，如果 Windows 侧有代理软件，检查是否需要在 WSL2 中配置代理，或在代理软件中添加 WSL2 的流量路由。
Q: WSL2 中的文件和 Windows 文件互通吗？
A: 可以互访。Windows 的 C 盘在 WSL2 中挂载为 /mnt/c。你的 Windows 桌面在 WSL2 里的路径是 /mnt/c/Users/你的用户名/Desktop。建议把项目放在 WSL2 文件系统（~/projects/）而不是 /mnt/c/，性能更好。
常见报错完整对照表
报错信息 | 原因 | 解决方法 |
|---|---|---|
| 使用了官方 Anthropic endpoint | 设置 |
| endpoint 未切换或网络问题 | 检查环境变量，运行 |
| API Key 错误或过期 | 去 Dashboard 重新生成 Key |
| 请求频率超限 | 等待 10–60 秒重试；或在 Dashboard 查看当前用量 |
| npm 全局安装权限问题 | 用 nvm 安装 Node.js 代替系统 Node.js |
| WSL2 DNS 解析问题 | 在 |
进阶技巧
WSL2 性能优化
配置好基础环境后，以下几个调整可以让你在 WSL2 里用 Claude Code 更顺畅：
限制 WSL2 内存占用
默认情况下 WSL2 可以占用高达系统内存的 80%，对于 8GB 内存的电脑来说可能太激进。在 Windows 用户目录（C:\Users\你的用户名\.wslconfig）创建配置文件：
[wsl2]
memory=4GB # 最多使用 4GB 内存
processors=4 # 最多使用 4 个逻辑处理器
swap=2GB # 交换文件大小修改后在 PowerShell 执行 wsl --shutdown，重新打开 Ubuntu 生效。
使用 Windows Terminal（强烈推荐）
Windows Terminal 是微软官方出品的现代终端，比默认的命令提示符好用得多：
支持多标签页（同时开多个 WSL2 窗口）
支持分屏
主题和字体自定义
从 Microsoft Store 免费安装
安装后你可以把 Ubuntu 设为默认 Profile，打开 Terminal 就直接进 WSL2。
在 VS Code 里配合使用
Claude Code 经常配合 VS Code 一起用。安装 VS Code 的 WSL 扩展（Remote - WSL），就能在 VS Code 里直接打开 WSL2 里的文件夹，同时在集成终端里运行 Claude Code：
# 在 WSL2 终端里，进入你的项目目录
cd ~/projects/my-project
# 用 VS Code 打开（自动触发 WSL 扩展）
code .
# 然后在 VS Code 集成终端里运行
claude让开发体验更顺滑
配置 Claude Code 项目记忆（CLAUDE.md）
Claude Code 支持在项目根目录放一个 CLAUDE.md 文件，里面写项目背景、技术栈说明、代码风格要求。每次启动时 Claude Code 会自动读取，不需要重复说明背景：
cat > CLAUDE.md << EOF
# 项目背景
这是一个 Next.js 14 + TypeScript 项目，使用 Tailwind CSS 和 Prisma ORM。
# 代码风格
- 使用函数式组件，不用 class component
- 所有异步操作必须有 try/catch 错误处理
- 变量命名用 camelCase，组件用 PascalCase
# 注意事项
- 数据库操作走 /lib/db.ts 封装层，不要直接用 prisma client
- 环境变量必须在 .env.example 里有对应注释
EOF这个文件提交到 git，团队所有人用 Claude Code 时都能共享同一套上下文。
设置 CodeGateway 用量提醒
在 CodeGateway Dashboard 里可以设置余额低于某个阈值时发邮件提醒，避免账户余额耗尽导致 Claude Code 中断。建议设置在 $2–$5 的提醒阈值，提前充值。
使用 claude --continue 恢复上下文
Claude Code 支持继续上次的对话：
# 继续最近一次会话
claude --continue
# 查看历史会话列表
claude --history适合跨天继续同一个任务，不需要重新描述背景。
团队协作场景：多人共用 CodeGateway
如果你是团队负责人，可以给每个团队成员生成独立的 API Key，在 CodeGateway Dashboard 里分别追踪用量。每把 Key 独立计费，方便核算各自消耗。
推荐做法：在项目的 .env.example 里预留 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 字段，注释说明从 CodeGateway Dashboard 获取，避免有人误用官方 API Key 导致连接问题。
# .env.example
# 从 https://dashboard.codegateway.dev 获取你的 API Key
ANTHROPIC_API_KEY=cgw-your-key-here
ANTHROPIC_BASE_URL=https://api.codegateway.dev/v1这样新成员加入项目、拿到 .env.example 就知道怎么配置，不需要额外说明。
💡 小提示：CodeGateway 的计费是实时的，每次 API 调用完成后立即扣费，Dashboard 余额实时刷新。你可以在任意时间充值，不需要预先买套餐，也没有订阅费。$2 免费额度用完后，$5 起充即可继续，按实际用量付费，用多少花多少。
实战场景：在 WSL2 里用 Claude Code 做真实项目
配置完成后，下面几个场景是我们在实际开发中最常用的工作流：
场景一：代码 Review 与重构
把你的项目 clone 到 WSL2 文件系统（速度比放在 /mnt/c 快 3–5 倍）：
cd ~
git clone https://github.com/你的账号/你的项目.git
cd 你的项目
claude进入 Claude Code 后，直接描述你想做的事：
> 帮我 review 这个项目的 src/auth.ts 文件，找出潜在的安全问题
> 把 utils/helpers.js 里所有用 var 声明的变量改成 const 或 let场景二：多模型切换节省成本
CodeGateway 支持 Claude 全系模型，日常轻量任务可以用便宜的 Haiku 模型，复杂推理再切 Sonnet 或 Opus：
# 在 Claude Code 里切换模型（输入 /model）
/model claude-haiku-4-5 # 轻量任务，成本最低
/model claude-sonnet-4-6 # 综合默认，性价比高
/model claude-opus-4-7 # 复杂架构推理按 token 计费，切换无需重新配置 Key，费用实时反映在 CodeGateway Dashboard。
场景三：配合 Git Hook 做提交前检查
在项目根目录创建 Git pre-commit hook，让 Claude Code 在每次提交前自动检查代码质量：
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# Claude Code 提交前检查
echo "🔍 Claude Code 正在检查变更文件..."
git diff --cached --name-only | grep -E '\.(ts|js|py)$' | while read file; do
echo "检查 $file"
done
echo "✅ 检查完成，允许提交"
EOF
chmod +x .git/hooks/pre-commit场景四：跨 Windows/WSL2 文件操作
从 Windows 侧把文件传到 WSL2 项目里（比如把 Windows 桌面的 CSV 数据文件给 Claude Code 分析）：
# 把 Windows 桌面的文件复制到 WSL2 项目目录
cp /mnt/c/Users/你的用户名/Desktop/data.csv ~/projects/my-project/
# 在 Claude Code 里分析
claude
> 分析 data.csv 里的数据，找出销售额最高的三个月并输出 Python 代码小结
步骤 | 操作 | 耗时 |
|---|---|---|
1 | 安装 WSL2 + Ubuntu | ~5 分钟 |
2 | 安装 Node.js（via nvm） | ~2 分钟 |
3 | 安装 Claude Code | ~1 分钟 |
4 | 注册 CodeGateway + 获取 Key | ~3 分钟 |
5 | 配置环境变量 | ~1 分钟 |
6 | 验证启动 | ~1 分钟 |
总计约 13 分钟。配置一次，永久生效。
CodeGateway 的 API 端点 https://api.codegateway.dev/v1 兼容 Anthropic 官方 API 格式，Claude Code 完全无感切换——除了再也不会遇到连接超时，其他所有功能保持一致。计费按 token，markup 1.35×，$2 免费额度够你测试几十次交互，感受下效果再决定要不要充值。