如何在 Windows 环境下通过 WSL 使用 Codex (2026)

如何在 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 个积分，无需信用卡。

如何在 Windows 上通过 WSL 使用 Codex (2026)

本指南将带你完成从安装 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+/月

总结

如果你的项目在代码之外还涉及 AI 生成的媒体，可以查看 Hypereal AI，它提供了一个统一的 API 来处理图像生成、视频、数字人头像等。

免费试用 Hypereal AI —— 提供 35 个积分，无需信用卡。

开始使用 Hypereal 构建

如何在 Windows 上通过 WSL 使用 Codex (2026)

什么是 OpenAI Codex CLI？

前置条件

第 1 步：安装 WSL2

验证 WSL2 是否正在运行

第 2 步：设置 Linux 环境

安装 Node.js

安装 Git（如果尚未安装）

第 3 步：安装 Codex CLI

第 4 步：配置 API Key

使用不同的 LLM 提供商

第 5 步：访问你的 Windows 文件

第 6 步：运行 Codex

Codex 自主模式

实际示例

常见问题排查

"codex: command not found"

文件访问缓慢

WSL 内存占用

网络问题 (API 调用失败)

GUI 应用程序和剪贴板

VS Code 集成

Codex 与其他 AI 编程工具对比

总结

相关文章

如何从零开始构建 MCP Server (2026)

Claude Code 入门指南与最佳实践 (2026)

如何使用 Claude Code 编写更好的代码 (2026)

立即开始构建

开始使用 Hypereal 构建

如何在 Windows 上通过 WSL 使用 Codex (2026)

什么是 OpenAI Codex CLI？

前置条件

第 1 步：安装 WSL2

验证 WSL2 是否正在运行

第 2 步：设置 Linux 环境

安装 Node.js

安装 Git（如果尚未安装）

第 3 步：安装 Codex CLI

第 4 步：配置 API Key

使用不同的 LLM 提供商

第 5 步：访问你的 Windows 文件

第 6 步：运行 Codex

Codex 自主模式

实际示例

常见问题排查

"codex: command not found"

文件访问缓慢

WSL 内存占用

网络问题 (API 调用失败)

GUI 应用程序和剪贴板

VS Code 集成

Codex 与其他 AI 编程工具对比

总结

相关文章

如何从零开始构建 MCP Server (2026)

Claude Code 入门指南与最佳实践 (2026)

如何使用 Claude Code 编写更好的代码 (2026)

立即开始构建