技术文档

主题

Windows 使用指南 ​

Codex 对 Windows 的支持仍处于早期阶段，但正在快速改进。

在 Windows 上使用 Codex 最简单的方式是设置 IDE 扩展，或安装 CLI 并从 PowerShell 运行。

在 Windows 上原生运行时，Codex 支持强大的 Agent 模式，可以读取文件、写入文件，并在工作文件夹中运行命令。Agent 模式使用实验性 Windows 沙箱来限制工作文件夹外的文件系统访问，以及在没有你明确批准的情况下阻止网络访问。如果你对风险感到舒适，可以使用它。详见下文。

或者，你可以安装和使用 Windows Subsystem for Linux (WSL2)。WSL2 为你提供 Linux shell、unix 风格的语义和工具，这与我们模型在训练中看到的大多数任务相匹配。重要的是，Linux 上的 Codex 沙箱实现是成熟的。

使用 WSL 的 VS Code ​

从 WSL 内部启动 VS Code ​

详细步骤请参考官方 VS Code WSL 教程。

先决条件 ​

  • Windows 10 版本 1903+ 或 Windows 11
  • 已安装 WSL2
  • 已安装 VS Code

从 WSL 终端打开 VS Code ​

bash
# 从你的 WSL shell
cd ~/code/your-project
code .

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

确认已连接到 WSL ​

  • 检查 VS Code 左下角的远程指示器
  • 应该显示 "WSL: Ubuntu"（或你的发行版名称）

在 WSL 中使用 Codex CLI ​

在提升权限的 PowerShell 或 Windows Terminal 中运行这些命令：

powershell
# 安装默认 Linux 发行版（如 Ubuntu）
wsl --install

# 在 Windows Subsystem for Linux 内启动 shell
wsl

# https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
# 在 WSL 中安装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# 在新标签页中或退出并再次运行 `wsl` 后安装 Node.js
nvm install 22

# 在 WSL 中安装和运行 Codex
npm i -g @openai/codex
codex

在 WSL 内处理代码 ​

  • 将项目存储在 WSL 文件系统中（~/ 下）以获得最佳性能
  • 避免从 /mnt/c/ 访问 Windows 文件，这会很慢
  • 使用 code . 从 WSL 打开 VS Code

IDE 扩展配置 ​

如果你在 Windows 上使用 Codex IDE 扩展，直接支持 WSL——在 VS Code 设置中设置以下内容，以便在 WSL 可用时将代理保持在 WSL 内：

json
{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

这确保 IDE 扩展继承 Linux 沙箱语义用于命令、审批和文件系统访问，即使主机操作系统是 Windows。

故障排除和常见问题 ​

已安装扩展但无响应 ​

你的系统可能缺少 C++ 开发工具，某些原生依赖需要它们：

  1. 安装 Visual Studio Build Tools
  2. 选择 "Desktop development with C++" 工作负载
  3. 安装后完全重启 VS Code

大型仓库感觉很慢 ​

  • 确保项目在 WSL 文件系统中（~/ 下）
  • 避免跨文件系统边界（/mnt/c/）
  • 考虑使用 .gitignore 排除大型生成的目录

WSL 中的 VS Code 找不到 codex ​

验证二进制文件存在且在 WSL 内的 PATH 中：

bash
which codex || echo "codex not found"

如果找不到二进制文件，尝试按照本指南前面的说明安装。

网络问题 ​

如果在 WSL 中遇到网络问题：

bash
# 检查 DNS 解析
cat /etc/resolv.conf

# 如果需要，重新生成 resolv.conf
sudo rm /etc/resolv.conf
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'

权限问题 ​

如果遇到权限错误：

bash
# 修复 npm 全局安装权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

原生 Windows 支持（实验性） ​

Codex 也支持在 Windows 上原生运行，使用实验性 Windows 沙箱。要启用：

toml
# ~/.codex/config.toml
[features]
enable_experimental_windows_sandbox = true

警告

Windows 原生沙箱仍处于实验阶段。对于生产使用，我们建议使用 WSL。

推荐设置 ​

对于最佳的 Windows 体验，我们推荐：

  1. 使用 WSL2 — 提供最稳定的沙箱和最佳兼容性
  2. 安装 Windows Terminal — 更好的终端体验
  3. 使用 VS Code Remote - WSL — 无缝的 IDE 集成
  4. 将项目存储在 WSL 中 — 避免跨文件系统性能问题

aicodex 文档网站

Copyright © 2025