跳到主要内容

本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/app/windows

Windows

在 Windows 上使用 Codex app，支持原生沙箱和 PowerShell

适用于 Windows 的 Codex app 为你提供统一界面，用于跨项目工作、运行并行 agent 线程以及审查结果。 Windows app 支持核心工作流，例如 worktrees、automations、Git 功能、应用内浏览器、artifact 预览、plugins 和 skills。 它使用 PowerShell 和 Windows sandbox 在 Windows 上原生运行，或者你也可以将其配置为在 Windows Subsystem for Linux 2 (WSL2) 中运行。

显示项目侧边栏、活动线程和审查面板的 Windows 版 Codex app

下载并更新 Codex app​

从 Microsoft Store 下载 Codex app。

然后按照快速开始开始使用。

要更新 app，请打开 Microsoft Store，前往 Downloads，然后点击 Check for updates。随后 Store 会安装最新版本。

对于企业，管理员可以通过企业管理工具使用 Microsoft Store app 分发来部署该 app。

如果你更喜欢命令行安装方式，或需要替代打开 Microsoft Store UI 的方案，请运行：

winget install Codex -s msstore

原生沙箱​

Windows 上的 Codex app 在 agent 运行于 PowerShell 时支持原生 Windows sandbox，而当你在 Windows Subsystem for Linux 2 (WSL2) 中运行 agent 时，则使用 Linux 沙箱。要在任一模式下应用沙箱保护，请在向 Codex 发送消息之前，在 Composer 中将沙箱权限设置为 Default permissions。

以完全访问模式运行 Codex 意味着 Codex 不会被限制在你的项目目录内，并且可能执行无意的破坏性操作，从而导致数据丢失。请保持沙箱边界，并使用 rules 进行有针对性的例外设置；或者将你的批准策略设置为 never，让 Codex 根据你的批准与安全设置尝试在不请求提升权限的情况下解决问题。

根据你的开发环境自定义​

首选编辑器​

为 Open 选择一个默认 app，例如 Visual Studio、VS Code 或其他编辑器。你也可以按项目覆盖该选择。如果你已经为某个项目从 Open 菜单中选择了其他 app，则该项目级选择会优先生效。

显示 Windows 上默认 Open In app 的 Codex app 设置

集成终端​

你还可以选择默认的集成终端。根据你已安装的内容，可选项包括：

  • PowerShell
  • Command Prompt
  • Git Bash
  • WSL

此更改仅适用于新的终端会话。如果你已经打开了一个集成终端，请重启 app 或启动一个新线程，然后新的默认终端才会显示出来。

显示 Windows 上集成终端选择的 Codex app 设置

Windows Subsystem for Linux (WSL)​

默认情况下，Codex app 使用 Windows 原生 agent。这意味着 agent 在 PowerShell 中运行命令。该 app 仍可通过在需要时使用 wsl CLI 来处理位于 Windows Subsystem for Linux 2 (WSL2) 中的项目。

如果你想从 WSL 文件系统添加项目，请点击 Add new project 或按 Ctrl+O，然后在 File Explorer 窗口中输入 \\wsl$\。接着，选择你的 Linux 发行版以及你想打开的文件夹。

如果你计划继续使用 Windows 原生 agent，建议将项目存储在 Windows 文件系统上，并通过 /mnt//... 从 WSL 访问它们。与直接从 WSL 文件系统打开项目相比，这种设置更可靠。

如果你希望 agent 本身运行在 WSL2 中，请打开 Settings，将 agent 从 Windows native 切换为 WSL，然后重启 app。只有在重启后，此更改才会生效。重启后你的项目应仍会保留在原位。

WSL1 在 Codex 0.114 之前受支持。从 Codex 0.115 开始，Linux 沙箱迁移到了 bubblewrap，因此不再支持 WSL1。

显示 Windows native 和 WSL 选项的 agent 选择器的 Codex app 设置

你可以独立于 agent 配置集成终端。终端选项请参见根据你的开发环境自定义。 你可以让 agent 保持在 WSL 中，同时仍在终端中使用 PowerShell；或者根据你的工作流，两者都使用 WSL。

实用的开发者工具​

当一些常见的开发者工具已经安装好时，Codex 的工作效果最佳：

  • Git：为 Codex app 中的审查面板提供支持，并允许你检查或回退更改。
  • Node.js：agent 用于更高效执行任务的常见工具。
  • Python：agent 用于更高效执行任务的常见工具。
  • .NET SDK：当你想构建原生 Windows app 时很有用。
  • GitHub CLI：为 Codex app 中 GitHub 特定功能提供支持。

使用默认的 Windows 包管理器 winget 安装它们，只需将以下内容粘贴到集成终端中，或让 Codex 安装它们：

winget install --id Git.Git
winget install --id OpenJS.NodeJS.LTS
winget install --id Python.Python.3.14
winget install --id Microsoft.DotNet.SDK.10
winget install --id GitHub.cli

安装 GitHub CLI 后，运行 gh auth login 以在 app 中启用 GitHub 功能。

如果你需要不同的 Python 或 .NET 版本，请将包 ID 更改为你想要的版本。

故障排查和常见问题​

使用提升权限运行命令​

如果你需要 Codex 使用提升后的权限运行命令，请将 Codex app 本身以管理员身份启动。安装完成后，打开开始菜单，找到 Codex，并选择“以管理员身份运行”。Codex agent 会继承该权限级别。

PowerShell 执行策略阻止命令​

如果你以前从未在 PowerShell 中使用过 Node.js 或 npm 之类的工具，Codex agent 或集成终端可能会遇到执行策略错误。

如果 Codex 为你创建了 PowerShell 脚本，也可能发生这种情况。在这种情况下，你可能需要将执行策略设置得不那么严格，PowerShell 才会运行这些脚本。

错误可能类似于这样：

npm.ps1 cannot be loaded because running scripts is disabled on this system.

一个常见的修复方法是将执行策略设置为 RemoteSigned：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

有关详细信息和其他选项，请在更改策略之前查看 Microsoft 的执行策略指南。

Windows 上的本地环境脚本​

如果你的本地环境使用 npm scripts 等跨平台命令，你可以为所有平台保留一套共享的设置脚本或一组 actions。

如果你需要 Windows 特定行为，请创建 Windows 专用的设置脚本或 Windows 专用的 actions。

Actions 在你的集成终端所使用的环境中运行。请参见根据你的开发环境自定义。

本地设置脚本在 agent 环境中运行：如果 agent 使用 WSL，则在 WSL 中运行；否则在 PowerShell 中运行。

与 WSL 共享 config、auth 和 sessions​

Windows app 使用与 Windows 原生 Codex 相同的 Codex 主目录：%USERPROFILE%\.codex。

如果你也在 WSL 内运行 Codex CLI，CLI 默认会使用 Linux 主目录，因此它不会自动与 Windows app 共享 configuration、缓存的 auth 或 session 历史记录。

要共享它们，可使用以下方法之一：

  • 在你的文件系统中同步 WSL ~/.codex 与 %USERPROFILE%\.codex。
  • 通过设置 CODEX_HOME 将 WSL 指向 Windows 的 Codex 主目录：
export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

如果你希望每个 shell 都应用该设置，请将其添加到你的 WSL shell 配置文件中，例如 ~/.bashrc 或 ~/.zshrc。

Git 功能不可用​

如果你没有在 Windows 上原生安装 Git，该 app 将无法使用某些功能。请通过 PowerShell 或 cmd.exe 运行 winget install Git.Git 来安装。

对于从 \\wsl$ 打开的项目，无法检测到 Git​

目前，如果你想将 Windows 原生 agent 与一个也可从 WSL 访问的项目一起使用，最可靠的临时解决方法是将项目存储在原生 Windows 驱动器上，并通过 /mnt//... 在 WSL 中访问它。

打开对话框中未列出 Cmder​

如果已安装 Cmder 但它没有显示在 Codex 的打开对话框中，请将其添加到 Windows 开始菜单：右键单击 Cmder 并选择 Add to Start，然后重启 Codex 或重新启动系统。