在 Windows 上使用 Codex

Windows 上使用 Codex，核心不是“装哪个入口”，而是先决定代码和工具链在哪里运行：native Windows 还是 WSL2。运行位置决定 sandbox、路径、终端、依赖和排错方式。

先选运行环境

flowchart TD
    Start["Windows 上使用 Codex"]
    Native{"项目主要在 Windows 工具链?"}
    Linux{"项目主要在 Linux 工具链?"}
    NativeRun["Native Windows<br/>App / CLI / IDE"]
    WSL["WSL2<br/>Linux filesystem + Linux tools"]
    Decide["先整理项目位置和工具链"]

    Start --> Native
    Native -->|是| NativeRun
    Native -->|否| Linux
    Linux -->|是| WSL
    Linux -->|否| Decide

Native Windows 适合：

• 项目工具链本来在 Windows。
• 需要 Windows 原生应用或路径。
• 企业机器要求保留 Windows-native workflow。

WSL2 适合：

• 项目依赖 Linux tooling。
• 主要用 VS Code Remote WSL。
• 代码放在 Linux filesystem。
• native sandbox 或企业策略不满足当前需求。

Native Windows 的关注点

Native Windows 运行时重点看：

• Windows sandbox 是否可用。
• 当前用户权限是否允许 setup。
• 企业策略是否阻止本地用户、组或 firewall 设置。
• 终端是否支持需要的交互能力。
• 路径是否是 Windows 路径。

不要为了绕过 sandbox 问题直接开 full access。先看官方 Windows setup 和 agent approvals / security。

WSL2 的关注点

WSL2 运行时重点看：

• 项目是否放在 WSL home 目录，而不是 /mnt/c/...。
• Node、包管理器和 Codex CLI 是否装在 WSL 内。
• VS Code 是否真正连接到 WSL。
• integrated terminal 是否显示 Linux 路径。
• Git、依赖、测试命令是否都在同一个 Linux 环境。

推荐项目位置：

mkdir -p ~/code
cd ~/code
git clone <your-repo>

从 WSL shell 打开 VS Code：

code .

App、CLI、IDE 怎么选

App：

• 适合桌面任务管理、threads、diff review、worktrees。
• 适合不想只在终端里工作的用户。

CLI：

• 适合终端、SSH、脚本和自动化。
• 在 WSL2 中使用时，确保 Codex 和项目都在 WSL2。

IDE extension：

• 适合编辑器内开发。
• 在 VS Code + WSL 场景下，要确认 extension 运行在正确 remote context。

入口不是关键，运行位置才是关键。

常见排错

Sandbox setup failed：

• 检查是否有管理员批准。
• 检查企业策略是否允许本地 sandbox setup。
• 确认当前入口是 native Windows 还是 WSL2。
• 必要时让 IT 协助，而不是放弃 sandbox。

路径找不到：

• Windows 路径和 WSL 路径不要混用。
• native Windows 常见是 C:\...。
• WSL 常见是 /home/...。
• Windows Explorer 访问 WSL 通常走 \\wsl$。

命令不能联网：

• 先看 sandbox 和 approval。
• 再看企业防火墙、代理和证书。
• 不要把网络失败直接归因于 Codex。

VS Code 没进 WSL：

• 看状态栏是否显示 WSL。
• 看 terminal 路径是否是 Linux。
• 必要时使用 “Reopen Folder in WSL”。

安全建议

• 默认保留 sandbox。
• 企业机器优先按 IT 策略完成 setup。
• 需要额外目录时明确添加，不要放开全盘。
• 凭据走系统 secret store 或环境变量。
• 不把 API key、token、auth.json 复制进项目。
• WSL 和 Windows 环境分别管理依赖，避免路径混乱。

Windows 上用 Codex 的关键是环境一致性：代码、终端、依赖、sandbox 和编辑器必须在同一套运行边界里。