---
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="/docs/codex/official/01-products/33-app-core">
    先理解 Codex App 的基本工作流。
  </Card>
  <Card title="Windows + Codex" href="/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)
