概览

• Windows 用户通过 WSL2 运行 Claude Code 和 Codex 的完整实践指南
• 涵盖 WSL2 安装、Ubuntu 配置、AI 编程代理安装及 VSCode 集成的全流程
• 提供常见问题排查方法，包括默认发行版选错导致的 “apk not found / libstdc++ required” 等典型报错

前言

之前在博客里分享了 Vibe Coding CLI评测： Claude Code vs. OpenAI Codex vs. Gemini CLI，不过那篇教程主要是在 macOS 环境下演示的。后来想了想，大多数小伙伴用的应该是 Windows，而且 Windows 上配置这两个 AI 编程代理确实有一些独特的问题需要解决——比如 WSL 环境设置、VSCode 集成、还有那个容易踩坑的“默认发行版选错导致 apk not found”的报错。

在正式开始之前，先看看官方文档是怎么推荐 Windows 用户安装这些 Vibe Coding 工具的：Claude Code 官方文档⁴明确指出支持 Windows 10+ 系统，推荐三种安装方式（WSL2、Git Bash、原生 Windows），而 OpenAI Codex 官方文档⁵, ⁶则更加直白，在多处强调”为了在 Windows 上获得最佳体验，请在 WSL 工作区中使用 Codex”。综合两个工具的官方建议，WSL2 仍然是最优选择——它不仅同时满足了 Claude Code 和 Codex 的”最佳体验”要求，提供了真正的 Linux 环境和完整的工具链，还能通过 Remote-WSL 扩展实现 VSCode 的无缝集成，避免 PATH 配置、权限管理等 Windows 特有的坑。因此，本文将手把手带你完成 WSL2 + Claude Code + Codex + VSCode 的完整配置流程，这是最符合官方推荐的路径，也是实际使用中最稳定的方案。

这里视频教程：

准备工作

在开始之前，你需要确认几件基本事项：

系统要求

你的 Windows 系统需要满足一定的硬件和软件条件。首先是系统版本，Windows 10 版本 2004 及以上（内部版本 19041 及更高）或 Windows 11 都可以。内存方面至少需要 4GB RAM，不过推荐 8GB 以上，因为 AI 代理本身会占用一些资源，再加上 WSL2 虚拟化开销，内存充足些会流畅很多。网络环境也很重要，你需要稳定的网络连接来下载 WSL 发行版和 AI 工具——你懂的，某些网络环境下这个过程可能会比较折腾，不多说了 (～￣▽￣)～

软件层面，你需要确保 VSCode 已经安装在 Windows 系统中，这是后续连接 WSL 环境的基础。至于 GitHub 账户，如果你需要克隆现成代码库、把项目托管到 GitHub、或者和小伙伴协作，那就建议提前准备一个；但如果你只是想先把环境跑通，其实没有 GitHub 账户也完全不影响本文的主要流程。

Github

注册 GitHub 账户

GitHub 账户是后续使用 Claude Code/Codex 进行项目管理的必备条件，无论是克隆代码库、托管项目，还是和小伙伴协作，都需要用到。注册过程非常简单：

1. 访问 GitHub 官网
2. 点击右上角的 “Sign up” 按钮
3. 填写注册信息：
4. 用户名：建议使用字母、数字和连字符的组合，比如 yourname-dev 或 yourname2025（用户名注册后可修改，但建议一开始就想好一个长期使用的）
5. 邮箱：建议使用常用邮箱，用于账户验证和通知
6. 密码：至少 15 个字符，或至少 8 个字符且包含数字和字母（建议使用密码管理器生成强密码）
7. 完成人机验证（通常是选择匹配图片的简单任务）
8. 验证邮箱：登录你的邮箱，点击 GitHub 发送的验证链接
9. （可选）创建个人仓库：GitHub 会引导你创建第一个仓库，也可以跳过

提示：
– GitHub 提供免费的公开仓库和私有仓库，对于个人学习和项目托管完全够用。对于敏感文档（如国家自然科学基金标书、未发表的论文、项目资料等），务必使用私有仓库以确保数据安全
– 如果你打算使用 GitHub Pages 托管个人网站，建议用户名与你的域名或品牌相关
– 记住你的用户名和邮箱，后续在 WSL 中配置 Git 时会用到

推荐：使用 GitHub Desktop 管理仓库

对于 Windows 用户来说，强烈建议安装 GitHub Desktop——这是 GitHub 官方推出的 Git 图形化管理工具，比命令行操作直观很多，特别适合 Git 新手。

为什么推荐 GitHub Desktop？
– ✅ 可视化操作：不需要记复杂的 Git 命令，通过点击按钮就能完成提交、推送、拉取等操作
– ✅ 分支管理直观：可以清楚地看到当前分支、未提交的更改、冲突文件等
– ✅ 自动处理认证：登录一次后，所有操作都会自动使用你的 GitHub 账户，不需要每次输入密码或配置 SSH key
– ✅ 内置冲突解决：当多人协作修改同一文件时，GitHub Desktop 会提供可视化的冲突解决界面

安装方式：
1. 访问 GitHub Desktop 官网
2. 下载 Windows 版本安装包
3. 运行安装程序，按提示完成安装
4. 首次启动时，使用你的 GitHub 账户登录

使用场景：
– 克隆现有仓库到本地
– 提交更改并推送到 GitHub
– 创建和切换分支
– 查看 commit 历史和文件差异
– 解决合并冲突

工作流建议：
– 日常开发：用 VSCode 写代码，用 GitHub Desktop 管理 Git 操作（提交、推送）
– 命令行备用：当需要高级操作（如 rebase、cherry-pick）时，再使用 WSL 中的 Git 命令行

账户准备：
– Claude Code：需要一个 Claude Pro/Max 订阅，或者 Anthropic Console 的有效计费账户
– Codex：推荐 ChatGPT Plus/Pro/Team/Edu/Enterprise 账户，也可以用 API key（但需要额外配置）

如果以上都准备好了，那就正式开始吧！ヾ(≧▽≦*)o

安装 WSL2

Windows 有两种安装 WSL 的方式：简单命令 和 手动步骤。前者适合大多数用户，后者适合需要精细控制的场景。

快速安装（推荐）

以管理员身份打开 PowerShell，然后运行以下命令：

wsl --install

这条命令会自动完成以下操作：
– 启用 WSL 和虚拟机平台功能
– 下载并安装最新的 Linux 内核
– 将 WSL 2 设置为默认版本
– 下载并安装 Ubuntu Linux 发行版（通常是最新 LTS 版本）

完成后，系统会提示你重启计算机。重启后，WSL 会自动完成 Ubuntu 的初始化，并要求你设置用户名和密码。

手动安装（备选）

如果你希望更精细地控制安装过程，或者需要解决快速安装遇到的问题，可以按以下步骤操作：

启用 WSL 功能

在 PowerShell（管理员）中运行：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

启用虚拟机平台

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重启计算机

Restart-Computer

下载并安装 Linux 内核更新包

访问 Microsoft 的 WSL2 内核更新页面，下载适用于 x64 的 MSI 安装包并安装。

将 WSL 2 设置为默认版本

wsl --set-default-version 2

安装 Ubuntu 发行版

在 PowerShell 中运行：

wsl --install -d Ubuntu

或者从 Microsoft Store 搜索并安装 “Ubuntu”（推荐 Ubuntu 22.04 LTS 或 Ubuntu 24.04 LTS）。

验证 WSL2 安装

安装完成后，打开一个新的终端窗口，运行以下命令验证：

wsl --list --verbose

期望输出类似：

  NAME            STATE           VERSION
* Ubuntu          Running         2

重点确认 VERSION 列显示为 2，且 Ubuntu 前面有星号 *，表示它是默认发行版。

如果 VERSION 是 1，可以手动转换：

wsl --set-version Ubuntu 2

这个转换过程可能需要几分钟，期间 WSL 会显示一个进度窗口。

初始化 Ubuntu

WSL 安装完成后，第一次打开 Ubuntu 终端时，系统会自动初始化，并要求你创建一个用户账户：

Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: yourusername
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
Installation successful!

注意事项：
– 用户名建议全部小写，不要使用空格或特殊字符
– 密码输入时不会显示任何字符（这是 Linux 的安全特性），正常输入即可
– 这个账户是 Ubuntu 的 sudo 用户，具有管理员权限

初始化完成后，你会看到一个类似以下的提示符：

Welcome to Ubuntu 22.04.4 LTS (GNU/Linux 5.15.146.1-microsoft-standard-WSL2 x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

  System information as of Mon Jan 13 12:00:00 UTC 2025

  System load:  0.08              Processes:             11
  Usage of /:   0.5% of 250.98GB  Users logged in:       1
  Memory usage: 3%                IPv4 address for eth0: 172.x.x.x

0 updates can be applied immediately.

Last login: Mon Jan 13 12:00:00 2025 from 172.x.x.x
yourusername@yourcomputername:~$

恭喜！你已经成功进入了一个完整的 Linux 环境。φ(゜▽゜*)♪

设置 Ubuntu 为默认 WSL 发行版

这一步非常关键，尤其是当你的系统上已经安装了 Docker Desktop 时——Docker 会自带 docker-desktop / docker-desktop-data 等 WSL 发行版，如果不手动设置默认，后续操作可能会意外进入 Docker 的内部发行版（而不是 Ubuntu），导致一系列奇怪报错。

在 PowerShell 中运行：

wsl --set-default Ubuntu

验证设置是否成功：

wsl --list --verbose

期望输出：

  NAME                   STATE           VERSION
* Ubuntu                 Running         2
  docker-desktop         Stopped         2
  docker-desktop-data    Stopped         2

重点确认 Ubuntu 前面的星号 * —— 这表示它是默认发行版。

如果 docker-desktop 或 docker-desktop-data 有星号，而 Ubuntu 没有，那就是默认值错误，必须重新运行 wsl --set-default Ubuntu。

在 WSL 中安装 Claude Code

Claude Code 的官方文档提供了多种安装方式，但在 WSL 环境下，最可靠的是通过 curl 的一键脚本安装¹。

安装 Claude Code

在 Ubuntu 终端中运行：

curl -fsSL https://claude.ai/install.sh | bash

这个命令会自动完成以下操作：
– 下载 Claude Code 的最新二进制文件
– 将其安装到 ~/.local/bin/claude
– 添加必要的路径配置

如果你安装后发现 claude 命令找不到，通常是 PATH 没刷新或终端没有重新加载配置，优先按本文后面的“命令找不到”排查即可；一般不建议直接用 sudo 去跑安装脚本。

验证安装

安装完成后，重启终端，或运行以下命令刷新路径：

source ~/.bashrc

然后验证：

claude --version

期望输出（示例）：

claude 1.0.58

认证 Claude Code

第一次运行 claude 时，系统会提示你进行认证²：

mkdir -p ~/coolProjects
cd ~/coolProjects
claude

Claude Code 会打开浏览器，让你选择认证方式：

推荐方式：使用 Claude Pro 或 Max 订阅账户登录
– 优点：统一管理 Claude Code 和 Claude Web 的订阅
– 路径：claude.ai 账户直接登录

备选方式：使用 Claude Console（Anthropic Console）
– 前提：Anthropic Console 已启用计费
– 特点：自动创建 “Claude Code” 工作区，用于使用追踪和成本管理
– 限制：无法为该工作区创建 API key

认证成功后，你就可以在终端中与 Claude Code 交互了：

✓ Connected to Claude

I'm ready to help! What would you like me to do?

在 WSL 中安装 Codex

Codex CLI 的安装相对简单，官方支持 npm 和 Homebrew 两种方式³。

前置条件：安装 Node.js

Codex 推荐通过 npm 安装，因此需要先安装 Node.js。

在 Ubuntu 终端中运行：

sudo apt update
sudo apt install -y nodejs npm

验证安装：

node --version
npm --version

期望输出（示例）：

v18.19.0
9.2.0

Codex CLI 的 npm 包要求 Node.js 版本至少为 16+（更高版本更省心）。

如果版本过低（Ubuntu 默认源可能提供较旧版本），可以使用 NodeSource 的最新版本：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

安装 Codex CLI

使用 npm 全局安装：

npm install -g @openai/codex

如果你用 apt / NodeSource 安装的 npm，这里偶尔会遇到 EACCES 权限报错：最推荐的解决方式是改用 nvm 安装 Node；图省事也可以用 sudo npm install -g @openai/codex（不太优雅，但能跑）。

或者使用 Homebrew（如果你更习惯这个包管理器）：（WSL 上一般直接用 npm 更省事；Homebrew 主要是 macOS 用户常用，WSL 上除非你已经装了 Homebrew，否则可以跳过这段。）

# 如果没有 Homebrew，先安装它
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 然后安装 Codex
brew install --cask codex

验证安装

codex --version

期望输出（示例）：

codex 0.80.0

认证 Codex

第一次运行 codex 时，系统会提示你认证³：

codex

Codex 会打开浏览器，推荐你使用 ChatGPT 账户登录（Plus/Pro/Team/Edu/Enterprise 计划）。

备选方式：使用 API key 认证
– 前提：在 OpenAI Platform 创建 API key
– 限制：需要额外配置，且计费方式不同

认证成功后，你就可以在终端中与 Codex 交互了：

✓ Connected to Codex

I'm ready to help! What would you like me to do?

让 VSCode 对接 WSL

现在你已经有了：
– ✅ WSL2 + Ubuntu 环境
– ✅ Claude Code 已安装并认证
– ✅ Codex CLI 已安装并认证

接下来的一步，就是让 VSCode 能够无缝连接到 WSL，并在其中使用这两个 AI 编程代理。

架构说明：VSCode 安装在哪里？

重要理解：VSCode 本身安装在 Windows 宿主系统中，但通过 Remote-WSL 扩展，它可以无缝连接到 WSL 环境。

┌─────────────────┐         ┌──────────────────┐
│  Windows 宿主   │  通信   │   WSL2 Ubuntu    │
│                 │◄────────┤                  │
│  VSCode 客户端  │         │  VSCode Server   │
│  (UI/界面)      │         │  (执行/终端)     │
└─────────────────┘         └──────────────────┘

工作原理：
– VSCode 客户端（Windows）：提供编辑器界面、扩展面板、调试器等图形组件
– VSCode Server（WSL）：执行文件操作、运行终端命令、加载语言服务
– Remote-WSL 扩展：两者之间的桥梁，负责通信协调

好处：
– ✅ 享受 Windows 原生的图形性能和渲染
– ✅ 同时获得 Linux 完整工具链和命令行环境
– ✅ 无需在 WSL 中配置 X Server 或其他图形转发方案
– ✅ 文件直接在 Linux 文件系统中操作，避免跨文件系统性能损失

这正是为什么本文要求你在 Windows 中安装 VSCode，而不是在 WSL 里——Remote-WSL 扩展专门为这种架构设计，是官方推荐的 WSL 开发方式。

安装 VSCode 的 WSL 扩展

在 VSCode 中，按下 Ctrl+Shift+X 打开扩展面板，搜索并安装以下扩展：

• WSL（官方扩展，作者：Microsoft）
• 扩展 ID：ms-vscode-remote.remote-wsl
• 功能：在 VSCode 中连接到 WSL 发行版

安装提示：
– 直接点击 “Install” 按钮即可
– 安装后可能需要重新加载 VSCode 窗口

连接到 WSL

在 VSCode 中连接 WSL 有两种方式：

通过命令面板

1. 按 F1 或 Ctrl+Shift+P 打开命令面板
2. 输入 WSL
3. 选择 “WSL: Connect to WSL using Distro”
4. 选择 Ubuntu

通过左下角按钮

1. 点击 VSCode 窗口左下角的远程连接图标（通常是一个绿色的图标，显示类似 >< 的符号）
2. 在弹出菜单中选择 “Connect to WSL using Distro”
3. 选择 Ubuntu

验证连接成功

连接成功后，你会看到以下变化：

1. 左下角状态栏 显示：WSL: Ubuntu
2. 集成终端 自动切换到 WSL 的 Bash 环境
3. 文件资源管理器 显示的是 WSL 中的文件系统（比如 /home/yourusername/）

在集成终端中运行：

pwd
ls

期望输出：

/home/yourusername
coolProjects  ...

在 WSL 中使用 Claude Code 和 Codex

现在，在 VSCode 的集成终端中，你可以直接运行 Claude Code 和 Codex：

运行 Claude Code：

cd ~/coolProjects/yourproject
claude

运行 Codex：

cd ~/coolProjects/yourproject
codex

更简洁的方式：直接在终端输入提示词：

claude "帮我重构这个函数"
codex "修复 CI 失败的问题"

实践与验证

为了确保一切正常工作，让我们做一个简单的测试。

创建一个测试项目

在 WSL 终端中运行：

cd ~/coolProjects
mkdir test-ai-agent
cd test-ai-agent
echo 'print("Hello from WSL!")' > hello.py

在 VSCode 中打开项目

在 VSCode 中：
1. 按 Ctrl+Shift+P 打开命令面板
2. 输入 WSL: Reopen Folder in WSL
3. VSCode 会重新以 WSL 模式打开当前项目

验证左下角状态栏：应该显示 WSL: Ubuntu

测试 Claude Code

在集成终端中运行：

claude "请解释 hello.py 的功能"

Claude Code 应该能够：
– 读取 hello.py 文件
– 解释代码的功能
– 一般会按你的提问语言回复（比如你用中文问，它就用中文答）

测试 Codex

在集成终端中运行：

codex "请将 hello.py 改写为 JavaScript 版本"

Codex 应该能够：
– 读取 hello.py 文件
– 生成等价的 JavaScript 代码（是否自动落盘为 hello.js 取决于你的批准模式/确认操作）

如果以上两个测试都通过了，恭喜你！(≧∇≦)/

你已经成功搭建了一个完整的 Windows + WSL + VSCode + Claude Code + Codex 的开发环境！

常见问题排查

默认发行版选错导致的 “apk not found / libstdc++ required” 提示

症状：

/bin/sh: eval: line 1: apk: not found
Error: libstdc++ required

原因：
– 某些情况下安装/更新 Docker Desktop 后，默认 WSL 发行版会被切到 docker-desktop / docker-desktop-data
– Claude Code/Codex 实际跑在了 Docker 的内部发行版（比如 docker-desktop / docker-desktop-data），而不是 Ubuntu

解决方案：

在 PowerShell 中运行：

wsl --list --verbose

检查 docker-desktop / docker-desktop-data 是否有星号 *。如果有，运行：

wsl --set-default Ubuntu

然后重新打开 VSCode，确保连接到 Ubuntu 而不是 docker-desktop / docker-desktop-data。

Claude Code 或 Codex 命令找不到

症状：

bash: claude: command not found
bash: codex: command not found

原因：
– 二进制文件未正确添加到 PATH
– 终端未重新加载配置

解决方案：

手动添加路径到 ~/.bashrc（Claude Code 一般会装到 ~/.local/bin）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

如果你是通过 npm 安装的 Codex，建议再确认一下它的全局 bin 目录（通常会是 $(npm bin -g)），必要时把它也加到 PATH。

然后验证：

which claude
which codex

期望输出：能看到两个命令各自的绝对路径即可。

例如：

/home/yourusername/.local/bin/claude
/usr/local/bin/codex

VSCode 无法连接到 WSL

症状：

Connecting to WSL...
Error: The VS Code Server failed to start.

原因：
– WSL 服务未运行
– 网络连接问题
– 防火墙或安全软件阻止

解决方案：

在 PowerShell 中重启 WSL：

wsl --shutdown
wsl

然后在 VSCode 中重新连接到 WSL。

Claude Code 或 Codex 认证失败

症状：

Error: Authentication failed

原因：
– 网络问题（无法访问 Anthropic/OpenAI 服务器）
– 账户未订阅相应的服务
– 浏览器弹窗被阻止

解决方案：

1. 检查网络连接，确保可以访问 claude.ai 和 openai.com
2. 确认账户已订阅 Claude Pro/Max 或 ChatGPT Plus/Pro
3. 尝试手动打开认证链接，而不是依赖自动弹窗

小结

通过以上流程，你现在应该已经在 Windows 上成功搭建了一个完整的 AI 编程代理开发环境：

• WSL2 提供了一个高性能的 Linux 子系统
• Ubuntu 作为主要的开发环境，支持完整的 Linux 工具链
• Claude Code 和 Codex 都可以在这个环境中流畅运行
• VSCode 通过 Remote-WSL 扩展实现了无缝对接

整个配置的核心要点：
1. 必须将 Ubuntu 设置为默认 WSL 发行版（尤其是安装了 Docker Desktop 时）
2. Claude Code 和 Codex 都需要认证，推荐使用订阅账户而非 API key
3. VSCode 的 WSL 扩展是连接 Windows 和 Linux 环境的桥梁

接下来，你就可以在 VSCode 中愉快地使用这两个 AI 编程代理了——无论是代码解释、重构、还是生成测试用例，它们都能大幅提升你的开发效率。

如果你在配置过程中遇到其他问题，欢迎在评论区留言，或者查阅官方文档¹, ³。

参考文献

1. Anthropic – Claude Code Docs – Set up Claude Code. https://code.claude.com/docs/en/setup
2. Reddit – How to use Claude Code in Vs Code in Windows via WSL. https://www.reddit.com/r/ClaudeAI/comments/1kv4mfx/how_to_use_claude_code_in_vs_code_in_windows_via/
3. OpenAI – Codex CLI Documentation. https://developers.openai.com/codex/cli/
4. Claude Code – Set up Claude Code – System Requirements. https://code.claude.com/docs/en/setup
5. OpenAI – Codex CLI Documentation. https://developers.openai.com/codex/cli/
6. OpenAI – Codex IDE Extension Documentation. https://developers.openai.com/codex/ide/