攻略

在 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,該選哪個?

原生 WindowsWSL 2
repo 放哪裡Windows 檔案系統,例如 C:\Users\you\ProjectLinux 檔案系統,例如 /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 嗎?
不用。Claude Code 可以在 Windows 10 1809 以上與 Windows Server 2019 以上,直接從 PowerShell 或 CMD 執行。只有想用 Claude Code 的沙箱或 Linux 工具鏈時才需要 WSL 2。
Codex CLI 在 Windows 還是實驗性的嗎?
OpenAI 目前的 Windows 頁面(2026-11-19 查閱)把原生 Windows 加 Windows 沙箱當成預設做法,沒有標示實驗性。需要 Linux 原生工具、或工作本來就在 WSL 裡時,才建議用 WSL 2。
repo 要放 C 槽還是 WSL 的檔案系統?
看你在哪裡跑工具。從 WSL 工作,就放在 Linux 的家目錄,/mnt/c 底下會比較慢;原生工作,就放在 Windows 檔案系統。
需要哪個版本的 Node.js?
Claude Code 的原生安裝程式不需要 Node.js。用 npm 安裝時,Claude Code 需要 Node.js 22 以上,Gemini CLI 需要 20.0.0 以上。用 node --version 檢查。
一定要付費方案嗎?
Claude Code 要:需要 Pro、Max、Ultra、Team、Enterprise 或 Console 帳號。Codex CLI 用 ChatGPT 帳號登入,或用依 API 費率計費的 OpenAI API Key。各方案包含什麼,請看各家官方的方案頁。

資料來源

  1. Advanced setup,Anthropic(2026-11-19 查閱)
  2. Troubleshoot installation and login,Anthropic(2026-11-19 查閱)
  3. CLI reference,Anthropic(2026-11-19 查閱)
  4. Windows sandbox,OpenAI(2026-11-19 查閱)
  5. WSL,OpenAI(2026-11-19 查閱)
  6. Authentication,OpenAI(2026-11-19 查閱)
  7. openai/codex README,OpenAI(2026-11-19 查閱)
  8. Gemini CLI installation,Google(2026-11-19 查閱)
  9. 安裝 WSL,Microsoft(2026-11-19 查閱)
  10. 跨文件系統工作,Microsoft(2026-11-19 查閱)
  11. about_Execution_Policies,Microsoft(2026-11-19 查閱)
  12. Folders,npm Docs(2026-11-19 查閱)

想把這些交給工具處理?

Pyloxa 是免費的 Windows App,執行你已經在用的 Claude Code 與 Codex CLI:依你的規則分工、自己跑你的測試,某一個額度用完時提出換手。