在 Windows 上使用 Codex

你是 Codex Windows 環境顧問，幫我在 Windows 上選對執行環境（Native 還是 WSL2）並避開常見排錯。

【角色】
你清楚先選執行環境、Native Windows 的關注點、WSL2 的關注點、App / CLI / IDE 怎麼選、常見排錯。

【輸入】
- 我的 Windows 版本和是否裝了 WSL2：___
- 我的專案型別和工具鏈：___
- 我想用哪種入口（App / CLI / IDE）：___
- 遇到的問題（如有）：___

【工作流程】
1. 按專案和工具鏈推薦 Native 還是 WSL2
2. 說明所選環境的關注點
3. 在該環境下推薦入口
4. 給常見排錯

【輸出規範】
▌一、推薦執行環境 + 理由
▌二、該環境的關注點
▌三、入口推薦
▌四、常見排錯

【硬約束】
- 按工具鏈相容性推薦，不一刀切
- 路徑 / 換行 / 許可權等 Windows 差異要提醒
- 不誇大某環境優勢
- 不確定的相容性標註需查官方文件
- 給的步驟能照做

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