---
title: "在 Windows 上使用 Codex"
description: "按 native Windows、WSL2、App、CLI 和 IDE extension 的邊界選擇 Windows 上的 Codex 執行方式。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Windows 上使用 Codex，核心不是“裝哪個入口”，而是先決定程式碼和工具鏈在哪裡執行：native Windows 還是 WSL2。執行位置決定 sandbox、路徑、終端、依賴和排錯方式。

> [!IMPORTANT]
> Windows 排障先確認執行邊界：當前任務是在 native Windows、WSL2、App、CLI 還是 IDE extension 裡執行。不要把不同環境的路徑、許可權和網路問題混在一起排查。

<Cards>
  <Card title="Windows setup" href="https://developers.openai.com/codex/windows">
    檢視 Windows 上 Codex CLI、IDE 和 sandbox 的官方說明。
  </Card>
  <Card title="Windows App" href="/zh-Hant/docs/codex/official/01-products/42-windows-app">
    瞭解 Codex App for Windows 的安裝和常見問題。
  </Card>
  <Card title="WSL" href="https://learn.microsoft.com/en-us/windows/wsl/install">
    檢視 Windows Subsystem for Linux 的官方安裝入口。
  </Card>
</Cards>

## 先選執行環境

```mermaid
flowchart TD
    Start["Windows 上使用 Codex"]
    Native{"專案主要在 Windows 工具鏈?"}
    Linux{"專案主要在 Linux 工具鏈?"}
    NativeRun["Native Windows<br/>App / CLI / IDE"]
    WSL["WSL2<br/>Linux filesystem + Linux tools"]
    Decide["先整理專案位置和工具鏈"]

    Start --> Native
    Native -->|是| NativeRun
    Native -->|否| Linux
    Linux -->|是| WSL
    Linux -->|否| Decide
```

Native Windows 適合：

- 專案工具鏈本來在 Windows。
- 需要 Windows 原生應用或路徑。
- 企業機器要求保留 Windows-native workflow。

WSL2 適合：

- 專案依賴 Linux tooling。
- 主要用 VS Code Remote WSL。
- 程式碼放在 Linux filesystem。
- native sandbox 或企業策略不滿足當前需求。

## Native Windows 的關注點

Native Windows 執行時重點看：

- Windows sandbox 是否可用。
- 當前使用者許可權是否允許 setup。
- 企業策略是否阻止本地使用者、組或 firewall 設定。
- 終端是否支援需要的互動能力。
- 路徑是否是 Windows 路徑。

不要為了繞過 sandbox 問題直接開 full access。先看官方 Windows setup 和 agent approvals / security。

## WSL2 的關注點

WSL2 執行時重點看：

- 專案是否放在 WSL home 目錄，而不是 `/mnt/c/...`。
- Node、包管理器和 Codex CLI 是否裝在 WSL 內。
- VS Code 是否真正連線到 WSL。
- integrated terminal 是否顯示 Linux 路徑。
- Git、依賴、測試命令是否都在同一個 Linux 環境。

推薦專案位置：

```bash
mkdir -p ~/code
cd ~/code
git clone <your-repo>
```

從 WSL shell 開啟 VS Code：

```bash
code .
```

## App、CLI、IDE 怎麼選

App：

- 適合桌面任務管理、threads、diff review、worktrees。
- 適合不想只在終端裡工作的使用者。

CLI：

- 適合終端、SSH、指令碼和自動化。
- 在 WSL2 中使用時，確保 Codex 和專案都在 WSL2。

IDE extension：

- 適合編輯器內開發。
- 在 VS Code + WSL 場景下，要確認 extension 執行在正確 remote context。

入口不是關鍵，執行位置才是關鍵。

## 常見排錯

Sandbox setup failed：

- 檢查是否有管理員批准。
- 檢查企業策略是否允許本地 sandbox setup。
- 確認當前入口是 native Windows 還是 WSL2。
- 必要時讓 IT 協助，而不是放棄 sandbox。

路徑找不到：

- Windows 路徑和 WSL 路徑不要混用。
- native Windows 常見是 `C:\...`。
- WSL 常見是 `/home/...`。
- Windows Explorer 訪問 WSL 通常走 `\\wsl$`。

命令不能聯網：

- 先看 sandbox 和 approval。
- 再看企業防火牆、代理和證書。
- 不要把網路失敗直接歸因於 Codex。

VS Code 沒進 WSL：

- 看狀態列是否顯示 WSL。
- 看 terminal 路徑是否是 Linux。
- 必要時使用 “Reopen Folder in WSL”。

## 安全建議

- 預設保留 sandbox。
- 企業機器優先按 IT 策略完成 setup。
- 需要額外目錄時明確新增，不要放開全盤。
- 憑據走系統 secret store 或環境變數。
- 不把 API key、token、`auth.json` 複製進專案。
- WSL 和 Windows 環境分別管理依賴，避免路徑混亂。

Windows 上用 Codex 的關鍵是環境一致性：程式碼、終端、依賴、sandbox 和編輯器必須在同一套執行邊界裡。
