如何在 Windows 环境下通过 WSL 使用 Codex (2026)
在 Windows 上使用 WSL2 设置 OpenAI Codex CLI
Hypereal AI Team开始使用 Hypereal AI 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等模型。免费额度即可起步，可扩展至千万级。
无需信用卡 • 10 万+ 开发者 • 企业级服务
如何在 Windows 上通过 WSL 使用 Codex (2026)
OpenAI Codex CLI 是一款基于终端的 AI 编程助手，它可以阅读你的代码库、编写代码、运行命令以及管理文件——所有这些都在命令行中完成。唯一的限制是：它是为 macOS 和 Linux 设计的。如果你使用的是 Windows，则需要通过 WSL (Windows Subsystem for Linux) 来运行它。
本指南将带你完成从安装 WSL 到在 Windows 机器上运行 Codex 的完整设置过程。
什么是 OpenAI Codex CLI？
Codex CLI 是 OpenAI 推出的用于 AI 辅助软件开发的开源命令行工具。你可以把它看作是一个终端原生的编程智能体，它能够：
- 阅读并理解你的整个项目结构
- 跨多个文件编写、编辑和重构代码
- 运行 Shell 命令并解读输出结果
- 通过阅读日志和堆栈跟踪来调试错误
- 支持任何编程语言
它在本地运行，但使用 OpenAI 的 API（或兼容的端点）作为语言模型后端。
前置条件
| 要求 | 详情 |
|---|---|
| Windows 10 (内部版本 19041+) 或 Windows 11 | WSL2 需要较新版本的 Windows |
| 管理员权限 | 安装 WSL 时需要 |
| OpenAI API key | 在 platform.openai.com 获取 |
| 8+ GB RAM | WSL2 在 Windows 侧运行一个真实的 Linux 内核 |
| 稳定的网络连接 | 调用 OpenAI API 时需要 |
第 1 步：安装 WSL2
如果你尚未安装 WSL2，请以管理员身份打开 PowerShell 并运行：
wsl --install
这会安装 WSL2，并默认使用 Ubuntu 发行版。根据提示重启计算机。
重启后，Ubuntu 终端将自动打开。设置你的 Linux 用户名和密码。
验证 WSL2 是否正在运行
# 在 PowerShell 中运行
wsl --list --verbose
你应该看到类似的内容：
NAME STATE VERSION
* Ubuntu Running 2
如果 VERSION 列显示为 1，请升级到 WSL2：
wsl --set-version Ubuntu 2
第 2 步：设置 Linux 环境
打开你的 WSL 终端（在“开始”菜单中搜索 "Ubuntu"）并更新软件包：
sudo apt update && sudo apt upgrade -y
安装 Node.js
Codex CLI 需要 Node.js 18+。通过 nvm (Node Version Manager) 安装：
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# 重新加载 Shell 配置
source ~/.bashrc
# 安装 Node.js LTS 版本
nvm install --lts
# 验证
node --version # 应显示 v22.x 或更高版本
npm --version
安装 Git（如果尚未安装）
sudo apt install -y git
第 3 步：安装 Codex CLI
通过 npm 全局安装 Codex：
npm install -g @openai/codex
验证安装：
codex --version
第 4 步：配置 API Key
Codex 需要 OpenAI API key 才能工作。将其设置为环境变量：
# 添加到 Shell 配置文件中以便持久化
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
或者，在你的项目目录中创建一个 .env 文件：
echo 'OPENAI_API_KEY=sk-your-api-key-here' > .env
使用不同的 LLM 提供商
Codex 支持任何兼容 OpenAI 的 API。要使用不同的提供商，请设置基础 URL：
# 示例：使用本地 Ollama 实例
export OPENAI_API_KEY="ollama"
export OPENAI_BASE_URL="http://localhost:11434/v1"
# 示例：使用 xAI Grok
export OPENAI_API_KEY="your-xai-key"
export OPENAI_BASE_URL="https://api.x.ai/v1"
第 5 步：访问你的 Windows 文件
WSL 可以通过 /mnt/c/ 访问你的 Windows 文件系统。你的 Windows 项目可以在以下位置找到：
# 导航到 Windows 项目目录
cd /mnt/c/Users/YourUsername/Projects/my-app
# 列出文件
ls -la
为了获得更好的性能，建议直接将代码仓库克隆到 WSL 文件系统中：
# WSL 原生目录（I/O 速度快得多）
cd ~
mkdir projects
cd projects
git clone https://github.com/your-repo/my-app.git
重要提示： 在 /mnt/c/ 上的文件操作明显比在原生 WSL 文件系统 (~/) 上慢。为了让 Codex 获得最佳性能，请在你的 WSL Home 目录中工作。
第 6 步：运行 Codex
导航到你的项目目录并启动 Codex：
cd ~/projects/my-app
# 以交互模式启动 Codex
codex
# 或者直接给它分配一个任务
codex "Add error handling to all the API route handlers in this project"
Codex 自主模式
Codex 有三个自主级别，控制它在未经询问的情况下可以执行的操作范围：
| 模式 | 标志 (Flag) | 它可以做什么 |
|---|---|---|
| 建议 (Suggest) | --suggest |
读取文件，建议更改（默认） |
| 自动编辑 (Auto-edit) | --auto-edit |
读取文件，应用代码更改 |
| 完全自动 (Full auto) | --full-auto |
读取文件，编辑代码，运行命令 |
# 让 Codex 自动更改代码
codex --auto-edit "Refactor this Express app to use TypeScript"
# 让 Codex 同时运行命令（请谨慎使用）
codex --full-auto "Set up ESLint and Prettier for this project, install dependencies, and fix all linting errors"
实际示例
根据错误信息修复 bug：
codex "I'm getting 'TypeError: Cannot read property of undefined' on line 42 of src/utils/parser.ts. Fix it."
为现有代码添加测试：
codex "Write unit tests for all functions in src/services/auth.ts using Jest"
重构组件：
codex "Convert the UserProfile class component in src/components/UserProfile.jsx to a functional component with hooks"
常见问题排查
"codex: command not found"
确保 npm 全局 bin 目录已包含在你的 PATH 中：
# 检查 npm 全局安装包的位置
npm config get prefix
# 如果需要，添加到 PATH
echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
source ~/.bashrc
文件访问缓慢
如果 Codex 在处理 /mnt/c/ 上的文件时很慢，请将项目移动到 WSL 文件系统：
cp -r /mnt/c/Users/YourUsername/Projects/my-app ~/projects/my-app
cd ~/projects/my-app
WSL 内存占用
WSL2 可能会消耗大量内存。在你的 Windows 用户目录下创建一个 .wslconfig 文件来限制内存：
# C:\Users\YourUsername\.wslconfig
[wsl2]
memory=8GB
processors=4
swap=4GB
更改配置后重启 WSL：
# 在 PowerShell 中运行
wsl --shutdown
网络问题 (API 调用失败)
如果 Codex 无法连接到 OpenAI API，请检查 WSL 中的 DNS 设置：
# 检查 DNS 解析是否正常
nslookup api.openai.com
# 如果失败，修复 DNS
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
sudo bash -c 'echo "[network]\ngenerateResolvConf = false" > /etc/wsl.conf'
GUI 应用程序和剪贴板
将 Codex 输出复制到 Windows 剪贴板：
# 将输出通过管道传输到 Windows 剪贴板
codex "explain this function" | clip.exe
# 或者安装 xclip 以实现双向剪贴板
sudo apt install -y xclip
VS Code 集成
为了获得最佳体验，请配合使用 VS Code 和 WSL 扩展：
- 在 VS Code 中安装 "WSL" 扩展
- 在 WSL 终端中使用
code .打开你的 WSL 项目 - VS Code 的集成终端将自动使用 WSL
- 直接在 VS Code 终端中运行 Codex
# 在你的 WSL 项目目录中
code .
# 然后在 VS Code 终端（现在是 WSL 终端）中运行
codex "Add a README with setup instructions for this project"
Codex 与其他 AI 编程工具对比
| 特性 | Codex CLI | Claude Code | Cursor | GitHub Copilot |
|---|---|---|---|---|
| 界面 | 终端 | 终端 | IDE | IDE |
| 文件编辑 | 是 | 是 | 是 | 仅建议 |
| 命令执行 | 是 | 是 | 有限 | 否 |
| WSL 支持 | 通过 WSL | 通过 WSL | 原生 | 原生 |
| 开源 | 是 | 否 | 否 | 否 |
| 模型灵活性 | 任何兼容 OpenAI 的模型 | 仅限 Claude | 多个模型 | 基于 GPT |
| 离线模式 | 否 (需 API) | 否 | 否 | 否 |
| 价格 | 仅 API 费用 | Claude 订阅 | $20+/月 | $10+/月 |
总结
通过 WSL 在 Windows 上运行 Codex 可以获得与 macOS 和 Linux 用户相同的体验。设置过程大约需要 15 分钟，且 WSL2 的集成已经非常成熟，你几乎感觉不到差异。为了获得最佳性能，请将项目文件保存在 WSL 文件系统中，而不是访问 Windows 驱动器。
如果你的项目在代码之外还涉及 AI 生成的媒体，可以查看 Hypereal AI，它提供了一个统一的 API 来处理图像生成、视频、数字人头像等。
免费试用 Hypereal AI —— 提供 35 个积分，无需信用卡。
相关文章
Download Hypereal Agent
Run a local AI media workspace for image generation, video prompts, model selection, credit tracking, and saved artifacts.
