Codex Windows 安裝與排錯：原生 PowerShell、WSL、沙箱許可權和路徑問題

Codex 在 Windows 上最常見的問題往往不是模型能力，而是執行環境：命令到底裝在 Windows 還是 WSL、倉庫路徑屬於哪個檔案系統、Git 使用哪套憑據、終端繼承了哪些環境變數，以及沙箱允許寫入哪裡。原生 PowerShell 和 WSL 都能成為可用入口，但不要在同一個任務中隨意混用兩套 Node、Git、Python 和路徑。本文先幫助你選擇路線，再分別完成安裝、登入、倉庫驗證和故障定位。 Codex 的安裝方式、模型和具體審批介面可能繼續更新。文中的診斷原則可以長期複用，安裝命令則應與 OpenAI Codex 官方文件當前頁面核對。

先選原生 Windows 還是 WSL

原生 PowerShell 更適合：

專案本來就在 C:\Work 等 Windows 目錄；
依賴 Visual Studio、MSBuild、PowerShell 或 Windows SDK；
測試必須呼叫 Windows 程式；
團隊命令和部署指令碼以 PowerShell 為主。 WSL 更適合：
專案生產環境是 Linux；
依賴 Bash、GNU 工具、Docker Linux 工作流；
包含對大小寫、許可權位或符號連結敏感的程式碼；
團隊 README 主要提供 Linux 命令。選擇原則很簡單：讓 Codex 與專案主要工具鏈處在同一環境。不要因為某條命令在 WSL 更短，就把 Windows 倉庫、Windows Node 和 WSL Git 混在一次任務裡。

盤點電腦上已有的兩套環境

在 PowerShell 檢查：

1
2
3
4
5
6


Get-Command codex -ErrorAction SilentlyContinue
Get-Command node -ErrorAction SilentlyContinue
Get-Command git -ErrorAction SilentlyContinue
codex --version
node --version
git --version

再進入 WSL：

1
2
3


wsl --status
wsl --list --verbose
wsl

在 WSL 內執行：

1
2
3
4
5
6


command -v codex
command -v node
command -v git
codex --version
node --version
git --version

兩邊輸出不同並不是錯誤，它們本來就是獨立環境。問題出在使用者以為升級了一個，實際執行的卻是另一個。

原生 PowerShell 安裝前的準備

先確認 64 位 PowerShell 和 Node 可用：

1
2
3
4


$PSVersionTable
[Environment]::Is64BitProcess
node --version
npm --version

如果使用 npm 安裝 Codex，執行官方當前安裝命令。常見形式是：

1

npm install -g @openai/codex

安裝後：

1
2
3


Get-Command codex
codex --version
codex --help

如果官方已經提供 Windows 安裝器或其他推薦方式，優先採用官方最新說明。不要同時用 npm、獨立二進位制和多個包管理器安裝三份 Codex。檢視命令解析到的真實路徑：

1
2


(Get-Command codex).Source
npm config get prefix

原生登入與憑據

啟動登入：

1

codex login

瀏覽器登入完成後，回到同一 Windows 使用者的終端驗證。不要用管理員 PowerShell 登入，再用普通使用者執行；兩者的使用者目錄和憑據可能不同。如果使用 API Key，按官方支援方式設定。臨時環境變數只在當前程序及其子程序生效：

1
2


$env:OPENAI_API_KEY = '<temporary-key>'
codex

不要把真實 Key寫進 PowerShell Profile、倉庫指令碼或命令歷史。測試結束後關閉終端，必要時撤銷該 Key。登入失敗時先確認系統時間、瀏覽器回撥、防火牆和代理，不要反覆刪除整個配置目錄。

在原生 Windows 開啟倉庫

使用絕對路徑：

1
2
3
4


Set-Location -LiteralPath 'C:\Work\my-project'
git rev-parse --show-toplevel
git status --short
codex

路徑包含空格時，-LiteralPath 比手工轉義更穩妥。啟動後先讓 Codex 執行只讀檢查：

1

报告当前工作目录、Git 分支和未提交文件，不要修改文件。

它回報的路徑必須與 git rev-parse --show-toplevel 一致。若錯誤，退出會話，在正確目錄重新啟動。

WSL 安裝的正確位置

在 PowerShell 進入指定發行版：

1

wsl -d Ubuntu

在 WSL 中安裝 Node 和 Codex。不要呼叫 /mnt/c/Program Files/nodejs/npm.cmd 來假裝完成 Linux 安裝。驗證全部命令來自 Linux 路徑：

1
2
3
4


which node
which npm
which codex
file "$(which codex)"

再執行官方安裝命令和登入：

1
2


npm install -g @openai/codex
codex login

WSL 的登入狀態通常與 Windows 原生狀態分開。即使同一瀏覽器賬戶完成授權，也要在目標環境單獨驗證。

WSL 倉庫放在 /home 還是 /mnt/c

Linux 工具鏈專案優先放在 WSL 自己的檔案系統，例如：

1
2
3
4
5


mkdir -p ~/src
cd ~/src
git clone https://github.com/example/project.git
cd project
codex

/mnt/c/Work/project 便於 Windows 程式直接訪問，但大量小檔案、許可權位、符號連結、檔案監聽和大小寫行為可能不同。如果專案必須同時被 Visual Studio 和 WSL 使用，可以留在 Windows 盤，但應測試：

npm/pnpm 安裝速度；
Git 檔案許可權變化；
Watcher 是否漏事件；
符號連結是否建立成功；
測試是否依賴大小寫；
Docker bind mount 效能。不要從 Windows 和 WSL 同時執行兩個格式化器修改同一工作樹。

Windows 路徑與 WSL 路徑互換

PowerShell 路徑：

1

C:\Work\my-project

在 WSL 中通常對應：

1

/mnt/c/Work/my-project

使用 wslpath 轉換比字串替換可靠：

1
2


wslpath 'C:\Work\my-project'
wslpath -w /home/user/src/project

不要把 C:\... 路徑直接傳給 Linux 原生命令，也不要把 /home/... 傳給普通 Windows 程式並期待它自動識別。 Codex 工具呼叫中的路徑必須屬於啟動它的環境。

Git 憑據為何一邊能拉取、一邊不能

PowerShell 的 Git 可能使用 Git Credential Manager；WSL Git 可能使用 SSH Agent、Linux Credential Store 或沒有配置任何 Helper。 Windows 檢查：

1
2


git config --show-origin --get-all credential.helper
git remote -v

WSL 檢查：

1
2
3


git config --show-origin --get-all credential.helper
git remote -v
ssh -T [email protected]

不要為了修復 WSL 拉取失敗而把 Personal Access Token寫進 Remote URL。它會出現在 .git/config、日誌和程序引數中。更穩妥的方法是在選定環境配置 GitHub CLI、SSH Key 或受支援的 Credential Helper。

CRLF 與“所有檔案都被修改”

Windows 常用 CRLF，Linux 常用 LF。如果 .gitattributes 不明確，跨環境切換可能讓 Git認為大量檔案變化。先看：

1
2
3


git status --short
git diff --numstat
git config --show-origin --get core.autocrlf

倉庫應透過 .gitattributes 宣告策略，例如：

1
2
3


* text=auto
*.sh text eol=lf
*.ps1 text eol=crlf

實際規則要與團隊一致。不要在有使用者未提交改動時執行批次重新規範化命令。如果 Codex 剛啟動就看到幾百個變化，先停止寫入，確認是換行、許可權位還是生成檔案，而不是讓 Agent繼續“修復”。

PowerShell 引號與 Bash 引號不同

PowerShell 中單引號不展開變數，雙引號會展開：

1
2
3


$name = 'demo'
Write-Output '$name'
Write-Output "$name"

Bash 的規則相似但並不完全相同，管道物件模型也不同。容易出錯的內容包括：

JSON 中的雙引號；
正規表示式中的 $；
Git 提交資訊中的反引號；
帶空格的路徑；
原生命令引數與 PowerShell 引數繫結；
curl 在舊 PowerShell 中可能是別名。讓 Codex 編寫命令時明確說明目標 Shell，例如“在 PowerShell 7 中執行”，不要只說“Windows 命令”。

沙箱與審批不是 Windows UAC

Codex 的沙箱決定本次 Agent 可以讀取、寫入或執行哪些內容；Windows UAC 和 NTFS ACL 決定作業系統層面許可權。兩者是不同層次。即使程式以管理員身份執行，Codex 仍可能按沙箱策略拒絕某些寫入。相反，沙箱允許執行的命令也不能突破 NTFS 許可權。啟動任務前確認：

工作區根目錄是否正確；
是否只允許寫入倉庫；
網路訪問是否必要；
命令執行是否需要審批；
使用者配置目錄是否在範圍外；
是否會觸碰其他掛載盤。不要為了省去一次提示就永久使用最高許可權模式。高許可權應對應清晰任務和可驗證目標。

“Access denied” 的分層排查

先取得完整錯誤路徑，不要只看最後一句。檢查檔案屬性與 ACL：

1
2


Get-Item -LiteralPath '.\target-file'
Get-Acl -LiteralPath '.\target-file' | Format-List

檢查是否被其他程序佔用：

1

Get-Process | Where-Object { $_.ProcessName -match 'node|python|dotnet|code' }

再判斷是：

Codex 沙箱範圍；
Windows 檔案許可權；
檔案只讀屬性；
防病毒軟體攔截；
檔案鎖；
路徑過長或字元問題；
WSL 掛載許可權對映。不要直接關閉 Defender 或給整個磁碟 Everyone Full Control。

Node、Python 和包管理器衝突

Windows 可能同時存在 winget Node、nvm-windows、Volta 和專案內工具；WSL 又有一套 nvm 或系統 Node。記錄真實解析路徑：

1

Get-Command node,pnpm,python,pip | Select-Object Name,Source

WSL：

1

type -a node pnpm python3 pip3

在讓 Codex 安裝依賴前，閱讀倉庫的 packageManager、鎖檔案、.nvmrc、.python-version 或工具配置。同時出現 package-lock.json、pnpm-lock.yaml 和 yarn.lock 時，不要讓 Agent猜測包管理器，應先查專案文件和 Git 歷史。

Docker Desktop 與 WSL

原生 PowerShell 和 WSL 都可能呼叫 Docker Desktop，但上下文和路徑掛載方式不同。檢查：

1
2
3


docker context show
docker version
docker compose version

WSL 中也執行相同命令，確認連線到預期引擎。 Compose 檔案中的 Windows 路徑、WSL 路徑和 named volume 不可隨意互換。遇到許可權問題時先執行 docker compose config 檢視解析結果。不要把 Docker Socket 暴露給不可信容器或 Agent。能訪問 Docker Daemon 通常意味著可以獲得宿主機高許可權。

代理和 TLS 錯誤

企業網路中，瀏覽器能登入不代表 npm、Git 和 Codex CLI 都能訪問外網。 PowerShell 檢視代理變數：

1

Get-ChildItem Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:NO_PROXY -ErrorAction SilentlyContinue

Git 檢視代理：

1

git config --show-origin --get-regexp 'http\..*proxy'

WSL 環境變數與 Windows 不自動同步。分別配置，並讓 NO_PROXY 包含確實需要直連的本地地址。不要使用關閉 TLS 驗證作為長期解決方案。應安裝企業 CA 或讓網路管理員提供正確代理配置。

任務開始前儲存基線

無論使用哪種環境，都先執行：

1
2
3


git status --short
git branch --show-current
git rev-parse --show-toplevel

告訴 Codex哪些改動屬於使用者、哪些檔案可以修改、必須執行什麼測試。完成後至少檢查：

1
2
3


git status --short
git diff --stat
git diff --check

高風險任務還應執行專案測試和構建。不要用“Codex說完成了”代替 Git diff 與測試結果。

常見症狀速查

PowerShell 找不到 codex

重啟終端，檢查 npm config get prefix 和 Get-Command codex，確認沒有隻安裝在 WSL。

WSL 中 codex 指向 .cmd

說明 PATH 混入 Windows npm 全域性目錄。清理 PATH，並在 WSL 內安裝 Linux 版本。

登入成功後仍提示未認證

確認執行使用者和環境與登入時相同。管理員終端、普通終端、Windows 和 WSL 各自可能有獨立配置。

Git 顯示許可權位全部變化

檢查 core.fileMode、倉庫位置和 WSL 掛載行為。先理解變化，不要直接提交。

測試在 PowerShell 失敗、WSL 成功

檢查 Shell 指令碼、路徑分隔符、環境變數語法和依賴二進位制。根據生產目標選擇主環境，而不是維護兩套偶然可用流程。

Codex 請求訪問工作區外目錄

判斷該目錄是否確實是構建快取或 SDK。若不是任務所需，拒絕並讓它改用倉庫內臨時目錄。