---
title: "使用 Windows 版 App"
description: "講清 Codex 在 Windows 上的三種執行方式、sandbox 邊界、WSL 選擇和常見排錯。"
verifiedAt: "2026-05-06"
---

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

Codex 在 Windows 上可以透過 native App、CLI 或 IDE extension 使用。Windows App 提供跨專案工作、parallel agent threads、worktrees、automations、Git review、in-app browser、artifact previews、plugins 和 skills。

> [!WARNING]
> Windows 上最重要的選擇不是“裝哪個入口”，而是 agent 跑在 Windows native、fallback sandbox，還是 WSL2。不同執行位置決定檔案路徑、shell、sandbox 和工具鏈。

<Cards>
  <Card title="Windows" href="https://developers.openai.com/codex/windows">
    官方 Windows 執行方式、sandbox 和排錯頁。
  </Card>
  <Card title="App overview" href="/zh-Hant/docs/codex/official/01-products/33-app-core">
    先理解 Codex App 的基本工作流。
  </Card>
  <Card title="Windows + Codex" href="/zh-Hant/docs/codex/official/01-products/120-windows-codex">
    比較 Windows App、CLI、IDE 和 WSL 場景。
  </Card>
</Cards>

## 三種執行方式

```mermaid
flowchart LR
    User["Windows user"] --> Native["Windows native"]
    User --> Fallback["Windows fallback sandbox"]
    User --> WSL["WSL2 / Linux sandbox"]
    Native --> Project["Windows filesystem project"]
    WSL --> LinuxProject["Linux filesystem project"]
```

官方把 Windows 上的 Codex 執行方式分成三類：

- Windows native，優先使用更強的 native sandbox。
- Windows native fallback sandbox，適合受企業策略或本機限制影響的環境。
- WSL2，使用 Linux sandbox implementation。

選擇原則：

- 標準 Windows 專案：優先 Windows native。
- 專案、依賴和指令碼都在 Linux：優先 WSL2。
- 企業裝置限制 sandbox setup：按官方 Windows 頁選擇 fallback 並記錄原因。

## 安裝和更新

Windows App 透過 Microsoft Store / Windows 包管理路徑分發。命令列安裝可使用官方給出的 `winget` 路徑：

```powershell
winget install Codex -s msstore
```

企業部署時，不要讓個人隨意下載未知安裝包。使用 Microsoft Store app distribution 或企業管理工具分發，並統一配置更新策略。

## Sandbox 邊界

Windows native agent mode 使用 Windows sandbox，目標是在沒有明確批准時阻止 working folder 外寫入和網路訪問。

Native sandbox 可透過 `config.toml` 配置：

```toml
[windows]
sandbox = "elevated" # or "unelevated"
```

原則：

- 能用推薦 sandbox 就不要關閉。
- fallback 只用於推薦模式不可用時。
- full access 會取消專案目錄限制，可能造成資料丟失。
- 需要例外命令時，用 rules 做 targeted exceptions。

不要把 “approval_policy = never” 理解成“更安全”。它只是讓 Codex 嘗試在不請求 escalated permissions 的情況下解決問題，仍然需要正確 sandbox 和任務邊界。

## 編輯器和終端

Windows App 可以設定預設 editor，例如 Visual Studio、VS Code 或其他編輯器。專案也可以覆蓋預設選擇。

Integrated terminal 可以選擇 PowerShell、Command Prompt、Git Bash、WSL 等，取決於本機安裝情況。

注意：

- terminal 選擇影響新 terminal sessions。
- agent 執行環境和 terminal 環境可以不同。
- agent 在 WSL 中執行時，setup scripts 按 Linux 環境執行。
- agent 在 Windows native 執行時，setup scripts 按 Windows shell 環境執行。

## WSL2 怎麼選

如果專案本來就在 WSL filesystem，或依賴強繫結 Linux 工具鏈，讓 agent 執行在 WSL2 中更一致。

如果你計劃用 Windows-native agent，專案放在 Windows filesystem 通常更穩，再從 WSL 透過 `/mnt/<drive>/...` 訪問。

不要在沒有確認路徑、Git、shell、依賴安裝方式前，在 Windows 和 WSL 兩邊反覆切換。路徑錯位會導致 Codex 在錯誤目錄工作，或復現不了本地問題。

## 常用開發工具

Codex 在常用 developer tools 可用時更穩：

- Git：支援 review、diff、revert。
- Node.js：前端和指令碼任務常用。
- Python：資料、指令碼和工具任務常用。
- .NET SDK：native Windows app 相關。
- GitHub CLI：GitHub workflow 和 PR 場景。

具體版本和安裝命令以官方 Windows 頁、專案規則和企業標準為準。教程不要把版本號寫死。

## 常見排錯

需要 elevated permissions 時，先判斷是否真的需要。必須以更高許可權執行時，開啟 Start menu，選擇 Codex 的 `Run as administrator`，並記錄這次任務為什麼需要。

PowerShell execution policy 阻止指令碼時，不要直接複製寬鬆策略。先看 Microsoft execution policy guide，再決定是否設定為專案和企業允許的策略。

Windows App 與 WSL CLI 預設不共享同一 `CODEX_HOME`。如果要共享 config、auth 或 sessions，必須明確同步目錄或設定 `CODEX_HOME`，並把認證檔案按密碼處理。

Git features 不可用時，先確認 Windows native 環境是否安裝 Git，以及專案是否能被當前 agent 環境看到。

## 驗收清單

- 知道 agent 當前跑在 Windows native 還是 WSL2。
- sandbox 模式明確，並能解釋為什麼。
- 專案路徑、Git 根目錄、shell 和 package manager 對齊。
- editor 和 integrated terminal 選擇符合專案工作流。
- Windows 和 WSL 的 `CODEX_HOME` 沒有意外混用。
- 需要管理員許可權或 execution policy 變更時，有原因和回復方案。

## 官方資料

- [Windows](https://developers.openai.com/codex/windows)
- [Codex App](https://developers.openai.com/codex/app)
- [Rules](https://developers.openai.com/codex/rules)
- [Agent approvals and security](https://developers.openai.com/codex/agent-approvals-security)
