攻略
在 Windows 跑 Claude Code 與 Codex CLI,需要 WSL 嗎?
兩個 CLI 現在都能直接在 Windows 上跑。這篇整理各自的官方安裝方式、什麼情況還是 WSL 2 比較好,以及最常卡住的安裝錯誤怎麼解。
Windows 怎麼安裝 Claude Code?
Anthropic 列出的支援環境是 Windows 10 1809 以上與 Windows Server 2019 以上,x64 或 ARM64,記憶體 4 GB 以上。PowerShell 或 CMD 都可以,官方方式有這幾種:
- PowerShell(建議的原生安裝程式):
irm https://claude.ai/install.ps1 | iex - CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd - WinGet:
winget install Anthropic.ClaudeCode。用 WinGet 裝的不會自動更新,要自己定期跑winget upgrade Anthropic.ClaudeCode。 - npm:
npm install -g @anthropic-ai/claude-code@latest。需要 Node.js 22 以上,裝的是同一個原生執行檔。
原生安裝程式會把 claude.exe 放在 %USERPROFILE%\.local\bin,之後在背景自動更新。裝完開一個新的終端機確認:
claude --version
claude doctor
claude doctor 會列出安裝與設定的診斷資訊(只讀,不會改東西)。接著在專案資料夾執行 claude,照瀏覽器的步驟登入。Claude Code 需要 Pro、Max、Ultra、Team、Enterprise 或 Console 帳號,claude.ai 免費方案不包含 Claude Code。
一定要裝 Git for Windows 嗎?
不一定,但建議裝。有 Git for Windows 時,Claude Code 的 Bash 工具會用 Git Bash;沒有的話就改用 PowerShell 工具執行命令。如果 Claude Code 找不到 Git Bash,在 ~/.claude/settings.json 指定路徑:
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}
要指到 bash.exe,不是 git-bash.exe 那個啟動器;檔名不對的話 Claude Code 會忽略這個變數。不確定 Git 裝在哪,執行 where.exe git 就知道。
Codex CLI 能在原生 Windows 跑嗎?
可以。OpenAI 的 Windows 文件寫明 CLI、IDE 擴充套件與桌面 App 都能在 Windows 原生使用,在 PowerShell 裡搭配 Windows 沙箱執行,不必透過 WSL 或虛擬機。我們查閱的頁面沒有把原生 Windows 標成實驗性。建議用 Windows 11;Windows 10 至少要 1809。
在 PowerShell 用官方安裝程式,或用 npm 安裝:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
npm install -g @openai/codex
用 codex login 透過瀏覽器以 ChatGPT 帳號登入,codex login status 可以看目前的登入方式。也可以用 codex login --with-api-key 改用 OpenAI Platform 的 API Key,這會依標準 API 費率計費。
Codex 的 Windows 沙箱
沙箱會依目前的權限設定,限制 Codex 執行的命令能讀寫哪些檔案、能不能連網。有三種實作:
mxc:支援的環境優先用它。需要 Windows 11 24H2(build 26100.9278)或 25H2(build 26200.9278),以及 Microsoft 還在陸續推出的 MXC 功能,不需要系統管理員設定。elevated:沒指定模式時 Codex 優先用的備援。設定時需要系統管理員核准,但沙箱裡的命令本身不會以系統管理員身分執行。unelevated:無法做 elevated 設定時使用,網路隔離比較弱。
要指定備援,在 Codex 的 config.toml 的 [windows] 下寫 sandbox = "elevated"(或 "unelevated")。
Gemini CLI 呢?
Google 的安裝說明建議 Windows 11 24H2 以上、Node.js 20.0.0 以上,支援的 shell 包含 PowerShell。安裝命令是 npm install -g @google/gemini-cli。
原生 Windows 還是 WSL 2,該選哪個?
| 原生 Windows | WSL 2 | |
|---|---|---|
| repo 放哪裡 | Windows 檔案系統,例如 C:\Users\you\Project | Linux 檔案系統,例如 /home/you/Project |
| 檔案存取速度 | 給 Windows 工具用最快 | 在 Linux 裡很快;在 /mnt/c/... 底下工作會變慢 |
| 工具鏈 | Windows 原生的專案與工具 | Linux 工具鏈 |
| Claude Code 沙箱 | 不支援 | 支援(WSL 1 不支援) |
| Codex 沙箱 | Windows 沙箱(mxc、elevated 或 unelevated) | Linux 沙箱;Codex 0.115 起不再支援 WSL 1 |
| 安裝方式 | 上面的 PowerShell 或 CMD 安裝程式 | 在 WSL 的 shell 裡執行 curl -fsSL https://claude.ai/install.sh | bash 與 curl -fsSL https://chatgpt.com/codex/install.sh | sh |
Microsoft 的原則很簡單:在 Linux 命令列工作,檔案就放 WSL 的檔案系統;在 PowerShell 或 CMD 工作,就放 Windows 的檔案系統。兩邊混用通常就是變慢的原因。要裝 WSL,用系統管理員身分開 PowerShell 執行 wsl --install 再重新開機;新裝的發行版預設就是 WSL 2,可以用 wsl -l -v 確認。
用 WSL 的話,Claude Code 與 Codex 要在 WSL 終端機裡安裝,不是在 PowerShell。如果 which node 或 which npm 顯示 /mnt/c/ 開頭的路徑,代表 WSL 用到的是 Windows 那邊的 Node.js,請在 Linux 發行版裡另外裝 Node。
常見的安裝錯誤與解法
裝完出現「'claude' 不是內部或外部命令」
安裝資料夾不在 PATH 裡。先確認檔案存在,再把資料夾加進使用者的 PATH,然後開新的終端機(用編輯器內建終端機的話,編輯器也要重開):
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
用 npm 裝的 CLI 找不到
在 Windows 上,npm 會把全域命令直接放在全域 prefix 資料夾,預設是 %AppData%\npm。執行 npm prefix -g 看你的位置,確認這個資料夾在 PATH 裡,再開新的終端機。
「因為這個系統上已停用指令碼執行」
英文訊息是 “running scripts is disabled on this system”。這是 PowerShell 的執行原則擋下了 npm 建立的 npm.ps1 或 claude.ps1。三個解法擇一:只對自己這個使用者允許本機指令碼(不需要系統管理員)、改呼叫 npm.cmd,或改用不會裝 .ps1 的原生安裝程式:
Get-ExecutionPolicy -List
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Microsoft 說明執行原則不是安全邊界。群組原則的設定會蓋過它,公司管理的電腦請找 IT。
在錯的 shell 跑了安裝命令
'irm' is not recognized:你在 CMD。改用 CMD 的命令,或開 PowerShell。The token '&&' is not a valid statement separator:你在 PowerShell。改用 PowerShell 的命令。A parameter cannot be found that matches parameter name 'fsSL':你在 PowerShell 跑了 macOS/Linux 的命令,PowerShell 的curl其實是Invoke-WebRequest的別名。
Node.js 版本太舊
執行 node --version。Claude Code 的 npm 套件需要 Node.js 22 以上(版本太舊時 npm 會顯示 EBADENGINE 警告),Gemini CLI 需要 20 以上。Claude Code 的原生安裝程式完全不用 Node.js。
WSL 出現「Exec format error」
你用的是 WSL 1。用 wsl --set-version <DistroName> 2 把發行版轉成 WSL 2。
Pyloxa 能幫上什麼
Pyloxa 是 Windows 10、11 的原生桌面 App,讓 Claude Code 和 Codex CLI 在同一個專案裡分工合作。它直接在 Windows 執行,不需要 WSL,也不需要 Docker。需要 Git for Windows 2.30 以上;Node.js 22 以上只有在要讓它幫你安裝 CLI 時才需要。
免費版的設定精靈就涵蓋這篇的步驟:
- 環境檢查:git(必要)與 Node.js(選用)。缺少或版本太舊時,複製畫面上的 winget 命令或開啟官方下載頁,裝好後按「重新檢查」。
- 安裝 Agent:每個 CLI 一張卡,先讓你看到完整命令,再以 CLI 官方的
npm install -g套件安裝 Pyloxa 已驗證的最新版本。 - 登入與金鑰:顯示每個 CLI 是否「可以派工」。在終端機用
claude auth login或codex login登入訂閱,或貼上 API Key。Pyloxa 不會讀取、複製或傳送你的 token。Gemini CLI 是實驗性支援,需要你自己的付費 Gemini API Key。
疑難排解裡和 Windows 有關的:CLI 在終端機能用、Pyloxa 卻顯示沒安裝,請重新啟動 Pyloxa;工作失敗並顯示「無法啟動 claude」(或 codex),可能是防毒軟體擋下,請允許 Pyloxa 的安裝資料夾,不要直接關掉防護。安裝檔目前還沒有程式碼簽章,第一次執行時 SmartScreen 可能會警告。
以上都在免費版。如果你只在一個終端機用一個 Agent,其實不需要 Pyloxa;它適合想讓大腦把需求拆給兩家 Agent 派工、每個工作在自己的 git worktree 跑、由你自己的測試命令決定過不過的情況。詳見工作流程。
常見問題
在 Windows 用 Claude Code 一定要 WSL 嗎?
Codex CLI 在 Windows 還是實驗性的嗎?
repo 要放 C 槽還是 WSL 的檔案系統?
/mnt/c 底下會比較慢;原生工作,就放在 Windows 檔案系統。需要哪個版本的 Node.js?
node --version 檢查。一定要付費方案嗎?
資料來源
- Advanced setup,Anthropic(2026-11-19 查閱)
- Troubleshoot installation and login,Anthropic(2026-11-19 查閱)
- CLI reference,Anthropic(2026-11-19 查閱)
- Windows sandbox,OpenAI(2026-11-19 查閱)
- WSL,OpenAI(2026-11-19 查閱)
- Authentication,OpenAI(2026-11-19 查閱)
- openai/codex README,OpenAI(2026-11-19 查閱)
- Gemini CLI installation,Google(2026-11-19 查閱)
- 安裝 WSL,Microsoft(2026-11-19 查閱)
- 跨文件系統工作,Microsoft(2026-11-19 查閱)
- about_Execution_Policies,Microsoft(2026-11-19 查閱)
- Folders,npm Docs(2026-11-19 查閱)