Claude Code + GLM Windows WSL 安装 SOP¶

适用场景¶

本文适用于以下环境：

Windows 主机
使用 WSL 2 作为开发终端
使用带代理/梯子的网络方式
在 WSL 中安装并运行 Claude Code
通过智谱 GLM Coding Plan 接入 GLM-5.1 或 GLM-5

技术咨询¶

豆包，用于回答技术问题 https://www.doubao.com/chat/
学员群，询问有经验的同学或教职工

由于教职工资源有限，技术问题请优先询问豆包解决。

官方参考¶

智谱 Claude Code 接入文档：Link
智谱 Coding Tool Helper：Link
智谱 GLM Coding Plan FAQ：Link
智谱开放平台：Link
Microsoft Learn: Install WSL：Link
Microsoft Learn: WSL networking：Link
Microsoft Learn: Node.js on WSL：Link
Git for Windows：Link
VS Code Windows 安装：Link
VS Code WSL 教程：Link
VS Code WSL 插件：Link
VS Code Remote Development 概览：Link

总体思路¶

安装顺序建议固定为：

在 Windows 上安装并启用 WSL 2
在 Windows 上安装 VS Code
在 Windows 上安装 WSL 扩展，并以 WSL Remote 方式打开 Linux 工作目录
在 Windows 上确认代理/VPN 已可用，并在 WSL 的 Ubuntu 中配置代理继承
在 WSL 中安装 git、nvm、Node.js
在 WSL 中安装 Claude Code
使用智谱官方 coding-helper 把 Claude Code 接到 GLM
启动 claude 并验证模型映射

前置准备¶

1. Windows 侧准备¶

建议使用 Windows 11
若为 Windows 10，建议至少 2004 / Build 19041+
安装 Git for Windows
确保本机代理/VPN 已可正常连接外网

2. 建议准备的信息¶

智谱开放平台账号
已开通的 GLM Coding Plan
一枚可用的智谱 API Key
代理端口信息，例如 7890

步骤一：安装 WSL 2¶

在按win键打开windows菜单，搜索PowerShell，右键点击以管理员身份打开 PowerShell，执行：

wsl --install -d Ubuntu

如果安装过程卡住，或者长时间停在下载阶段，可改用微软官方的 web 下载方式：

wsl --install --web-download -d Ubuntu

安装完成后，重启 Windows。

重启后进入win菜单，搜索并打开 Ubuntu，按提示创建：

Linux 用户名
Linux 密码

然后回到 PowerShell 检查 WSL 状态：

wsl --status
wsl -l -v

如果 Ubuntu 不是 WSL 2，部分功能可能缺失，应执行：

wsl --set-version Ubuntu 2

步骤二：在 Windows 上安装 VS Code¶

建议直接使用 VS Code 官方 Windows 安装程序。

操作步骤：

打开 VS Code 官方 Windows 安装页
下载 Windows Installer，也就是 VSCodeUserSetup-{version}.exe
双击安装，按默认设置完成安装即可
安装完成后，重新打开 PowerShell 或 WSL 终端

根据 VS Code 官方文档，安装程序会把 code 加入 Windows 的 %PATH%。
如果你安装后马上执行 code 提示找不到命令，通常只需要重开终端即可。

可在 Windows 终端中验证：

code --version

步骤三：安装 WSL 插件并用 VS Code 打开 Ubuntu 工作目录¶

1. 安装 WSL 插件¶

在 Windows 上启动 VS Code，按 Ctrl+Shift+X 打开扩展面板，搜索并安装：

WSL
发布者：Microsoft
扩展标识：ms-vscode-remote.remote-wsl

如果你之后还会用到 SSH、容器或 Tunnel，也可以直接安装官方的 Remote Development 扩展包。
但对当前这份 SOP 来说，必需的是 WSL 插件。

2. 以 WSL Remote 模式打开项目¶

推荐方式是在 WSL 终端里进入项目目录后直接执行：

cd ~/your-project
code .

根据 VS Code 官方 WSL 教程，第一次这样启动时，VS Code 会自动在 WSL 里安装一份对应版本的 VS Code Server。
如果弹出允许访问 Node.js-based server 的提示，选择允许即可。

也可以从 VS Code 图形界面进入 WSL：

按 F1 打开命令面板
输入 WSL: New Window
在新窗口中选择 Open Folder
打开 WSL 中的 Linux 路径，例如 /home/<用户名>/project

3. 判断当前是否真的连在 WSL 上¶

连接成功后，至少会看到这些现象：

左下角状态栏显示类似 WSL: Ubuntu
Terminal > New Terminal 打开的是 WSL 里的 shell
打开项目后，文件路径显示为 Linux 路径

4. WSL 插件的实际使用规则¶

这部分很关键：

VS Code 的界面运行在 Windows 上
终端、命令、调试、以及大部分和项目相关的扩展运行在 WSL 里

连接到 WSL 后，扩展面板里通常会出现类似 WSL: Ubuntu - Installed 的分区。
如果你安装的是语言类扩展，例如 Python、Go、C/C++、ESLint 等，推荐在 WSL 上下文 中安装，这样它们会直接使用 WSL 内部的解释器、编译器和依赖。

一个实用判断方式是：

改界面主题、图标、快捷键的扩展，通常装在 Windows 本地即可
跟项目运行、Lint、调试、补全有关的扩展，通常应装在 WSL: Ubuntu

5. 与 WSL 配合时的建议¶

如果你的项目代码、Node.js、Python、Claude Code 都放在 WSL 的 Linux 文件系统中，推荐始终用 WSL Remote 方式打开项目。
基于 VS Code 官方文档的说明，可以推断出：如果只是把 \\wsl.localhost\... 当作普通 Windows 文件夹打开，很多终端、调试和扩展能力会落回 Windows 上下文，达不到“工具链全部跑在 Linux 里”的效果。

步骤四：为 WSL 配置代理继承¶

因为你选择的是“带梯子”的方式，这一步很重要。
仅在 Windows 上开代理通常不够，npm、npx、claude 在 WSL 里仍可能访问失败。

1. 推荐做法：启用 mirrored networking + autoProxy¶

编辑（这里建议用VSCode 编辑） Windows 用户目录下的 C:\Users\你的用户名\.wslconfig：

[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=true

保存后在 PowerShell 执行：

wsl --shutdown

然后重新打开 Ubuntu。

2. 如仍有网络错误，在 WSL 中手动导出代理变量¶

先在 WSL 中查看 Windows 主机的默认网关地址：

ip route show | grep -i default | awk '{ print $3 }'

假设代理端口为 7890，可在 WSL 中设置：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

如果 127.0.0.1 不通，则改为 Windows 主机 IP：

export HTTP_PROXY=http://<Windows主机IP>:7890
export HTTPS_PROXY=http://<Windows主机IP>:7890

如需长期生效，把上述两行加入 ~/.bashrc，然后执行：

source ~/.bashrc

步骤五：在 WSL 中安装基础开发环境¶

进入 Ubuntu 后执行：

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git build-essential ca-certificates
git --version

步骤六：在 WSL 中安装 Node.js¶

微软对 WSL 的建议是优先使用 nvm 管理 Node.js 版本。

在 WSL 中执行：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
command -v nvm
nvm install --lts
node --version
npm --version

如果你之前已经通过 apt 装过旧版 nodejs/npm，建议先清理后再改用 nvm，避免版本混装。

步骤七：在 WSL 中安装 Claude Code¶

继续在 Ubuntu 中执行：

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

此时先不要急着直接裸跑 claude，下一步应先把它接入智谱 GLM。

步骤八：准备智谱账号与 API Key¶

登录智谱开放平台：

确认账号状态正常
确认已开通 GLM Coding Plan
创建并保存 API Key

步骤九：使用官方 Helper 接入 GLM¶

智谱官方推荐通过 coding-helper 完成安装与配置。

在 WSL 中执行：

npx @z_ai/coding-helper

按提示依次完成：

选择语言
选择编码套餐
输入智谱 API Key
选择 Claude Code
安装或检测依赖
装载套餐配置

如果你想把 Helper 全局安装，方便后续排查，可执行：

npm install -g @z_ai/coding-helper
coding-helper doctor

步骤十：手动配置方式（兜底）¶

如果自动向导没有成功，可按智谱文档在 WSL 中手动配置。

1. 编辑 `~/.claude/settings.json`¶

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的智谱API Key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5-turbo",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.1"
  }
}

若你希望固定为 GLM-5，可将最后一项改为：

"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5"

2. 编辑 `~/.claude.json`¶

{
  "hasCompletedOnboarding": true
}

步骤十一：启动并验证¶

重新打开一个新的 WSL 终端窗口，进入你的项目目录后执行：

claude

如首次提示是否使用当前 API Key，选择 Yes。

进入后执行：

/status

重点确认：

Claude Code 已正常启动
当前模型映射已切换到 GLM
未再出现地区限制或网络错误

常见问题¶

1. `npx @z_ai/coding-helper` 报 `Network Error`¶

优先检查：

Windows 代理是否仍在线
WSL 是否已应用 .wslconfig
HTTP_PROXY 和 HTTPS_PROXY 是否已正确设置
代理端口是否真的对 WSL 可达

2. `claude` 启动后仍无法使用¶