---
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="/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 和编辑器必须在同一套运行边界里。
