在 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 和編輯器必須在同一套執行邊界裡。