開發工具

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

比較 Codex CLI 在 Windows 原生 PowerShell 與 WSL 中的使用方式，覆蓋安裝登入、Git 憑據、工作目錄、CRLF、環境變數、沙箱審批和常見許可權錯誤。

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' }

再判斷是：

  1. Codex 沙箱範圍；
  2. Windows 檔案許可權；
  3. 檔案只讀屬性；
  4. 防病毒軟體攔截；
  5. 檔案鎖；
  6. 路徑過長或字元問題；
  7. 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。若不是任務所需，拒絕並讓它改用倉庫內臨時目錄。

推薦的穩定組合

Windows/.NET/PowerShell 專案：程式碼放在 NTFS，使用原生 Codex、Windows Git 和 PowerShell 7。 Linux 服務/Node/Python 專案：程式碼放在 WSL ~/src，使用 WSL Codex、Linux Git 和 Bash。 必須跨兩邊的專案：明確唯一的 Git 寫入環境，另一邊只執行特定工具，並用 .gitattributes 固定換行策略。 最重要的不是哪條路線“更高階”，而是命令、檔案系統、憑據和測試是否處於同一個可解釋環境。環境一旦穩定，Codex 的排錯成本會明顯下降。

Windows 與 WSL 延伸文件

Codex 在 PowerShell 中的逐項錯誤排查

在 Windows PowerShell 裡運行 Codex 報錯，很多時候不是 Codex 本身壞了，而是 Node.js、npm、PATH、執行策略、引號、環境變數、代理或 PowerShell 傳參方式出了問題。

這篇按常見報錯整理排查順序。

快速排查清單

先跑：

1
2
3
4
5

$PSVersionTable.PSVersion
node -v
npm -v
where.exe codex
codex --version

如果 codex --version 正常，代表 Codex 命令可用，再查登入、專案路徑、權限或網路。

報錯一：codex 不是內部或外部命令

常見提示：

1

codex : The term 'codex' is not recognized as the name of a cmdlet...

檢查：

1
2
3
4

node -v
npm -v
where.exe npm
where.exe codex

如果 Node 或 npm 不存在，先安裝 Node.js LTS。若 npm 存在但沒有 codex，重新安裝：

1

npm install -g @openai/codex

再確認：

1
2

where.exe codex
codex --version

如果還是找不到，多半是 npm 全域 bin 目錄沒有進 PATH。

報錯二：npm install -g 失敗

常見原因：

  • Node.js 版本太舊；
  • npm 全域目錄權限不足；
  • 公司代理或憑證攔截。

檢查：

1
2
3
4
5
6

node -v
npm -v
npm ping
npm config get proxy
npm config get https-proxy
npm config get registry

公司設備不要隨便關閉 SSL 校驗，優先看內部開發環境說明。

報錯三：運行腳本被 ExecutionPolicy 攔截

如果看到：

1

running scripts is disabled on this system

可信腳本可以設定目前使用者策略：

1

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

或只針對這一次：

1

powershell -ExecutionPolicy Bypass -File .\script.ps1

不要把 -ExecutionPolicy Bypass 當萬能前綴。

報錯四：路徑裡有空格或中文

不要拼一整串命令。

不要這樣：

1

codex --cd C:\Users\Your Name\Documents\My Project

建議：

1
2
3

$project = 'C:\Users\Your Name\Documents\My Project'
Set-Location -LiteralPath $project
codex

調用可執行文件時：

1
2
3
4
5
6

$exe = 'C:\Program Files\nodejs\npx.cmd'
$args = @(
    '--version'
)

& $exe @args

每個參數都應該是陣列裡的一項。

報錯五：把 Bash 教程貼到 PowerShell

Bash 寫法：

1
2
3

export OPENAI_API_KEY=sk-...
curl -fsSL https://example.com/install.sh | bash
VAR=value codex

不能直接貼到 PowerShell。PowerShell 設定環境變數：

1

$env:OPENAI_API_KEY = 'sk-...'

長期保存：

1

[Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-...', 'User')

保存後重新開終端。

報錯六：引號、反斜線和 JSON 參數被改壞

不要手寫複雜 JSON 轉義：

1

codex --config "{\"foo\":\"bar\"}"

更穩的是用文件：

1
2
3
4

@{
    foo = 'bar'
    mode = 'review'
} | ConvertTo-Json | Set-Content -Encoding UTF8 .\config.json

原生命令用陣列傳參：

1
2
3
4
5
6
7
8

$args = @(
    '--model'
    'gpt-5-codex'
    '--reasoning-effort'
    'high'
)

codex @args

報錯七：中文亂碼或文件被寫壞

PowerShell 終端顯示亂碼，不一定代表文件真的壞了。用 UTF-8 讀取確認：

1

python -c "from pathlib import Path; print(Path('README.md').read_text(encoding='utf-8')[:200])"

修改中文 Markdown 時，要明確使用 UTF-8 並在寫入後驗證，不要只看終端顯示。

報錯八：Codex 登入或 API Key 不生效

先確認你要用哪種認證：

  • Codex app / CLI 登入；
  • API key；
  • 插件沿用本機 Codex；
  • 其他工具間接調用 Codex。

檢查目前視窗是否讀到：

1

$env:OPENAI_API_KEY

修改系統環境變數後，需要重新開 PowerShell。

報錯九：代理、憑證或防火牆

Codex 能啟動但請求失敗時，先測網路：

1
2

Resolve-DnsName api.openai.com
Test-NetConnection api.openai.com -Port 443

如果 DNS 或 443 不通，先修網路。瀏覽器可用但 PowerShell 不行時，查終端代理和公司憑證策略。

報錯十：命令成功失敗判斷不準

原生命令看 $LASTEXITCODE：

1
2
3
4

npm test
if ($LASTEXITCODE -ne 0) {
    throw "npm test failed with exit code $LASTEXITCODE"
}

PowerShell cmdlet 用終止錯誤：

1
2

$ErrorActionPreference = 'Stop'
Copy-Item -LiteralPath '.\a.txt' -Destination '.\backup\a.txt'

不要用 $LASTEXITCODE 判斷 Copy-Item、Move-Item、Remove-Item。

建議優先使用 PowerShell 7

powershell.exe 通常是 Windows PowerShell 5.1。PowerShell 7 是：

1

pwsh.exe

檢查：

1

$PSVersionTable.PSVersion

安裝 PowerShell 7 不會自動替換 powershell.exe，VS Code 和 Windows Terminal 設定也要確認。

一份更穩的 Codex 啟動模板 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

$ErrorActionPreference = 'Stop'

$project = 'C:\Work\my-project'
Set-Location -LiteralPath $project

where.exe codex | Out-Null
if ($LASTEXITCODE -ne 0) {
    throw 'codex command was not found in PATH'
}

codex --version
codex

帶參數時：

1
2
3
4
5
6

$args = @(
    '--model'
    'gpt-5-codex'
)

codex @args

排查順序建議

  1. node -v 和 npm -v。
  2. where.exe codex。
  3. codex --version。
  4. PowerShell 5.1 還是 7。
  5. 路徑是否有空格或中文。
  6. 是否複製了 Bash 語法。
  7. 是否被執行策略攔截。
  8. 登入或 API key 是否在目前視窗生效。
  9. 代理和憑證是否正常。
  10. 原生命令和 cmdlet 的錯誤判斷是否混用。