Codex 权限机制

概述

Codex 的权限并不是一个“允许或拒绝”开关。本地命令先受沙箱约束，沙箱决定能够读写哪些路径、能否访问网络；审批策略再决定何时暂停任务并请求越界授权。两层一起工作，任何一层收紧都会限制最终行为。

截至 2026 年 8 月 19 日，本地 Codex 同时支持旧式 sandbox 配置和仍处于 beta 的 permission profiles。前者兼容性更广，后者可以用一份具名策略同时描述文件系统和网络边界。两套配置互斥，不能叠加使用。

权限结构

一次本地命令大致经过下面几层判断：

沙箱约束的不只是 Codex 内置的文件编辑。git、包管理器、编译器、测试工具及其子进程都会继承同一边界。审批则只决定是否可以为某次操作扩大权限，不会撤销已执行命令造成的修改。

Web 搜索、MCP、连接器、内置浏览器、Computer Use 和 Codex cloud 各有自己的控制面。给本地 shell 开放网络，不会自动开放这些工具；反过来，启用 Web 搜索也不会让 curl 或包管理器联网。

默认行为

Codex 启动时会检查当前目录是否受版本控制，并推荐不同的本地权限：

• 版本控制目录：通常推荐 Auto，即 workspace-write 与 on-request
• 非版本控制目录：通常从 read-only 开始
• 尚未信任的目录：可能保持只读，直到通过引导界面或 /permissions 明确选择

Auto 允许 Codex 在当前工作区内编辑并运行常规命令，访问工作区外路径或网络时再申请批准。本地 Agent 默认没有命令网络访问能力。可以用 /status 检查当前模型、审批策略和实际工作区根目录，避免把界面名称当成权限事实。

旧式沙箱

旧式配置通过 sandbox_mode 定义本地命令的技术边界：

模式	文件系统与网络边界	适用场景
read-only	读取工作区；编辑、其他命令和网络操作需要越界授权	陌生仓库分析、代码审查
workspace-write	可读写工作区和临时目录，命令网络默认关闭	日常开发
danger-full-access	移除本地沙箱的文件系统和网络限制	已有外层隔离的受控环境

workspace-write 不是工作区内毫无限制。可写根目录中的 .git、.agents 和 .codex 默认仍按只读路径保护，而且保护会递归应用。

一份适合日常开发的 ~/.codex/config.toml 如下：

approval_policy = "on-request"
approvals_reviewer = "user"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

danger-full-access 只表示没有沙箱边界，并不等于自动关闭所有审批。所谓 Full access 是 danger-full-access 与 approval_policy = "never" 的组合，风险也来自这两个限制同时消失。

审批策略

approval_policy 决定 Codex 在什么情况下停下来：

策略	行为
untrusted	仅自动运行已知安全的读取操作，其他命令先询问
on-request	默认在沙箱内工作，需要越过边界时由 Agent 申请
never	不显示审批提示，不能执行的动作直接失败并返回给 Agent

never 只关闭询问，不会扩大沙箱。read-only 与 never 组合后，Codex 会保持只读并在遇到写操作时失败；它不是另一种 Full access。

交互式审批默认交给用户：

approvals_reviewer = "user"

也可以把符合条件的请求交给 reviewer agent：

approval_policy = "on-request"
approvals_reviewer = "auto_review"

Auto-review 会根据请求内容自动批准或拒绝符合条件的越界操作。它不会改写会话的默认 sandbox 设置，但获批准的操作可以按请求范围越过原边界。界面提供“仅本次”和“本次会话”等范围时，应选择能够完成任务的最小范围。

需要更细控制时，approval_policy 还支持 granular 配置，分别处理 sandbox 越界、execpolicy 规则、MCP、request_permissions 和 Skill 脚本审批。团队环境通常还会用 requirements.toml 限制允许的策略，用户配置和 CLI 参数都不能绕过管理员边界。

常用组合

场景	配置	结果
日常开发	workspace-write + on-request	工作区内自动执行，越界时询问
只读分析	read-only + on-request	允许检查项目，修改和命令按需询问
CI 只读检查	read-only + never	不出现交互提示，也不写入工作区
CI 自动修复	workspace-write + never	只在工作区边界内尽力完成任务
自动审批	workspace-write + on-request + auto_review	符合条件的越界请求交给 reviewer agent
完全访问	danger-full-access + never	没有本地沙箱，也没有审批提示

最后一项只适合已经由容器或虚拟机提供外层隔离的环境。即使在容器中，挂载进去的凭据、SSH agent、宿主目录和开放网络仍然属于可访问资产。

Permission Profiles

Permission profiles 是 beta 功能。它把文件系统和网络规则放进具名配置，目前内置三个 profile：

• :read-only：本地命令保持只读
• :workspace：允许写入当前工作区根目录和系统临时目录
• :danger-full-access：移除本地沙箱限制

最简单的选择方式是设置：

default_permissions = ":workspace"

更精确的配置可以继承 :workspace，禁止读取指定扫描深度内的环境文件，并只允许命令访问一个域名：

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
description = "允许编辑项目并访问 OpenAI API"
extends = ":workspace"

[permissions.project-edit.filesystem]
glob_scan_max_depth = 4

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

文件规则使用 read、write 和 deny。更具体的路径优先；规则指向同一路径时，优先级是 deny、write、read。因此可以先把工作区设为可写，再把 .env、部署密钥或生成脚本切成只读或完全拒绝。

Linux、WSL 和原生 Windows 需要在沙箱启动前展开无界的 ** 拒绝规则，glob_scan_max_depth 决定展开深度。目录可能更深时，应提高该值，或列出明确深度的 glob，不能默认一条规则覆盖任意层级。

extends = ":workspace" 会继承内置保护，包括工作区中只读的 .codex 目录。自定义 profile 可以继承 :read-only、:workspace 或另一个自定义 profile，但不能继承 :danger-full-access。

这里的 permission profile 不要与 CLI 的 --profile 混淆。前者是本地命令权限策略；后者选择一份独立的 Codex 配置文件。

配置互斥

旧式沙箱和 permission profiles 只能选择一套。以下任一情况出现时，Codex 会使用旧式 sandbox，而不是 default_permissions：

• 任意已加载配置文件包含 sandbox_mode
• 命令行传入 --sandbox
• --profile 选中的独立配置文件包含 sandbox_mode

迁移到 permission profiles 时，应从所有配置层删除 sandbox_mode 和 [sandbox_workspace_write]。项目配置、用户配置、独立 profile 和系统配置都在加载链中，只改其中一处并不一定生效。

网络权限

Permission profiles 把“是否联网”和“能访问哪里”拆成两个开关：

1. permissions.<name>.network.enabled = true 允许本地命令联网
2. features.network_proxy = true 启动代理并执行 domains 规则

两者的组合结果如下：

命令网络	网络代理	结果
关闭	任意	命令不能联网
开启	关闭	命令可以直接访问网络，domains 规则不生效
开启	开启	命令经代理访问，domains 规则生效

域名匹配中，*.example.com 只包含子域名，**.example.com 同时包含根域名和子域名，deny 始终优先于 allow。代理默认阻止环回、链路本地和私有网络目标；确实要访问本机服务时，应精确允许 localhost 或具体 IP，而不是直接打开所有本地绑定。

域名允许列表只限制目的地，不代表目标服务可信。涉及高价值凭据或不受信任仓库时，还应在容器、防火墙或云环境层增加出站限制。

界面与命令

TUI 中使用 /permissions 切换当前权限，使用 /status 查看实际生效状态。IDE extension 和 ChatGPT desktop app 在输入框下方提供权限选择器；可见选项取决于客户端版本、管理员策略和已配置的 permission profiles。

CLI 可以临时覆盖旧式 sandbox 与审批策略：

codex --sandbox workspace-write --ask-for-approval on-request
codex --sandbox read-only --ask-for-approval on-request

--dangerously-bypass-approvals-and-sandbox 及其别名 --yolo 会同时跳过审批和沙箱。这个名称已经把风险写得很直白，不应把它当作解决权限报错的常规参数。

无人值守

codex exec 默认使用只读沙箱。CI 中最好显式写出边界，避免客户端默认值变化后扩大权限：

codex exec \
  --sandbox read-only \
  --ask-for-approval never \
  "检查当前改动并输出风险"

需要自动修改工作区时：

codex exec \
  --sandbox workspace-write \
  --ask-for-approval never \
  "修复构建错误并执行已有验证命令"

第二个命令不会弹出审批，也不会因此获得网络或工作区外写权限。任务需要安装依赖时，应在流水线的准备阶段完成，或只开放必要的网络目标和缓存目录。

风险边界

沙箱降低的是一次命令直接访问宿主资源的能力，它不是恶意代码检测器。使用时还要考虑几类间接影响：

• Codex 修改构建脚本、包管理器 hook 或 shell 启动文件后，后续工具可能在沙箱外执行这些内容
• 网络允许列表可以限制目的地，但不能判断上传内容是否包含密钥或源码
• 批准一次越界命令可能产生持久修改，审批记录不会自动回滚文件或外部服务状态
• MCP、浏览器、连接器和云端任务有独立权限，不能只检查 sandbox_mode 就断定整个会话没有外部访问
• 管理员策略可以继续收紧本地配置，最终生效值应以 /status 和当前权限界面为准

陌生仓库先用只读模式检查，日常开发保留工作区边界，无人值守任务关闭审批但收紧沙箱。完全访问应该来自明确的隔离设计，而不是为了少点几次确认按钮。

参考

• Permissions
• Sandbox
• Agent approvals & security
• Configuration Reference