OpenAI Codex 中文文档（4.14更新）
联系我 ↗
官方文档 ↗

智能体审批与安全

了解如何通过沙箱、审批和网络控制安全地运行 Codex。

Codex 会尽量保护你的代码和数据，并降低误用风险。

本页介绍如何安全操作 Codex，包括沙箱、审批和网络访问。如果你要找的是用于扫描已连接 GitHub 仓库的产品，请参见 Codex Security。

默认情况下，智能体会在关闭网络访问的状态下运行。在本地，Codex 会使用由操作系统强制执行的沙箱限制它可以接触的内容范围，通常只限于当前工作区；同时还会配合审批策略，控制它在执行操作前何时必须暂停并向你请求确认。

如果你想先了解 Codex App、IDE 扩展和 CLI 中沙箱机制的高层说明，请参见沙箱机制。如果你需要更广泛的企业安全概览，请参见 Codex 安全白皮书。

沙箱与审批

Codex 的安全控制由两层共同配合实现：

  • 沙箱模式（sandbox mode）：决定 Codex 在技术上能做什么，例如可以写入哪些位置、是否能够访问网络。这个限制会在执行模型生成的命令时生效。
  • 审批策略（approval policy）：决定 Codex 何时必须先请求你的批准，例如离开沙箱、使用网络，或运行不在受信任集合内的命令。

Codex 会根据运行位置采用不同的沙箱模式：

  • Codex 云端：运行在 OpenAI 管理的隔离容器中，无法访问你的宿主系统或无关数据。它使用两阶段运行时模型：setup 阶段先于智能体阶段运行，可以访问网络以安装指定依赖；随后智能体阶段默认离线运行，除非你为该环境显式开启互联网访问。为云端环境配置的 secrets 只在 setup 阶段可用，并会在智能体阶段开始前移除。
  • Codex CLI / IDE 扩展：由操作系统级机制强制执行沙箱策略。默认包括关闭网络访问，并且把写权限限制在当前活动工作区内。你可以根据自己的风险承受范围配置沙箱、审批策略和网络设置。

在 Auto 预设下，例如 --full-auto，Codex 可以自动读取文件、编辑文件，并在工作目录中运行命令。

如果 Codex 需要编辑工作区之外的文件，或者运行需要网络访问的命令，它就会请求审批。如果你只想聊天、规划或阅读代码而不做修改，可以通过 /permissions 切换到 read-only 模式。

即使操作不是 shell 命令或文件修改，Codex 也可能为带副作用提示的应用（连接器）工具调用请求审批。只要某个应用 / MCP 工具声明了 destructive 注解，就一定需要审批，即便它同时还声明了其他较弱的提示，例如只读提示。

网络访问（高风险）

对于 Codex 云端，请参见智能体互联网访问，了解如何开启完整互联网访问或配置域名允许列表。

对于 Codex App、CLI 或 IDE 扩展，默认的 workspace-write 沙箱模式会保持网络关闭，除非你在配置中显式启用：

[sandbox_workspace_write]
network_access = true

你也可以在不为派生命令授予完整网络权限的前提下，单独控制 Web 搜索工具。Codex 默认通过 Web 搜索缓存访问结果。这个缓存是 OpenAI 维护的网页结果索引，因此 cached 模式返回的是预先索引好的结果，而不是实时抓取页面。这样能降低暴露于任意实时内容提示词注入的风险，但你仍应把 Web 结果视为不可信输入。

如果你使用 --yolo 或其他完全访问沙箱设置，Web 搜索会默认切换为实时结果。你可以使用 --search 或设置 web_search = "live" 来允许实时浏览，也可以把它设为 "disabled" 关闭该工具：

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

无论是启用网络访问还是启用 Web 搜索，都需要格外谨慎。提示词注入可能会诱导智能体获取并遵循不可信指令。

默认值与建议

  • 启动时，Codex 会检测当前文件夹是否受版本控制，并据此给出建议：
    • 受版本控制的文件夹：Auto（workspace-write + on-request 审批）
    • 不受版本控制的文件夹：read-only
  • 取决于你的设置，Codex 也可能在你显式信任当前工作目录之前先以 read-only 启动，例如通过首次引导提示或 /permissions 完成信任。
  • 工作区不仅包括当前目录，也包括 /tmp 之类的临时目录。你可以通过 /status 查看哪些目录属于当前工作区。
  • 如果你要接受默认行为，直接运行 codex 即可。
  • 你也可以显式指定：
    • codex --sandbox workspace-write --ask-for-approval on-request
    • codex --sandbox read-only --ask-for-approval on-request

可写根目录中的受保护路径

在默认的 workspace-write 沙箱策略下，即使某个根目录可写，其中仍然包含受保护路径：

  • 无论 <writable_root>/.git 是目录还是文件，都会被作为只读保护。
  • 如果 <writable_root>/.git 是一个指针文件（gitdir: ...），其解析后的 Git 目录路径也会被作为只读保护。
  • 当 <writable_root>/.agents 存在且为目录时，会被作为只读保护。
  • 当 <writable_root>/.codex 存在且为目录时，会被作为只读保护。
  • 保护是递归的，因此这些路径下的所有内容都会保持只读。

在不弹出审批提示的情况下运行

你可以通过 --ask-for-approval never 或简写 -a never 关闭审批提示。

这个选项适用于所有 --sandbox 模式，因此你仍然可以控制 Codex 的自主性边界。Codex 会在你设定的限制内尽最大努力完成任务。

如果你需要 Codex 在没有审批提示的情况下读取文件、编辑文件并运行带网络访问的命令，可以使用 --sandbox danger-full-access，或等价的 --dangerously-bypass-approvals-and-sandbox 标志。启用前请务必谨慎。

如果你希望采用中间方案，可以使用 approval_policy = { granular = { ... } }，让某些类别的审批保持交互式，而其他类别自动拒绝。细粒度策略覆盖沙箱审批、execpolicy 规则提示、MCP 提示（mcp_elicitations）、request_permissions 提示以及技能脚本审批。

如果你希望把符合条件的审批评审交给 Guardian 评审子智能体，而不是直接弹给用户，可以设置 approvals_reviewer = "guardian_subagent"。管理员还可以通过 allowed_approvals_reviewers 约束可选评审者范围。

常见的沙箱与审批组合

目标 Flags 效果
Auto（预设） 不传 flag，或 --full-auto Codex 可以在工作区内读取文件、编辑文件和运行命令。编辑工作区外文件或访问网络时需要审批。
安全的只读浏览 --sandbox read-only --ask-for-approval on-request Codex 可以读文件并回答问题。改文件、运行命令或访问网络时都需要审批。
非交互式只读（CI） --sandbox read-only --ask-for-approval never Codex 只能读取文件，且永不请求审批。
自动编辑，但运行不可信命令前请求审批 --sandbox workspace-write --ask-for-approval untrusted Codex 可以读写文件，但在运行不可信命令前会先请求审批。
危险的完全访问 --dangerously-bypass-approvals-and-sandbox（别名：--yolo） 没有沙箱，也没有审批（不推荐）。

--full-auto 只是 --sandbox workspace-write --ask-for-approval on-request 的便捷别名。

当你使用 --ask-for-approval untrusted 时，Codex 只会自动运行已知安全的只读操作。那些可能改变状态或触发外部执行路径的命令，例如破坏性的 Git 操作，或带 Git 输出/配置覆盖 flag 的命令，都需要审批。

config.toml 中的配置

更完整的配置工作流，请结合基础配置、高级配置和配置参考一起阅读。

# Always ask for approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

你也可以把这些预设保存为 profile，然后通过 codex --profile <name> 选择：

[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode    = "read-only"

在本地测试沙箱

如果你想观察某条命令在 Codex 沙箱下运行时会发生什么，可以使用下面这些 Codex CLI 命令：

# macOS
codex sandbox macos [--full-auto] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--full-auto] [COMMAND]...

sandbox 命令也可以通过 codex debug 使用；平台辅助命令还有别名，例如 codex sandbox seatbelt 和 codex sandbox landlock。

操作系统级沙箱

Codex 会根据不同操作系统以不同方式强制执行沙箱：

  • macOS：使用 Seatbelt 策略，并通过 sandbox-exec 结合与你所选 --sandbox 模式对应的 profile（-p）运行命令。当受限读取权限启用平台默认规则时，Codex 会附加一套精心筛选的 macOS 平台策略，而不是宽泛地放开 /System，以尽量保持常见工具兼容性。
  • Linux：默认使用 bwrap pipeline 配合 seccomp。如果你需要旧路径，也可以使用 use_legacy_landlock。在 managed proxy 模式下，默认 bwrap pipeline 会通过仅代理桥接转发出站流量；如果无法构建有效的本地代理路由，它会以 fail-closed 的方式失败。
  • Windows：在 Windows Subsystem for Linux 2 (WSL2) 中运行时使用 Linux 沙箱实现。WSL1 在 Codex 0.114 之前仍可使用；从 0.115 开始，Linux 沙箱切换到了 bwrap，因此 WSL1 不再受支持。在 Windows 原生环境中运行时则使用Windows 沙箱实现。

如果你在 Windows 上使用 Codex IDE 扩展，它可以直接支持 WSL2。你可以在 VS Code 设置中加入以下内容，以便在可用时始终让智能体运行在 WSL2 内：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

这样即使宿主机是 Windows，IDE 扩展也会继承 Linux 的命令、审批和文件系统访问沙箱语义。更多内容请参见 Windows 设置指南。

如果你是在 Windows 原生环境中运行 Codex，可以在 config.toml 中配置原生沙箱模式：

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

更多细节请参见 Windows 设置指南。

如果你在 Docker 这类容器化环境中运行 Linux，而宿主机或容器配置不支持所需的 Landlock 和 seccomp 功能，沙箱可能无法工作。

此时应由 Docker 容器本身提供你需要的隔离，然后在容器内部使用 --sandbox danger-full-access，或 --dangerously-bypass-approvals-and-sandbox，来运行 codex。

版本控制

Codex 在配合版本控制工作流时效果最佳：

  • 在委派任务前先切到 feature branch，并保持 git status 干净。这样更容易隔离和回滚 Codex 生成的补丁。
  • 相比直接编辑已跟踪文件，更推荐基于补丁的工作流，例如 git diff / git apply。同时要频繁提交，以便小步回退。
  • 像审查普通 PR 一样对待 Codex 的建议：运行有针对性的验证、审查 diff，并在提交信息中记录决策以便审计。

监控与遥测

Codex 支持基于 OpenTelemetry（OTel）的可选监控，帮助团队在不削弱本地默认安全边界的前提下进行审计、问题调查和合规支持。遥测默认关闭，必须在配置中显式启用。

概览

  • 默认情况下，Codex 会关闭 OTel 导出，以保持本地运行自包含。
  • 启用后，Codex 会发出结构化日志事件，覆盖会话、API 请求、SSE / WebSocket 流活动、用户 prompt（默认脱敏）、工具审批决策和工具结果。
  • Codex 会给导出事件打上 service.name（来源方）、CLI 版本和环境标签，用于区分 dev / staging / prod 流量。

启用 OTel（可选）

在 Codex 配置中加入 [otel] 块，通常位于 ~/.codex/config.toml，然后选择 exporter 并决定是否记录 prompt 文本：

[otel]
environment = "staging"    # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false    # redact prompt text unless policy allows
  • exporter = "none" 会保留埋点，但不会把数据发到任何地方。
  • 如果你要把事件发送到自有 collector，可以选择其一：
[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Codex 会批量发送事件，并在退出时刷新缓冲。Codex 只会导出由自身 OTel 模块产生的遥测数据。

事件类别

代表性事件类型包括：

  • codex.conversation_starts：模型、reasoning 设置以及沙箱 / 审批策略
  • codex.api_request：请求次数、状态 / 成功与否、耗时和错误细节
  • codex.sse_event：流事件类型、成功 / 失败、耗时，以及 response.completed 上的 token 计数
  • codex.websocket_request 和 codex.websocket_event：请求耗时，以及每条消息的类型 / 成功 / 错误
  • codex.user_prompt：长度；除非显式开启，否则内容会被脱敏
  • codex.tool_decision：是否批准 / 拒绝，以及决策来源是配置还是用户
  • codex.tool_result：耗时、成功与否以及输出片段

对应的 OTel metrics 也包含计数器和耗时直方图，例如 codex.api_request、codex.sse_event、codex.websocket.request、codex.websocket.event 和 codex.tool.call，以及相应的 .duration_ms 指标。

完整事件目录和配置参考，请参见 GitHub 上的 Codex configuration 文档。

安全与隐私建议

  • 除非你的策略明确允许存储 prompt 内容，否则应保持 log_user_prompt = false。prompt 中可能包含源代码和敏感数据。
  • 遥测只应发送到你自己可控的 collector，并按合规要求配置保留期和访问控制。
  • 工具参数和工具输出也应视为敏感数据；如有可能，优先在 collector 或 SIEM 层做脱敏。
  • 如果你不希望 Codex 在 CODEX_HOME 下保存会话记录，请检查本地数据保留设置，例如 history.persistence 和 history.max_bytes。参见高级配置和配置参考。
  • 如果 CLI 运行时关闭了网络访问，OTel 导出将无法连接到你的 collector。若要导出，需要在 workspace-write 模式中允许访问 OTel endpoint，或者在 Codex 云端把 collector 域名加入允许列表。
  • 应定期审查导出事件，重点关注审批 / 沙箱变更以及异常的工具执行。

OTel 是可选项，它的设计目标是补充上文的沙箱与审批保护，而不是替代它们。

托管配置

企业管理员可以在托管配置中为工作区配置 Codex 安全设置。关于具体的设置方式和策略细节，请参见该页。

来源：https://developers.openai.com/codex/agent-approvals-security