部署 Codex 时,您需要决定允许它访问哪些账户、文件和服务,以及执行哪些操作。本手册帮助企业管理员将这些决定落实到配置中,测试配置效果,并找出需要额外保护的环节。
这些安全建议旨在让开发者获得使用 Codex 所需的权限,同时降低意外更改、敏感数据泄露和防护措施本身被修改的风险。您可以据此选择适合自身工作流和风险管理要求的控制措施,了解其局限,并验证它们在您的环境中如何生效。这些措施可补充组织已有的身份、终端、网络和服务防护。
您可以从具体任务入手,例如仅允许登录公司的工作空间,也可以从更广泛的目标入手,例如在保护生产环境的同时让开发者使用 Codex。
根据您的工作选择起点:
-
单项配置方案逐项介绍控制措施,包括配置步骤、验证方法、回滚说明和适用边界。
-
组合方案介绍如何将多项控制措施与身份管理、源代码管理、部署等系统中的防护措施结合起来,实现常见的安全目标。
您可以根据组织的实际情况调整示例。使用每个配置示例时,请结合配套说明,确认应将配置放在哪里、适用于哪些客户端或环境,以及它能控制和不能控制哪些行为。
在扩大部署范围之前,请先在测试终端上试用配置。确认预期的工作流能够成功执行,同时有意限制的操作会被阻止。根据测试结果调整配置,并向将要使用 Codex 的人员说明权限边界。
选择起点
使用页面目录打开以下相应章节。
| 如果您想要 | 请从这里开始 |
|---|---|
| 配置一项具体的控制措施 | 单项配置方案 |
| 在保护生产环境的同时让开发者使用 Codex | 在保护生产环境的同时让开发者使用 Codex |
| 降低内部代码被公开发布的风险 | 降低内部代码被公开发布的风险 |
| 防止 Codex 修改自身的防护措施 | 防止 Codex 修改自身的防护措施 |
组合方案列出了实现各项目标所需的控制措施、外部防护和验证步骤。
准备工作
-
盘点纳入管理范围的客户端和运行环境:桌面应用、CLI、IDE 扩展程序、Codex 云端、CI 运行器和远程主机。
-
在大范围部署之前,先在测试终端上试行配置。
-
记录支持的最低 Codex 版本。权限配置文件允许列表需要 Codex 0.138.0 或更高版本。
-
为每个托管配置包保留一份用于回滚的副本。
-
每次更改后,分别测试一个允许执行的工作流和一个有意阻止的工作流。
托管要求是管理员强制实施的约束,托管默认值是启动时使用的设置。对于受支持的身份验证、沙盒、审批、MCP、插件、钩子和网络限制,请使用托管要求。身份验证要求必须在本地部署或通过 macOS MDM 下发,云端托管要求无法强制实施这些身份验证限制。请参阅托管配置和配置参考。
配置位置
在向试点用户部署之前,请根据组织的实际情况调整这些配置示例。TOML 代码块是策略片段。请将所需设置合并到现有文件中,避免重复定义表,并替换示例中的名称、域名和路径。验证步骤列出了您需要在自己的环境中确认的预期结果。
对于本地 Codex,管理员可以在 macOS 和 Linux 上将强制要求部署到 /etc/codex/requirements.toml,在 Windows 上部署到 %ProgramData%\OpenAI\Codex\requirements.toml。对于托管的 macOS 设备,可以通过 MDM 下发 com.openai.codex:requirements_toml_base64 偏好设置。您也可以在管理控制台的智能体安全下配置云端托管策略。先选择策略,再选择适用的环境或操作系统,然后配置要求。请保护策略文件及其父目录,防止运行 Codex 的用户修改它们。常规 config.toml 或托管默认设置提供启动值,无法强制实施要求。请参阅托管配置和智能体安全。
单项配置方案
选择所需的控制措施,展开相应方案即可查看配置、验证步骤、回滚说明和适用边界。每验证一项,就勾选对应条目。如果浏览器存储可用,验证进度会保存在当前浏览器中。
| 控制项 | 配置方案 |
|---|---|
| 身份验证 | 仅允许登录公司的工作空间 |
| 运行时权限 | 限制权限配置文件和完全访问权限 |
| MCP 服务器 | 仅允许已批准的 MCP 服务器 |
| 监控和审计 | 监控 Codex 活动 |
| 网络 | 限制网络访问目标 |
| 文件和凭据 | 保护密钥等机密信息和无关代码仓库 |
| 敏感命令 | 要求对敏感命令进行审批 |
如果员工必须通过公司的 ChatGPT 工作空间登录 Codex,且托管终端禁止使用个人 ChatGPT 账户或 API 密钥进行身份验证,请使用此方案。
预期结果
在公司管理的设备上,Codex 仅允许用户通过 ChatGPT 登录公司的 ChatGPT 工作空间。
前提条件
-
已批准的 ChatGPT Enterprise 工作空间的 UUID。
-
向终端分发 Codex 托管配置的途径。
-
已决定在托管终端上禁止使用 API 密钥进行身份验证。
配置
-
在内部配置代码仓库中记录已批准的工作空间 UUID。
-
将强制身份验证要求添加到本地
requirements.toml:allowed_login_methods = ["chatgpt"] allowed_chatgpt_workspaces = ["00000000-0000-0000-0000-000000000000"]第一个键仅允许通过 ChatGPT 进行身份验证,第二个键将登录范围限制为已批准的工作空间。请将示例 UUID 替换为您的工作空间 UUID。请参阅要求配置参考。
-
通过本地
requirements.toml或 macOS MDM 部署这些要求,使用配置位置中列出的路径。这些身份验证要求在加载凭据和获取云端策略之前生效。如果将它们放入云端托管要求中,Codex 会忽略它们。请防止用户修改该文件及其父目录。旧版managed_config.toml中的默认设置无法强制实施此限制。 -
试点期间,请让用户退出登录,或移除先前保存的个人 Codex 会话。不要假设新策略会自动使已有会话失效。
-
将登录限制与工作空间角色和用户组访问权限结合使用。身份验证决定哪个身份可以登录,RBAC 决定该身份可以使用哪些 Codex 功能。请参阅身份验证。
验证
-
退出 Codex 登录。
-
尝试使用个人 ChatGPT 账户登录。预期结果:登录个人工作空间的请求被拒绝。
-
尝试使用 API 密钥登录 Codex。预期结果:API 密钥登录被拒绝。
-
使用企业账户登录已批准的工作空间。预期结果:登录成功。
-
重启桌面应用、CLI 和 IDE 扩展程序,然后重复上述检查。
回滚
恢复之前的本地身份验证要求,并重新部署经过审查的配置包。
适用边界
此方案控制托管终端上的托管 Codex 客户端。如果要求是“禁止通过公司资产以个人身份使用 Codex”,还需结合终端应用控制措施和网络策略。
如果开发者需要只读访问权限或仅限工作空间的访问权限,而您希望防止他们选择完全访问权限或使用 --yolo 绕过审批和沙盒限制,请使用此方案。
预期结果
用户只能选择已批准的只读或仅限工作空间的权限配置文件,不能选择
danger-full-access、approval_policy = "never"或--yolo。
配置
-
定义一个已批准的工作空间权限配置文件:
[permissions.corp-workspace] description = "Company workspace access with no unrestricted host access." extends = ":workspace" -
强制限定允许使用的权限配置文件和审批策略:
allowed_approval_policies = ["on-request", "untrusted"] allowed_approvals_reviewers = ["user"] default_permissions = "corp-workspace" [allowed_permission_profiles] ":read-only" = true "corp-workspace" = true ":danger-full-access" = false允许列表必须列出所有允许使用的配置文件。未列入其中或设为 false 的配置文件一律被拒绝,包括未来版本新增的配置文件。请参阅配置参考。
-
对于仍使用
sandbox_mode的旧版客户端,请使用以下设置:allowed_approval_policies = ["on-request", "untrusted"] allowed_sandbox_modes = ["read-only", "workspace-write"] -
将这些设置作为管理员强制实施的要求下发,避免通过用户可编辑的配置文件下发。
-
如果之后决定允许自动审查,请先测试,再明确将其加入允许范围。自动审查会改变由谁审查越过权限边界的请求,但无法恢复已移除的边界。请参阅自动审查。
验证
-
打开权限选择器。预期结果:完全访问权限不可用,或选择该权限时被拒绝。
-
使用
--dangerously-bypass-approvals-and-sandbox启动。预期结果:Codex 拒绝启动,或强制使用兼容的权限配置文件。 -
使用
--sandbox danger-full-access --ask-for-approval never启动。预期结果:启动请求被拒绝。 -
运行常规工作空间任务。预期结果:任务成功,越过权限边界的操作仍需审批。
回滚
恢复之前的要求配置包。除非已单独批准例外情况,否则应继续禁止不受限制的访问。
适用边界
此方案控制 Codex 的运行时权限,无法撤销操作系统账户已有的特权。
如果组织需要决定 Codex 可以使用哪些 MCP 服务器,并强制执行已批准的服务器列表,请使用此方案。
允许使用服务器和配置服务器是两个独立步骤。允许列表条目只允许使用与之匹配的服务器,不会创建服务器配置。请单独配置服务器,使用匹配的名称和身份,并配置服务器所需的身份验证。
预期结果
只有当配置的 MCP 服务器名称和身份均与企业批准的列表匹配时,Codex 才会启用该服务器。
配置
-
盘点每台已批准服务器的负责人、用途、传输方式、确切的可执行文件或 URL、身份验证方式、数据分类以及具有写入能力的工具。
-
从全部拒绝开始。空的托管表会禁用所有 MCP 服务器:
[mcp_servers] -
按确切的 URL 添加已批准的 HTTP 服务器:
[mcp_servers.internal_docs] identity = { url = "https://mcp.example.com/docs" } -
按可执行文件和位置参数添加已批准的 stdio 服务器:
[mcp_servers.internal_build.identity] command = { executable = "/usr/local/bin/company-mcp", args = [ { match = "exact", value = "serve" }, { match = "prefix", value = "--workspace=" }, ] }结构化匹配器检查可执行文件、参数数量和参数顺序,但不限制
cwd、env或env_vars。批准 stdio 服务器的前提是能够控制其完整的启动上下文。请保护其可执行文件和依赖项,并防止不受信任的用户配置或项目配置提供可改变其行为的工作目录或环境。如果无法独立实施这一限制,请勿批准该 stdio 服务器,改用经过审查的 HTTP 服务器。 -
在
plugins.<plugin>.mcp_servers.<server>下单独添加插件自带的 MCP 服务器身份。 -
将已批准的列表存放在实施变更审查的配置代码仓库中,并通过管理员强制实施的要求部署该列表。
只有当服务器的名称和身份均与某个已批准条目匹配时,客户端才会启用该服务器。请参阅托管配置。
验证
-
严格按照已批准的条目配置服务器。预期结果:服务器启动。
-
更改 URL 中的一个字符。预期结果:服务器被禁用。
-
更改 stdio 参数的数量或顺序,或提供不符合已配置参数规则的参数。预期结果:服务器被禁用。仍符合允许前缀的值依然可以使用。
-
在一次性的受信任项目中,保持可执行文件和参数匹配,尝试用无害的值覆盖
cwd、env和env_vars。仅凭身份匹配不会拒绝这些覆盖设置。请验证独立的启动上下文控制措施会拒绝不安全的覆盖设置,或确认该 stdio 服务器仍未获批准。不要使用真实的注入载荷。 -
添加一个未经批准的名称。预期结果:服务器被禁用。
-
测试插件自带的服务器。预期结果:服务器仅在使用已批准的身份时才能工作。
回滚
移除新添加的条目。要立即停止使用所有 MCP 服务器,请部署空的 mcp_servers 表。
适用边界
将身份列入允许列表并不能证明服务器的工具、上游数据、凭据或启动环境安全。本地 stdio MCP 进程在本地命令沙盒之外运行。匹配可执行文件和参数无法限制服务器的访问权限,也无法阻止其根据环境设置加载代码。请独立审查完整的启动上下文和服务器权限。请参阅MCP 身份要求。
如果安全团队需要了解 Codex 在终端和网络中的活动,请使用此方案。它将运行事件、工具事件、审批决定、工作空间审计记录和网络日志汇集起来,供团队调查。
预期结果
安全团队可以关联 Codex 运行记录、工具使用决定、审批记录、工作空间审计记录和实际的出站网络活动,无需依赖模型对自身行为的描述。
使用四种证据来源
-
Codex OpenTelemetry:运行、API、模型、沙盒、审批和工具事件。
-
托管生命周期钩子:在终端侧记录工具使用和权限请求。
-
网络代理或网关日志:实际的 DNS/HTTP 请求目标和连接结果。
-
合规 API:工作空间级别的审计和调查记录。
单一来源无法全面监控网络活动。
配置
-
将 Codex OpenTelemetry 日志发送到您的收集器,并从日志中排除原始提示词:
[otel] environment = "enterprise" log_user_prompt = false [otel.exporter.otlp-http] endpoint = "https://otel.example.com/v1/logs" protocol = "binary" headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }启动客户端之前,通过已批准的机密管理器或进程环境向 Codex 进程提供
OTLP_TOKEN。不要将令牌写入部署的 TOML 文件或纳入源代码管理。Codex 可以输出会话开始事件、API 请求、流式传输事件、提示词元数据、工具使用决定和工具结果。请参阅高级配置。
-
在项目本地配置之外部署 OTel。项目中的
.codex/config.toml文件无法覆盖遥测数据的路由设置。 -
为
SessionStart、PreToolUse、PermissionRequest、PostToolUse、Stop和SessionEnd添加托管生命周期钩子。 -
将钩子脚本安装在管理员管理的目录中。如果需要忽略用户、项目和插件钩子,请设置
allow_managed_hooks_only = true。 -
让沙盒内命令的流量经过独立记录日志的代理。OTel 记录工具的运行事件,代理记录子进程尝试连接的位置。
-
为网页搜索、应用、连接器、MCP 服务器、浏览器活动和 Codex 云端单独配置遥测。本地命令代理规则不会自动覆盖这些活动。
-
将合规 API 支持的记录持续传入 SIEM,并实施您自己的数据保留和法律保全措施。请参阅合规 API 和审计事件。
-
关联用户或服务账户、主机或运行器、会话 ID、模型、客户端版本、权限配置文件、审批决定、访问目标和工具名称。
验证
运行一个受控会话,执行以下操作:
-
读取一个允许访问的文件。
-
尝试读取一个禁止访问的文件。
-
运行一条允许的命令。
-
尝试发起一个会被阻止的出站请求。
-
请求审批,并收到拒绝决定。
-
结束会话。
各证据来源的预期结果如下:
-
OTel 显示运行事件和工具事件。
-
钩子记录显示会话的生命周期。
-
代理日志显示允许访问和被阻止的目标。
-
合规数据采集流程收到受支持的记录。
-
SIEM 将这些记录与相应的用户或工作负载关联起来。
回滚
恢复之前的配置,以禁用导出器和钩子。回滚遥测配置时,不要移除独立的代理日志记录功能。
适用边界
不要承诺 Codex 遥测能捕获每个命令参数、每个输出字节或每个网络数据包。请记录各层的覆盖范围。
如果 Codex 不应访问互联网,或只能访问已批准的目标,请使用此方案。请根据要配置的环境选择本地或云端步骤,并注意两者的策略适用范围不同。
预期结果
根据您选择的配置,Codex 无法访问互联网,或只能访问已批准的域名。Codex 云端(旧版)环境还可以限制 HTTP 方法。
配置当前版本的 Codex 云端
-
为不同的信任级别创建独立环境,例如 no-internet-review、approved-dependencies-build 和 cyber-lab。
-
在环境配置中关闭启用所有公共互联网访问和启用软件包管理器域名。
-
如果需要访问公共互联网,请在其他允许的域名下添加已批准主机的确切名称。移除允许访问未经批准的公共目标的 HTTP 机密。要阻止在 VPN 之外访问公共互联网,请将该列表留空,并移除允许访问公共目标的 HTTP 机密。
-
保存配置,并在设置阶段测试服务。发布或重新发布环境,然后在新任务中测试对已批准和未经批准目标的访问。请单独审查设置脚本,固定依赖项版本,优先使用已批准的镜像,并避免下载未经审查的可执行文件。
请参阅连接到服务。当前版本的 Codex 云端设置不提供旧版的 HTTP 方法选择器。
配置 Codex 云端(旧版)
-
不需要智能体访问互联网时,请保持该设置为关闭。旧版云端默认在智能体运行阶段阻止互联网访问,但设置脚本仍可访问互联网以安装依赖项。
-
如果智能体需要访问互联网,请将设置切换为开启,并严格限制允许列表的范围。先选择无,再添加确切的域名。
-
对于只需下载的工作流,仅允许
GET、HEAD和OPTIONS。这样会阻止POST、PUT、PATCH、DELETE和其他方法。请单独审查设置脚本,因为智能体运行阶段的限制不适用于这些脚本的互联网访问。
请参阅旧版智能体互联网访问。这些预设选项和 HTTP 方法控制仅适用于旧版云端。
配置本地 Codex
-
在管理员管理的
requirements.toml中定义并选用已批准的网络权限配置文件,并限制用户只能使用该配置文件:default_permissions = "corp-build" [allowed_permission_profiles] "corp-build" = true [permissions.corp-build] description = "Workspace access with approved dependency destinations." extends = ":workspace" [permissions.corp-build.network] enabled = true allow_local_binding = false [permissions.corp-build.network.domains] "registry.npmjs.org" = "allow" "pypi.org" = "allow" "files.pythonhosted.org" = "allow" -
按照托管配置部署经过审查的要求配置包。仅定义具名配置文件不会使其生效。
default_permissions用于选用该配置文件,允许列表则防止用户选择其他配置文件。 -
在同一要求配置包中启用管理员管理的代理,以强制实施域名限制,并防止用户扩大允许访问的范围。请同时部署代理和启用网络的权限配置文件。如果代理未启用,启用网络的配置文件将允许直接访问网络,而不会强制执行其中的域名规则:
注意:
[experimental_network]是实验性设置,可能会发生变化。在扩大部署范围之前,请在每个受支持的本地客户端版本和操作系统上验证其效果。对 Windows 的支持有限。在您的环境中测试并确认策略得到强制执行之前,请勿将其应用于 Windows 用户。[experimental_network] enabled = true managed_allowed_domains_only = true [experimental_network.domains] "registry.npmjs.org" = "allow" "pypi.org" = "allow" "files.pythonhosted.org" = "allow" -
除非工作流需要,否则请保持本地端口绑定关闭。请单独配置对专用网络目标的访问。允许访问某个域名并不等于批准访问该域名对应的私有地址。请参阅网络访问要求。
-
请单独配置网页搜索、应用、MCP 服务器、浏览器活动和 Codex 云端。本地沙盒规则不控制这些活动。
验证
-
向已批准的域名发送请求,确认请求成功。
-
向未经批准的域名发送请求,确认请求被阻止。
-
分别向 localhost、私有 IP 地址和云端元数据端点发送请求。确认每个请求都会被阻止,除非已获得明确批准。
-
在 Codex 云端(旧版)中,尝试向允许访问的域名发送
POST请求。确认仅允许GET、HEAD和OPTIONS时,该请求会被阻止。 -
确认代理或网关日志同时包含允许和拒绝的请求记录。
回滚
将环境的互联网访问设置恢复为关闭,或恢复之前的域名策略。避免回滚到不受限制的互联网访问状态。
适用边界
获批在完全解除沙盒限制的情况下执行的命令可以绕过本地命令代理。在依赖此限制之前,请分别测试在沙盒内运行的普通命令和获批在沙盒外运行的命令。
即使域名获准访问,它仍可能托管包含提示词注入的内容、遭到篡改的软件包或不安全的文档。
如果 Codex 需要访问已批准的源代码目录,但不应接触机密信息、.env 文件、SSH 密钥和无关代码仓库,请使用此方案。它介绍如何限制文件访问,并减少传递给新启动命令的含凭据环境变量。
预期结果
Codex 可以在已批准的源代码目录中工作,但无法读取常见的含机密信息文件,也不会继承大量含凭据的环境变量。
配置
-
在工作空间权限配置文件中定义禁止读取的路径模式:
[permissions.corp-workspace] description = "Workspace edits with secret-bearing paths denied." extends = ":workspace" [permissions.corp-workspace.filesystem] glob_scan_max_depth = 6 [permissions.corp-workspace.filesystem.":workspace_roots"] "**/.env*" = "deny" "**/*.pem" = "deny" "**/*.p12" = "deny" "**/id_*" = "deny" "**/.aws/**" = "deny" "**/.kube/**" = "deny" -
将已知凭据目录、签名密钥、生产配置和相邻代码仓库的确切路径加入禁止访问的范围。
-
在系统的
/etc/codex/config.toml或用户的~/.codex/config.toml中,减少传递给新启动命令的环境变量:[shell_environment_policy] inherit = "core" ignore_default_excludes = false [shell_environment_policy.filters] "AWS_*" = "exclude" "AZURE_*" = "exclude" "GITHUB_*" = "exclude" "*_TOKEN" = "exclude" "*_SECRET" = "exclude" "*_PASSWORD" = "exclude"这是用户可配置的默认设置,不具备强制约束力。它能减少继承的变量,但不能阻止访问凭据文件、凭据辅助程序、shell 启动时加载的内容或其他身份。请参阅高级配置。
-
在管理员管理的
requirements.toml中选用受限配置文件,并仅允许使用该配置文件。内置配置文件不会继承其中针对机密文件的禁止读取规则:default_permissions = "corp-workspace" [allowed_permission_profiles] "corp-workspace" = true ":danger-full-access" = false -
为您的云端环境选择凭据传递方式:
-
如果智能体需要进行身份验证,请使用独立的凭据代理提供短期凭据,并将其权限限定到具体目标和操作。请参阅推荐配置。
验证
创建以下无害的测试文件:
.env.test
test-key.pem
.aws/credentials
.kube/config然后让 Codex 执行以下操作:
-
读取一个普通文件。
-
读取每个测试文件。
-
递归搜索机密信息。
-
打印命令运行时的环境变量。
-
读取相邻的代码仓库。
预期结果:普通文件读取成功,禁止访问的文件和相邻代码仓库仍无法访问,被排除的变量未出现在命令环境中。
回滚
恢复之前的权限配置文件,但在调查工作流失败的原因时,保留已确认应禁止读取的机密文件规则。
适用边界
文件系统的禁止访问规则无法移除已粘贴到提示词中、已提交到可读源代码中、由连接器返回或已写入模型可访问日志的机密信息。
如果 git push、部署、数据库迁移和云端 CLI 命令等操作需要先获批才能执行,请使用此方案。先决定哪些命令需要请求审查、哪些必须禁止,再为这些命令配置规则。
预期结果
即使模型认为执行敏感命令是合适的,命令也会按规则暂停以等待审批,或被禁止执行。
配置
- 确定哪些命令需要提示审批,哪些命令禁止执行。
| 命令类别 | 处理方式 |
|---|---|
git push、git commit |
提示审批 |
terraform apply |
提示审批 |
kubectl apply/delete/patch |
提示审批 |
| 数据库迁移 | 提示审批 |
| 破坏性主机命令 | 禁止执行 |
-
添加管理员强制实施的命令规则:
[rules] prefix_rules = [ { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating shared Git state." }, { pattern = [{ token = "terraform" }, { token = "apply" }], decision = "prompt", justification = "Require review before infrastructure changes." }, { pattern = [{ token = "kubectl" }, { any_of = ["apply", "delete", "patch"] }], decision = "prompt", justification = "Require review before Kubernetes changes." }, { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Destructive removal is not permitted in managed Codex workflows." }, ]托管要求中的规则可以要求提示审批或禁止命令,但不能用于放行命令。请参阅托管配置。
-
对于高风险权限配置文件,如果 shell 包装命令可能掩盖其中的敏感命令,请在同一
prefix_rules数组中添加以下条目:{ pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Review shell wrappers that could obscure sensitive commands." },此条目可能会触发大量审批提示,请按需使用。
-
如果命令必须由人工审批,请强制实施以下设置:
allowed_approval_policies = ["on-request", "untrusted"] allowed_approvals_reviewers = ["user"]自动审查会改变审查方,但无法提供确定性的安全保证。请参阅自动审查。
-
将 PermissionRequest、工具使用决定和工具结果事件发送到安全事件处理系统。
验证
-
运行
git status。预期结果:不出现审批提示。 -
运行
git push。预期结果:出现审批提示。 -
运行
terraform apply。预期结果:出现审批提示。 -
运行
kubectl delete pod test。预期结果:出现审批提示。 -
运行
rm -rf test-directory。预期结果:命令被禁止执行。 -
拒绝一个审批请求。预期结果:命令未运行,拒绝决定已记入日志。
-
重启客户端并重复检查。预期结果:规则仍得到强制执行。
回滚
恢复之前的要求配置包。如果某个命令词匹配模式范围过宽,请缩小其范围,避免移除对整类敏感命令的限制。
适用边界
前缀规则无法提供完整的操作系统策略控制。请结合沙盒、遵循最小权限原则的操作系统账户、网络限制、云端 IAM、分支保护、部署审批和数据库授权使用这些规则。
面向企业安全目标的组合方案
以下示例介绍如何组合多项控制措施,实现常见的企业安全目标。请在管理范围内的每种客户端和环境中测试配置。
**使用的单项配置方案:**限制权限配置文件和完全访问权限、保护密钥等机密信息和无关代码仓库、要求对敏感命令进行审批。
开发者拥有合法的生产环境访问权限,但您希望 Codex 协助开发时,不会对生产环境进行未经审查的更改。
-
定义已批准的工作空间权限配置文件,并强制限定允许使用的权限配置文件和审批策略。将这些设置作为管理员强制实施的要求下发,防止用户覆盖。
-
使用单独的低权限身份运行 Codex,或在无法访问或获取生产环境写入凭据的环境中运行它。开发者可以通过单独授权的工作流继续访问生产环境。
-
尽量减少传递给新启动命令的环境变量。如果智能体需要进行身份验证,请使用独立的凭据代理提供短期凭据,并将其权限限定到具体目标和操作。
-
确定哪些命令需要提示审批,哪些禁止执行。对于选定的高影响命令,例如
git push、terraform apply、Kubernetes 更改和数据库迁移,要求人工审批。对于绝不能运行的命令,禁止执行。 -
在 Codex 之外独立强制实施生产环境 IAM、分支保护和部署审批。
限制权限配置文件并要求人工审查
在管理员管理的 requirements.toml 中,允许使用内置的工作空间和只读权限配置文件,并要求用户审查需要审批的操作:
allowed_approval_policies = ["on-request"]
allowed_approvals_reviewers = ["user"]
default_permissions = ":workspace"
[allowed_permission_profiles]
":read-only" = true
":workspace" = true工作空间权限配置文件允许在其沙盒内对工作空间执行操作。只读配置文件适合权限范围更小的任务。授予完全访问权限的配置文件未列入允许列表。
如果客户端需要明确指定兼容的策略,请在客户端配置中设置 approval_policy = "on-request"。on-request 允许在需要时提示审批,并不会对每条命令都给出提示。请为需要审查的操作添加明确的规则,并保留独立的生产环境授权机制。
托管权限配置文件允许列表需要 Codex 0.138.0 或更高版本。对于较旧的客户端,请使用并测试文档中介绍的旧版沙盒模式要求。
重启每个试点客户端,验证已批准的权限配置文件可以使用,并确认不允许使用的完全访问权限配置文件会被拒绝。
将 Codex 身份与生产环境凭据隔离
在设备管理或开发环境预配系统中,为 Codex 创建专用用户、容器或开发主机,仅允许其访问所需的源代码和开发服务。不要将开发者的生产环境凭据文件、令牌辅助程序或钥匙串挂载到该环境,并阻止该身份获得具有生产环境写入权限的角色。
如果智能体需要访问服务,请配置组织的凭据代理,使其签发仅适用于相应开发资源和操作的短期凭据。开发者可以通过单独授权的生产环境工作流使用其常规身份。
例如,在 AWS IAM 中打开角色,选择 Codex 开发角色,然后在权限下添加类似以下示例的、经过审查的内联策略。请将账户和角色替换为您自己的值:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyAssumeExampleProductionRole",
"Effect": "Deny",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/ExampleProductionRole"
}
]
}此示例仅拒绝代入指定角色的请求。还应移除直接授予的生产环境权限,限制其他生产角色和凭据来源,并审查信任策略及组织级控制措施。
在不更改生产环境的情况下,选取有代表性的开发和生产环境权限,测试开发角色是否具备相应权限。请参阅 AWS IAM 角色策略示例。
尽量减少 shell 环境变量
要设置系统范围的初始配置,请使用 /etc/codex/config.toml。要为单个用户配置,请使用 ~/.codex/config.toml。在相应文件中配置新启动的命令可以继承哪些环境变量:
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false
[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"
"GITHUB_*" = "exclude"
"*_TOKEN" = "exclude"
"*_SECRET" = "exclude"
"*_PASSWORD" = "exclude"这是可调整的默认设置,不能强制隔离凭据。用户设置、shell 启动时加载的内容或快照、凭据辅助程序以及其他凭据来源仍可能暴露凭据。
如果与您的工作流兼容,可以在 requirements.toml 中使用以下可选限制来禁用登录 shell 和 shell 快照:
allow_login_shell = false
[features]
shell_snapshot = false请先试行这些设置,因为某些工作流依赖登录 shell 的初始化过程。
使用符合过滤规则的无害模拟变量启动 Codex,并检查新启动命令的环境。如果已禁用登录 shell,还应验证登录 shell 请求会被拒绝。请另行验证执行命令的身份无法访问真实的生产环境凭据。请参阅 shell 环境策略。
对选定的高影响命令提示审批
为组织使用的命令添加强制规则。例如:
[rules]
prefix_rules = [
{ pattern = [{ token = "git" }, { token = "push" }], decision = "prompt", justification = "Review Git pushes." },
{ pattern = [{ token = "terraform" }, { token = "apply" }], decision = "prompt", justification = "Review infrastructure changes." },
{ pattern = [{ token = "kubectl" }, { any_of = ["apply", "delete", "patch"] }], decision = "prompt", justification = "Review cluster changes." },
{ pattern = [{ token = "python3" }, { token = "manage.py" }, { token = "migrate" }], decision = "prompt", justification = "Review database migrations." },
]对于绝不能运行的命令,请使用 forbidden。根据实际使用的部署和迁移工具替换或添加匹配模式。
这些规则匹配命令前缀,无法覆盖所有具有同等效果的操作。请分别测试绝对路径、包装命令、不同参数顺序、其他客户端和其他工具。
在一次性测试目标上运行一条常规命令,然后请求执行规则中列出的某项操作,拒绝审批请求,并确认该操作未执行。请参阅强制实施命令规则。
在 Codex 之外强制实施代码仓库和部署审批
在源代码管理平台中保护 main 等生产分支,要求变更经过审查、获得必要的批准并通过必要的状态检查,同时审查哪些角色可以绕过这些要求。在相应的部署系统中配置部署审批,并在数据库本身配置数据库权限。
使用一次性测试代码仓库验证经过审查的变更可以应用,而未经授权的直接推送会被拒绝。无论操作是否通过 Codex 发起,这些控制措施都适用。
验证
在一次性测试目标上执行以下检查:
-
运行常规工作空间任务。预期结果:任务成功。
-
尝试运行一条有代表性的敏感命令,并拒绝审批请求。预期结果:被拒绝的命令未运行。
-
验证 Codex 身份无法获得生产环境写入权限。
-
重启客户端并重复检查。
适用边界
前缀规则无法提供完整的操作系统策略控制。请结合沙盒、遵循最小权限原则的操作系统账户、网络限制、云端 IAM、分支保护、部署审批和数据库授权使用这些规则。
**使用的单项配置方案:**保护密钥等机密信息和无关代码仓库、限制网络访问目标、仅允许已批准的 MCP 服务器、要求对敏感命令进行审批。
开发者在内部代码仓库中使用 Codex,而您希望降低代码被发送到公共代码仓库、作为公开代码片段发布或发送到其他未经批准目标的风险。
-
将已知凭据目录和无关代码仓库的确切路径加入禁止访问的范围,并尽量减少传递给新启动命令的环境变量。
-
当智能体需要访问互联网时,请将允许列表严格限定为已批准的域名。仅允许已批准的 MCP 服务器名称和身份,并对
git push等选定的发布命令要求审查或禁止执行。 -
使用源代码管理钩子和权限、针对公共代码仓库和公开代码片段的策略,以及适合组织的数据防泄漏措施。
禁止访问无关代码仓库和凭据文件
在管理员管理的 requirements.toml 中添加本地智能体禁止读取的确切路径:
[permissions.filesystem]
deny_read = ["~/.ssh", "~/.aws/credentials", "~/.kube/config", "/work/unrelated-repository"]将示例替换为托管设备上实际存在的路径。这项托管限制对所有允许使用的权限配置文件生效。如果只在某个自定义配置文件中禁止读取,选择其他配置文件的用户将不受这项保护。优先使用已知的确切路径。如果使用通配符模式,请在所需的目录深度上进行测试。
在原生 Windows 环境中,托管的 deny_read 适用于直接访问文件的工具,但仅凭此项设置无法阻止 shell 子进程读取文件。请同时使用操作系统身份和文件访问控制列表。
在禁止访问的位置创建无害的测试文件。逐一使用每个允许的权限配置文件,验证直接读取和通过 shell 读取这些文件都会被拒绝,同时确认已批准的源文件可以读取。请参阅托管的禁止读取要求。
尽量减少含凭据的 shell 变量
在 /etc/codex/config.toml 或 ~/.codex/config.toml 中限制可继承的环境变量:
[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false
[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"
"GITHUB_*" = "exclude"
"*_TOKEN" = "exclude"
"*_SECRET" = "exclude"
"*_PASSWORD" = "exclude"此设置可以减少继承的变量,但用户可以自行配置。它无法阻止访问凭据文件、凭据辅助程序、shell 启动时加载的内容或其他身份。
在适用的情况下,管理员还可以将以下限制添加到 requirements.toml 中,先试行,再评估它们对开发者工作流的影响:
allow_login_shell = false
[features]
shell_snapshot = false请使用模拟测试变量和独立的最小权限执行身份进行测试。不要使用真实凭据。请参阅 shell 环境策略。
仅允许本地命令访问已批准的网络目标
如果本地沙盒中的命令需要访问网络,请将下面的权限配置文件和托管代理设置一并合并到 requirements.toml 中,并将域名替换为已批准的端点:
default_permissions = "corp_network"
[allowed_permission_profiles]
corp_network = true
[permissions.corp_network]
extends = ":workspace"
[permissions.corp_network.network]
enabled = true
[experimental_network]
enabled = true
managed_allowed_domains_only = true
[experimental_network.domains]
"git.corp.example" = "allow"
"registry.corp.example" = "allow"启用网络的权限配置文件为沙盒命令提供网络通路,托管代理则限制命令可以访问的目标。请同时部署两者。如果没有配置预期的托管代理,启用网络的配置文件不会实施相同的目标限制。如果无需访问互联网,请保持网络访问禁用。
不要将标准的 domains 表与旧版 allowed_domains 或 denied_domains 设置混用。请迁移现有策略并进行测试。
重启客户端,验证已批准的端点可以访问,未经批准的端点会被阻止。
这些设置仍处于实验阶段。请验证操作系统和客户端是否支持这些设置。如果已批准的主机解析为私有地址,请单独配置专用网络访问。获批在完全解除沙盒限制的情况下执行的命令可以绕过命令代理。
此项本地命令网络控制本身不覆盖网页搜索、应用、MCP 服务器、浏览器活动或云端环境,需要为它们单独配置策略。已批准的托管服务域名也可能包含公共代码仓库或公开代码片段,因此仅靠访问目标允许列表无法保护内容。请参阅网络访问要求。
单独配置云端环境的网络访问
在当前版本的 Codex 云端界面中打开环境配置。关闭启用所有公共互联网访问和启用软件包管理器域名。如果需要访问公共互联网,请在其他允许的域名下添加已批准主机的确切名称。移除允许访问未经批准的公共目标的 HTTP 机密。要阻止在 VPN 之外访问公共互联网,请将该列表留空,并移除允许访问公共目标的 HTTP 机密。保存配置,发布或重新发布环境,然后运行一个新任务进行测试。
请独立审查服务的身份验证方式和功能。
旧版 Codex 云端为每个环境单独提供智能体互联网访问设置,可以限制允许访问的域名和 HTTP 方法。设置脚本有各自的访问规则。
请测试您实际使用的环境版本。请参阅连接到服务和旧版互联网设置。
限制 MCP 服务器并在 Git 推送前提示审批
在 requirements.toml 中仅允许已批准的本地 MCP 服务器身份。例如:
[mcp_servers.internal]
identity = { url = "https://mcp.corp.example/mcp" }在用户配置或托管默认配置的 config.toml 中单独配置实际的服务器,使用匹配的名称和 URL,并配置服务器所需的身份验证:
[mcp_servers.internal]
url = "https://mcp.corp.example/mcp"该要求只允许使用与之匹配的服务器,不会创建服务器配置。请审查该服务器自身的访问权限和工具。
验证已批准的服务器能够连接,而使用其他名称或 URL 的服务器不被允许。
添加托管命令规则,在执行有代表性的发布命令之前请求审查:
[rules]
prefix_rules = [
{ pattern = [{ token = "git" }, { token = "push" }], decision = "prompt", justification = "Review the destination before publishing." },
]如果必须由人工审查,请同时将 allowed_approval_policies = ["on-request"] 和 allowed_approvals_reviewers = ["user"] 设为顶层要求。
拒绝一次测试推送,确认推送未执行。
前缀匹配无法覆盖所有包装命令、API 客户端、应用或其他发布途径。
使用源代码管理和 DLP 措施限制公开发布
在源代码管理平台支持的范围内,限制创建公共代码仓库,并限定哪些用户可以更改代码仓库的可见性。请审查特权用户绕过限制的权限。组织设置无法管控所有发布目标,因此还要单独检查个人账户、代码片段、外部组织和令牌访问权限。
在相关代码仓库中要求变更经过审查,并检查分支保护和绕过限制的权限。
在组织的数据防泄漏(DLP)控制台中,针对敏感源代码内容和 DLP 产品实际覆盖的上传或代码仓库渠道配置试点策略。将处理方式设为阻止,并使用无实际作用的模拟标记进行测试。
如果源代码管理平台支持服务器端控制,请为接收推送的代码仓库配置经过审查的钩子,并强制执行。
使用获准用于测试的目标,并确认操作在内容发布之前被阻止。
验证
-
创建无害的测试文件,并确认尝试读取禁止访问的文件时会失败。
-
如果已启用网络访问,请检查是否能成功访问已批准的目标,以及对未经批准目标的访问是否被阻止。如果网络访问已禁用,请验证网络请求会被阻止。
-
使用无害的标记和一次性测试账户或目标,验证有代表性的公开发布操作在内容发布之前就会被阻止。
适用边界
获准访问的域名仍可能托管公开内容。请单独配置网页搜索、应用、MCP 服务器、浏览器活动和 Codex 云端。本地沙盒规则不控制这些活动。
**使用的单项配置方案:**限制权限配置文件和完全访问权限、仅允许已批准的 MCP 服务器、限制网络访问目标、保护密钥等机密信息和无关代码仓库、要求对敏感命令进行审批。
您希望 Codex 在代码仓库中工作时,或用户更改本地配置后,对 Codex 的限制仍然有效。
-
将受支持的权限、审批、MCP、网络和命令限制作为管理员强制实施的要求下发。
-
将钩子脚本安装在管理员管理的目录中。如果应忽略用户、项目和插件钩子,请设置为仅使用托管钩子。
-
使用操作系统和设备管理控制措施保护策略文件及配置分发途径。运行 Codex 的身份不应具备修改这些防护措施所需的权限。
-
审查管理范围内每种客户端和环境实际生效的配置。
强制限定允许的权限配置文件、审批方式、服务器身份和命令
将经过审查的设置合并到管理员管理的 requirements.toml 中,避免依赖用户或代码仓库中可编辑的设置。例如:
allowed_approval_policies = ["on-request"]
allowed_approvals_reviewers = ["user"]
default_permissions = ":workspace"
[allowed_permission_profiles]
":read-only" = true
":workspace" = true
[mcp_servers.internal]
identity = { url = "https://mcp.corp.example/mcp" }
[rules]
prefix_rules = [
{ pattern = [{ token = "git" }, { token = "push" }], decision = "prompt", justification = "Review Git pushes." },
]此示例允许使用两种权限配置文件,在需要审批时要求人工审查,允许匹配的 MCP 身份,并对具有指定前缀的命令提示审批。
请单独配置 MCP 服务器本身,并添加组织内其他敏感命令的匹配模式。根据需要添加全局文件限制和网络限制。托管要求可以约束受支持的设置,但不能替代 Codex 之外针对身份、服务和访问目标的控制措施。
托管权限配置文件允许列表需要 Codex 0.138.0 或更高版本。
在试点客户端上尝试选择不允许的权限配置文件、更改受限的用户或项目设置,以及使用未列入允许列表的 MCP 身份。验证每项尝试都被拒绝,或在重启后仍受限制。拒绝一次测试命令的审批请求,并确认命令未运行。
添加托管文件系统和网络限制
要在所有允许使用的权限配置文件中禁止读取敏感本地文件,请将下表添加到 requirements.toml,并将示例路径替换为组织实际使用的路径:
[permissions.filesystem]
deny_read = ["~/.ssh", "~/.aws/credentials", "~/.kube/config"]如果本地沙盒命令需要访问网络,请同时定义一个允许使用且已启用网络的权限配置文件,以及由管理员管理的访问目标:
default_permissions = "corp_network"
[allowed_permission_profiles]
corp_network = true
[permissions.corp_network]
extends = ":workspace"
[permissions.corp_network.network]
enabled = true
[experimental_network]
enabled = true
managed_allowed_domains_only = true
[experimental_network.domains]
"git.corp.example" = "allow"可以选择此配置文件策略来替换前面的 :workspace 默认配置,也可以按需将两个配置文件名称合并到同一策略中。不要粘贴重复的键或表。如果命令不需要访问网络,请保持网络访问禁用。
使用无害文件验证禁止访问的确切路径,并分别验证对已批准和未经批准目标的访问结果。
在原生 Windows 环境中,还应使用文件访问控制列表,因为仅靠托管的 deny_read 无法限制 shell 子进程读取文件。
本地命令的网络设置不控制其他客户端、应用、连接器或云端执行的活动。
安装并强制使用管理员管理的钩子
请管理员将经过审查的钩子程序安装到由 root 管理的目录中,例如安装到 /etc/codex/hooks/pre_tool_use_policy.py,并防止运行 Codex 的用户修改该文件或其所在目录。在 requirements.toml 中启用钩子,并忽略用户、项目、会话和插件钩子:
allow_managed_hooks_only = true
[features]
hooks = true
[hooks]
managed_dir = "/etc/codex/hooks"
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "/usr/bin/python3 /etc/codex/hooks/pre_tool_use_policy.py"
timeout = 30
statusMessage = "Checking managed Bash command"此要求只负责注册钩子。请由管理员使用下方的命令安装所选文件。
要在本地 macOS 上进行集成测试,请将 Python 版本保存为 pre_tool_use_policy.py。
在 Go 模块中将 Go 版本保存为 main.go,然后运行 go build -o pre_tool_use_policy . 进行编译。请管理员将生成的可执行文件安装到 /etc/codex/hooks/pre_tool_use_policy,将文件所有者设为 root,权限设为 755,并将钩子的 command 设为该绝对路径。Go 版本仅使用标准库,运行时无需解释器。
要在本地 macOS 上进行集成测试,请将 Ruby 版本保存为 pre_tool_use_policy.rb。将钩子的 command 设置为 /usr/bin/ruby /etc/codex/hooks/pre_tool_use_policy.rb。如有需要,请将 /usr/bin/ruby 替换为您的 Ruby 解释器的绝对路径。Ruby 钩子仅使用标准库。
此程序仅阻止包含模拟标记的命令。用于实际防护前,请将其替换为经过审查、适合您组织的策略。请确认目标设备上存在配置中指定的可执行文件,以及运行该版本所需的任何解释器。钩子的启动命令必须与所选语言匹配:
1
2
3
4
5
6
7
8import json
import sys
event = json.load(sys.stdin)
command = event.get("tool_input", {}).get("command", "")
if "CODEX_HOOK_TEST_DENY" in command:
print("Synthetic test command blocked by managed hook.", file=sys.stderr)
sys.exit(2)1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26package main
import (
"encoding/json"
"fmt"
"io"
"os"
"strings"
)
func main() {
var event struct {
ToolInput struct {
Command string `json:"command"`
} `json:"tool_input"`
}
decoder := json.NewDecoder(io.LimitReader(os.Stdin, 1<<20))
if err := decoder.Decode(&event); err != nil {
fmt.Fprintln(os.Stderr, "Invalid hook event.")
os.Exit(2)
}
if strings.Contains(event.ToolInput.Command, "CODEX_HOOK_TEST_DENY") {
fmt.Fprintln(os.Stderr, "Synthetic test command blocked by managed hook.")
os.Exit(2)
}
}1
2
3
4
5
6
7
8require "json"
event = JSON.parse($stdin.read)
command = event.fetch("tool_input", {}).fetch("command", "")
if command.include?("CODEX_HOOK_TEST_DENY")
warn "Synthetic test command blocked by managed hook."
exit 2
endsudo install -d -o root -g wheel -m 755 /etc/codex/hooks
sudo install -o root -g wheel -m 644 ./pre_tool_use_policy.py /etc/codex/hooks/pre_tool_use_policy.py如果使用 Ruby,请将安装命令中两处路径里的 pre_tool_use_policy.py 均替换为 pre_tool_use_policy.rb,保持文件归 root 所有,并沿用相同的权限。
重启本地客户端,然后执行以下检查:
-
确认无害的 Bash 命令可以运行。
-
确认包含
CODEX_HOOK_TEST_DENY的命令会被阻止。 -
验证运行 Codex 的用户无法修改策略及其依赖项。
allow_managed_hooks_only 会跳过所有非托管的用户、项目、会话和插件钩子,可能会影响其他工作流。
Bash 匹配器无法覆盖所有工具,也无法覆盖之后传给现有进程的输入。出现错误、超时或钩子响应格式不正确时,工具调用仍可能继续执行。
由云端编排的工作模式支持的钩子处理程序有所不同。请保留独立的操作系统和服务防护措施。请参阅托管钩子和钩子行为。
保护策略及其分发途径
在 macOS 上,管理员可以将经过审查和合并的要求文件部署到归 root 所有的父目录中,并禁止运行 Codex 的用户写入该文件:
sudo install -d -o root -g wheel -m 755 /etc/codex
sudo install -o root -g wheel -m 644 ./requirements.reviewed.toml /etc/codex/requirements.toml
ls -ld /etc/codex
ls -l /etc/codex/requirements.toml在 Linux 上,请使用适当的管理员组。在 Windows 上,请使用管理员管理的访问控制列表保护 ProgramData 目录和文件。请限定哪些人员可以更改 MDM 或云端策略,审查变更,并保留用于回滚的副本。
使用非管理员试点账户,验证该账户无法修改策略、父目录或托管钩子程序。尝试使用限制较弱的用户或项目设置,重启 Codex,并验证强制要求仍然生效。
请测试管理范围内的每种客户端和环境,不要假设所有客户端都会加载相同的策略。
验证
使用非管理员测试身份执行以下检查:
-
尝试编辑托管策略。预期结果:无法更改托管文件。
-
尝试通过用户或项目配置放宽限制。预期结果:较宽松的设置被拒绝,或仍受强制要求约束。
-
重启客户端并验证限制仍然生效。
适用边界
如果用户或智能体拥有足够的主机管理员权限,就可能更改外围防护措施。仅靠用户可编辑的设置无法替代管理员管理的要求。