WSL

WSL

Windows WSL2 使用 Codex CLI 指南：配置 WSL 环境、安装运行 Codex，从 WSL shell 启动 VS Code 并确认远程窗口；说明把仓库放在 Linux 文件系统的优势，提供 Git、Node.js、依赖和网络排查步骤，解决仓库缓慢、VS Code 找不到 codex 等常见问题。

WSL#

Codex 中文站说明： 本页围绕“WSL”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

在 Windows Subsystem for Linux 中运行并排查 Codex

使用 WSL2 时，Codex 在 Linux 环境中运行，而不是使用原生 Windows 沙箱。如果你需要 Linux 原生工具链、仓库和开发流程本来就在 WSL2 中，或者两种原生 Windows 沙箱模式都不适合当前环境，请选择 WSL2。

Codex 0.114 及更早版本支持 WSL1。从 Codex 0.115 开始，Linux 沙箱改用 bubblewrap，因此不再支持 WSL1。

从 WSL 内启动 VS Code#

分步说明请参阅 VS Code 官方 WSL 教程。

前置条件#

  • Windows 已安装 WSL。安装时，以管理员身份打开 PowerShell 并运行 wsl --install，通常可选择 Ubuntu。
  • VS Code 已安装 WSL 扩展。

从 WSL 终端打开 VS Code#

bash
# From your WSL shell
cd ~/code/your-project
code .

这会打开 WSL 远程窗口，在需要时安装 VS Code Server，并确保集成终端在 Linux 中运行。

确认已连接 WSL#

  • 查看绿色状态栏中是否显示 WSL: 。
  • 集成终端应显示 /home/... 之类的 Linux 路径，而不是 C:\。
  • 也可以运行：
bash
echo $WSL_DISTRO_NAME

命令会输出当前发行版名称。

如果状态栏没有显示 WSL: ...，按 Ctrl+Shift+P，选择 WSL: Reopen Folder in WSL。为获得最佳性能，应把仓库放在 /home/... 下，而不是 C:\。

如果 Windows 版 App 或项目选择器没有显示 WSL 仓库，请在文件选择器或资源管理器中输入 \\wsl$，再进入对应发行版的主目录。

在 WSL 中使用 Codex CLI#

在以管理员身份运行的 PowerShell 或 Windows Terminal 中执行：

powershell
# Install default Linux distribution (like Ubuntu)
wsl --install

# Start a shell inside Windows Subsystem for Linux
wsl

随后在 WSL shell 中运行：

bash
# Install and run Codex in WSL
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

在 WSL 中处理代码#

  • 在 /mnt/c/... 等 Windows 挂载路径中工作，通常比使用 WSL 原生路径更慢。把仓库放在 Linux 主目录下，例如 ~/code/my-app，可以获得更快的 I/O，并减少符号链接和权限问题：
bash
mkdir -p ~/code && cd ~/code
git clone https://github.com/your/repo.git
cd repo
  • 如果需要从 Windows 访问文件，可在资源管理器中打开 \wsl$\Ubuntu\home<user>。

故障排查与常见问题#

大型仓库在 WSL 中很慢#

  • 确认仓库不在 /mnt/c 下，把它移到 WSL 内，例如 ~/code/...。
  • 必要时为 WSL 增加内存和 CPU，并更新到最新版本：
powershell
wsl --update
wsl --shutdown

WSL 中的 VS Code 找不到 codex#

确认二进制文件存在，并且位于 WSL 的 PATH 中：

bash
which codex || echo "codex not found"

如果找不到，请按照在 WSL 中使用 Codex CLI重新安装。

本站实践建议#

验证“WSL”时，请记录操作系统、终端、Codex 版本和项目路径。环境差异往往比配置文本本身更容易造成行为不一致。

Codex API 与国内使用#

在实践“WSL”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。