Windows PowerShell 運行 Codex 報錯怎麼辦：安裝、登入、路徑和命令傳參排查

在 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

排查順序建議

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

小結

Windows PowerShell 運行 Codex 報錯，通常分成安裝環境、PowerShell 語法、路徑編碼、網路和認證四類。先按層排查，不要一上來重裝所有東西。使用陣列傳參、-LiteralPath、UTF-8 驗證和明確錯誤處理，Codex 在 Windows 上會穩很多。