什么是权限配置文件
Codex 的文档用两句话定义了它:“权限配置文件允许你对 Codex 代表你运行的本地命令应用最小权限边界。配置文件是一个命名策略,它结合了定义命令可以读取或写入什么的文件系统规则,以及定义命令可以到达哪些目的地的网络规则。”
关键词是命令。配置文件管理 Codex 在你的机器上运行的 shell 命令,例如测试、构建、脚本和包安装。文档给出了两个例子来说明这如何提供帮助:“只读配置文件可以允许 Codex 在不编辑的情况下检查项目,而具备写入能力的配置文件可以将编辑限制在选定的工作区根目录。”
配置文件适用于 macOS、Linux、WSL 和原生 Windows。每个平台强制执行它们的方式不同,文档指出在 macOS 上有一个值得注意的行为:“如果选定的策略无法由平台沙箱强制执行,Codex 将拒绝运行该命令,而不是在无沙箱的情况下静默运行。”
三个内置配置文件
Codex 附带了三个无需定义即可使用的配置文件:
:read-only保持本地命令执行为只读。:workspace允许在活动工作区根目录和系统临时目录内进行写入。:danger-full-access移除本地沙箱限制。文档称其“仅应在有意进行广泛访问时使用”。
要使用其中一个,请将 default_permissions 设置为其名称。要构建自己的配置文件,请在 permissions 下创建一个命名表,并将 default_permissions 指向它。文档建议从内置配置文件开始:“优先扩展内置配置文件,而不是从头开始,以便继承基准保护。”
自定义配置文件可以扩展 :read-only、:workspace 或另一个命名配置文件。它不能扩展全访问权限配置文件。配置参考说明 Codex 会拒绝将 :danger-full-access 作为父级,同时也会拒绝未知的父级和继承循环。
在 CLI 中,你可以通过 /permissions 查看和更改当前模式。在 ChatGPT 桌面应用和 IDE 扩展中,相同的选项位于 composer 下方的权限控制中。
Codex 启动时的选择
你不需要配置任何内容,Codex 就会应用边界。安全文档描述了启动时的默认设置:“启动时,Codex 会检测文件夹是否受版本控制,并推荐”针对版本控制文件夹的自动预设,以及针对其他文件夹的只读预设。自动预设是“工作区写入 + 按需批准”。
它增加了一个第二个条件:“根据你的设置,Codex 也可能以 read-only 模式启动,直到你明确信任该工作目录(例如,通过入门提示或 /permissions)。”因此,在信任之前,新克隆的项目可能比你以前使用过的项目感觉受到更多限制。
要查看当前会话中哪些内容算作工作区,文档指向了一个命令:“使用 /status 命令查看哪些目录在工作区中。”当写入被拒绝且你不确定路径是否在边界内时,这是最快的检查方法。如果路径未列出,则它在工作区边界之外。
配置文件也遵循正常的配置层级。文档指出:“高优先级层级可以添加或替换同一配置文件名称下的条目,而无需重述整个配置文件。”其示例显示了一个组织级文件和一个用户级文件各自向同一个命名配置文件添加了一个工作区根目录。当该配置文件激活时,两个根目录都有效。这很方便,也是在规则似乎凭空出现时检查每一层的原因。
文件系统规则的工作原理
每个文件系统条目都会获得三个值之一:read(读取)、write(写入)或 deny(拒绝)。文档的表格描述了它们:
- read: “允许命令读取路径下的文件和列出目录。命令不能在那里创建、修改、重命名或删除文件。”
- write: “允许命令读取和修改路径下的文件,包括在操作系统允许的情况下创建、重命名和删除文件。”
- deny: “拒绝路径下的读取和写入。”
当规则重叠时,更具体的路径胜出。当两条规则针对同一路径时,文档称“deny 优先级高于 write,而 write 优先级高于 read”。这让你能够开放整个仓库进行写入,同时保持匹配的环境文件不可读。
路径可以是绝对路径、主目录下的路径或几个特殊名称之一。一个关键名称是 :workspace_roots,意思是“当前会话的工作区根目录加上任何启用的配置文件定义的工作区根目录”。因此,一个配置文件可以添加第二个仓库(例如共享库),并在那里应用相同的规则。
对于长时间运行的进程,有一个时间细节很重要。在 Linux、WSL 和原生 Windows 上,使用 glob 模式的拒绝规则在每个沙箱进程启动时解析。文档直接说明了后果:“一个长时间运行的 shell、脚本、观察器或开发服务器可以读取在其启动后创建的匹配 .env 文件。”其建议是:“不要依赖 glob 来阻止该运行进程中新创建的文件。”
网络规则的工作原理
在自定义配置文件中,命令网络访问默认关闭:配置参考将 network.enabled 的默认值列为 false。开启它和强制执行域名规则是两个独立的步骤,这也是开头示例中第一个意外的原因。
文档指出:“配置文件的 network.enabled = true 允许命令网络访问,但它不会启动网络代理。”域名列表是由该代理强制执行的。文档继续写道:“如果没有活动的代理,配置文件域名规则不会限制直接网络访问。”
为了使域名列表生效,文档说明要在 config.toml 中设置网络代理功能,或使用启用的、由管理员管理的网络要求。在代理激活的情况下,本地地址会获得额外保护:“活动的网络代理默认阻止本地和私有网络目标。”显式允许 localhost、私有 IP 或 Unix 套接字可以重新开放这些访问。
文档还警告不要过度解读允许规则。域名规则“不决定允许的目的地是否值得信任,且通配符允许规则保持宽泛。”
为什么旧的沙箱设置会关闭配置文件
在配置文件出现之前,Codex 使用 sandbox_mode,其值包括 read-only、workspace-write 和 danger-full-access,外加一个单独的 workspace-write 选项表。配置文件取代了这种组合,但这两个系统不能混用。
文档将其放在页面顶部:“权限配置文件不与旧的沙箱设置组合使用。”你只能配置其中一个系统。只要旧系统出现在加载的配置、命令行或选定的配置 profile 中的任何位置,它就会接管。
这很容易意外触发。Codex 从多个层级读取配置,因此用户配置、项目配置或你为某种工作选择的配置 profile 中的旧 sandbox_mode 行都可能关闭你的权限配置文件。脚本或别名中的 --sandbox 标志也是如此。
对于受管理的环境,有一个例外。文档称,受管理的 allowed_permission_profiles 要求“使 Codex 使用权限配置文件”,并建议管理员在部署它之前移除旧设置。一旦该白名单存在,“未包含的配置文件将被拒绝,包括未包含的内置配置文件和未来 Codex 版本中添加的配置文件。”
为什么 .codex 和 .agents 保持只读
这是开头示例中的第二个意外,也是对于塑造 Codex 在项目中运作方式的文件最重要的一个。
Codex 的安全文档列出了可写工作区内的受保护路径:
- “
<writable_root>/.git无论是作为目录还是文件出现,都受只读保护。” - “
<writable_root>/.agents当它作为目录存在时,受只读保护。” - “
<writable_root>/.codex当它作为目录存在时,受只读保护。” - “
<writable_root>/.aws当它作为目录存在时,受只读保护。”
它补充道:“保护是递归的,因此这些路径下的所有内容都是只读的。”
在实践中,.agents 是仓库技能存放的地方,而 .codex 保存项目配置。因此,Codex 在 workspace-write 会话中运行的命令无法重写你编写的技能或决定 Codex 在那里行为的项目设置。你的 Git 历史记录也是如此。
权限页面说明,当自定义配置文件扩展 :workspace 时,这些保护会延续,除非你覆盖它们。如果你从头开始构建配置文件,它不会继承这些保护,这也是文档建议使用扩展的原因之一。
该页面还解释了为什么即使在边界内,写入也值得谨慎对待:“具备写入能力的配置文件可以创建持久更改。将对脚本、构建步骤、包管理器钩子、shell 启动文件和共享目录的写入视为敏感操作,因为随后的工具或用户可以在原始沙箱上下文之外执行这些文件。”
配置文件不控制什么
配置文件涵盖本地沙箱命令。文档列出了哪些内容使用其自身的控制:
- Web 搜索。 “托管搜索工具使用其自身的访问设置。”
- 应用和连接器。 它们使用其自身的服务端连接和设置。
- MCP 服务器。 “使用
mcp_servers配置和受管理的服务器白名单来控制它们。” - 浏览器和计算机使用 (Computer Use)。 它们有自己的功能和批准控制。
- Codex Cloud。 云端任务使用其环境的网络设置。
文档的总结是:“命令网络白名单并不是 Codex 可以执行的每项操作的全局网络策略。”
我们在关于 Codex web 搜索是实时的还是缓存的 指南中介绍了 web 搜索如何融入其中,包括为什么在命令网络访问关闭时它仍可保持可用。
谁来批准进一步的请求
配置文件设置边界。批准决定了当 Codex 想要跨越边界时会发生什么。权限文档说明两者协同工作,并且“更改审核请求的人员不会扩大沙箱范围”。
当批准设置为“按需批准”时,Codex 会暂停并询问。选择“替我批准”后,符合条件的请求将转到自动审核员而不是你。无论哪种方式,边界本身都保持在配置文件设定的位置。
你也可以关闭提示。文档称 --ask-for-approval never “适用于所有 --sandbox 模式,因此你仍然可以控制 Codex 的自主程度。”关闭提示不会拓宽你选择的边界。相反,文档称,“Codex 会在你设置的约束范围内尽力而为。”如果任务需要配置文件未授予的访问权限,解决方法是有意更改配置文件,而不是指望出现提示。
在这两者之间,细粒度的批准策略“允许你保持特定批准提示类别的交互性,同时自动拒绝其他类别”。它涵盖的类别包括沙箱批准、MCP 提示和技能脚本批准。当你希望 Codex 询问网络访问但从不询问技能想要运行的脚本时,这非常有用。
人们首先尝试的操作
在没有代理的情况下添加域名规则。 域名规则仅在网络代理活动时生效。
在保留旧 sandbox_mode 行的同时使用新配置文件。 只要加载了该行,Codex 就会使用旧设置。
要求 Codex 编辑 .agents 中的技能。 在工作区配置文件下,该文件夹是只读的。请自行编辑或刻意更改规则。
从头开始编写配置文件。 扩展 :workspace 可以保留受保护路径。
依赖 glob 向运行中的开发服务器隐藏新的 .env 文件。 Glob 匹配在进程启动时就已固定。
解决方法:使配置文件成为唯一的真相来源
第 1 步:移除旧的沙箱设置
在你的用户、项目和配置 profile 文件以及任何脚本中搜索 sandbox_mode 和 --sandbox。
第 2 步:扩展内置配置文件
从 :workspace 或 :read-only 开始,以便延续受保护路径。
第 3 步:如果你列出了域名,请开启代理
域名规则仅在代理运行时过滤流量。
第 4 步:记录每条规则存在的原因
写下你选择的根目录、拒绝的文件和域名,以及每个选择的原因。
在 MemoryLake 中设置
权限配置文件记录了 Codex 可以触及的内容,但它不记录原因。每条规则背后的原因(例如为什么允许某个域名、哪个仓库共享了库,或者为什么拒绝某个文件夹)都是项目上下文,下一个编辑配置文件的人或下一个工具必须重新发现这些信息。
MemoryLake 是此类项目上下文的记忆层,例如访问决策、惯例及其背后的原因,这些内容保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。
你用自己的语言亲自编写条目。没有任何内容会从你的 config.toml、权限配置文件、.codex 或 .agents 文件夹、仓库或任何供应商的存储中读取、写入或删除。Codex 权限按照 OpenAI 描述的方式运作。
第 1 步:创建 API 密钥
登录并从仪表板生成密钥。将其存储在仓库之外,就像任何其他凭据一样。

第 2 步:上传你的第一批记忆
从你在解决方法的第 4 步中写下的内容开始:每条规则及其原因。每个条目对应一个决策。

第 3 步:连接你的 AI 和 agent
连接 Codex、Claude Code 和你使用的其他助手。每个助手都可以利用相同的访问决策。

这在实践中改变了什么
第一个区别是,当有人编辑配置文件时,意外会减少。规则的原因就在规则描述的旁边。
第二个区别是审核更容易。当添加域名或根目录时,决策及其所有者都有记录。
第三个区别是工具之间的一致性。相同的访问决策在 Codex 和其他助手中都可用。
Codex 权限配置文件的最佳实践
选择一个系统。 使用配置文件或旧的沙箱设置,不要两者混用。
扩展,不要重建。 :workspace 保持 .git、.agents、.codex 和 .aws 为只读。
域名规则需配合代理使用。 否则它们不会限制直接连接。
显式拒绝机密信息。 拒绝规则优于更宽泛的写入规则。
添加机密信息后重启长运行进程。 Glob 拒绝在进程启动时固定。
分别配置其他界面。 Web 搜索、MCP、连接器和浏览器都有各自的控制。
检查测试版标签。 该功能可能会在版本之间发生变化。
结论
Codex 权限配置文件是针对 Codex 本地运行命令的命名策略,结合了文件系统规则(读取、写入或拒绝)和网络规则。三个内置配置文件涵盖了只读、工作区和全访问权限,自定义配置文件应扩展内置配置文件以延续保护。
有两个行为很容易被忽略。加载的配置中任何位置的旧 sandbox_mode 设置或 --sandbox 标志都会使 Codex 改用旧系统。此外,域名规则仅在网络代理活动时生效。在工作区配置文件下,.git、.agents、.codex 和 .aws 保持只读,这可以防止命令重写你的技能、项目配置和历史记录。配置文件仅涵盖本地命令,因此 web 搜索、MCP 服务器、连接器和浏览器需要各自的设置。