For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

Windows 沙盒

在 Windows 上配置原生 Codex 沙盒并进行故障排除

在 Windows 上通过原生 ChatGPT 桌面应用CLIIDE 扩展使用 Codex。

Windows 上的 ChatGPT 桌面应用支持并行聊天、 工作树、计划任务、Git 功能、内置浏览器、文件预览、 插件和技能等核心工作流。

该应用可以通过 Windows 沙盒在 PowerShell 中原生运行,无需 WSL 或虚拟机。这样,Codex 可以继续使用 Windows 原生 工作流,同时限制文件系统和网络权限的范围。

原生 Windows 沙盒有两种模式:

  • 在 Windows 上以原生方式使用防护更强的 elevated 沙盒,
  • 在 Windows 上以原生方式使用备用的 unelevated 沙盒。

配置 Windows 沙盒

当您在 Windows 上原生运行 Codex 时,智能体模式会使用 Windows 沙盒, 阻止写入工作文件夹以外的文件系统,并在未经您明确审批时 阻止网络访问。

原生 Windows 沙盒支持两种模式,您可以在 config.toml 中进行配置:

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

elevated 是首选的原生 Windows 沙盒。它使用专用的 低权限沙盒用户、文件系统权限边界、防火墙 规则,以及在沙盒中运行命令所需的本地策略变更。

unelevated 是备用的原生 Windows 沙盒。它使用从您当前用户派生的 受限 Windows 令牌运行命令,应用基于 ACL 的 文件系统边界,并采用环境级离线控制,而不是 专用于离线用户的防火墙规则。其防护能力弱于 elevated,但 当经管理员批准的设置受到本地或 企业策略阻止时,仍然很实用。

如果两种模式均可用,请使用 elevated。如果默认原生沙盒 无法在您的环境中正常工作,请使用 unelevated 作为备用方案,同时 排查设置问题。

企业管理员可以限制 Codex 能够使用哪些原生沙盒实现, 具体通过 requirements.toml 进行配置:

[windows]
allowed_sandbox_implementations = ["elevated"]

此示例要求使用 elevated 沙盒,并禁止用户 回退到 unelevated。若要允许使用任一实现,请同时包含这两个值; 未选择模式时,Codex 会优先使用 elevated。请参阅 requirements.toml 参考资料,了解 支持的取值。

默认情况下,两种沙盒模式还会使用私有桌面,以增强 UI 隔离。仅当出于兼容性需要时,才设置 windows.sandbox_private_desktop = false,以使用 旧版 Winsta0\\Default 行为。

沙盒权限

以完全访问权限模式运行 Codex 时,Codex 不再局限于您的项目 目录,并且可能无意中执行破坏性操作,导致 数据丢失。为了更安全地执行自动化,请保留沙盒边界,并通过 规则处理特定例外;或者 将审批策略设置为 never,让 Codex 尝试解决问题,而不请求提升权限, 具体行为取决于您的审批和安全设置

Windows 版本矩阵

Windows 版本支持级别备注
Windows 11推荐这是在 Windows 上运行 Codex 的最佳基准版本。如果您正在标准化企业部署,请使用此版本。
较新且已更新到最新状态的 Windows 10尽力支持可以运行,但可靠性不如 Windows 11。在 Windows 10 上,Codex 依赖包括 ConPTY 在内的现代控制台支持。实际使用中,需要 Windows 10 版本 1809 或更高版本。
较旧的 Windows 10 版本不推荐更可能缺少 ConPTY 等必需的控制台组件,在企业环境中也更容易失败。

其他环境前提:

  • winget 应可用。若不可用,请先更新 Windows 或安装 Windows 程序包管理器,再设置 Codex。
  • 设置推荐的原生沙盒需要获得管理员批准。
  • 即使操作系统版本本身符合要求,部分由企业管理的设备仍会阻止 必要的设置步骤。

授予沙盒读取权限

当 Windows 沙盒无法读取目录,导致命令执行失败时,请使用:

/sandbox-add-read-dir C:\absolute\directory\path

该路径必须是指向现有目录的绝对路径。命令执行成功后,当前会话中后续在沙盒内运行的命令都可以读取该目录。

默认情况下,请使用原生 Windows 沙盒。在以下情况下选择 WSL: 您需要 Linux 原生工具、工作流已在 WSL2 中运行,或者 两种原生 Windows 沙盒模式都无法满足您的需求。

故障排除和常见问题

如果您正在排查受管理的 Windows 计算机问题,请先检查原生 沙盒模式、Windows 版本以及 Codex 显示的任何策略错误。Windows 原生 运行中的大多数问题都源于沙盒设置、登录权限或文件系统 权限,而不是编辑器本身。