Skip to main content

​
本页解决什么问题

Codex 不只是回答问题的聊天工具。它可以读取文件、编辑代码、启动命令、运行测试，并根据结果继续下一步。权限配置决定了这些动作能到哪里，审批策略决定了哪些动作需要停下来等你确认。 本页专门讲两个独立的控制面：
  • 沙箱模式：read-only、workspace-write、danger-full-access。
  • 审批策略：untrusted、on-request、never。
还会覆盖以下实际操作：
  • 用 CLI 参数只改变当前会话。
  • 用 config.toml 设置默认值。
  • 判断命令为什么被批准、阻止或要求确认。
  • 理解工作区、临时目录、.git 和敏感文件的边界。
  • 控制网络访问和可写目录。
  • 组合权限时避免“审批很严但沙箱已经过宽”的错觉。
  • 用最小实验测试配置，并在结果不对时回滚。
  • 识别 --yolo 或完全访问模式带来的危险后果。
具体选项、默认值和交互界面可能随 Codex 版本变化。执行前先运行本机的 codex --help，进入会话后用 /status 查看当前生效状态；本文示例中的命令和配置项以官方文档及常见 CLI 版本为基础。

​
先记住两个独立旋钮

沙箱和审批经常被混为一谈，但它们解决的是不同问题。 可以把沙箱理解为物理边界，把审批理解为决策流程。审批不能把一个已经开放的文件系统重新变成只读；沙箱也不代表每一步都会弹窗。 例如：
  • read-only + never：只能在只读边界内工作，而且不主动询问。
  • workspace-write + on-request：工作区内可以自动编辑，越出边界时询问。
  • danger-full-access + on-request：即使仍然询问，获批后也可能访问整台机器。
  • danger-full-access + never：没有沙箱和人工审批两层保护，风险最高。
因此不要只看“是否需要批准”这一件事。每次使用前同时检查“能访问的范围”和“会不会询问”。

​
开始前的四项检查

在陌生仓库、临时目录或包含敏感数据的机器上，先确认上下文：
Windows PowerShell 可使用：
然后确认四件事：
  1. 当前目录确实是目标项目，而不是主目录、下载目录或生产挂载点。
  2. 当前账号不是不必要的管理员账号，环境变量中没有多余的生产凭据。
  3. 工作区是否有 Git；没有 Git 时，修改通常更难审查和恢复。
  4. 这次任务是否需要联网、安装依赖、写出工作区、访问外部服务或删除文件。
先写出明确的非目标也很重要，例如：
任务范围越明确，审批时越容易判断一条命令是否合理。

​
三种沙箱模式

​
read-only

read-only 把本地工作重点限制为读取和分析。它适合代码审查、设计讨论、错误诊断、生成方案和初次了解不可信仓库。 典型行为：
  • 可以读取允许范围内的源代码和配置。
  • 不能直接写入代码、补丁、日志或新文件。
  • 不能把“先写临时文件再移动回来”当成绕过方式；派生进程也在同一权限边界内。
  • 网络通常不可用，具体行为以当前版本状态和配置为准。
  • 如果请求要求写文件或执行越界动作，可能被阻止，也可能根据审批策略请求一次性批准。
适合的任务：
  • “只审查这段代码，不要修改。”
  • “解释测试失败原因，并给出修复方案。”
  • “查看仓库结构，列出风险，不要运行修改性命令。”
  • “检查配置中是否出现密钥，但不要打开真实密钥文件。”
只读并不等于安全地读取一切。一个包含令牌、客户信息或私钥的目录，即使只能读取，也可能发生敏感信息暴露。因此仍要限制启动目录、提示内容和输出范围。

​
workspace-write

workspace-write 允许 Codex 在工作区范围内编辑文件，通常是日常开发的平衡选择。 典型行为：
  • 可以修改工作区内的代码、测试和文档。
  • 可以创建、删除或重命名工作区内的普通文件，但具体动作可能仍受审批规则影响。
  • 派生的 git、测试脚本和包管理命令同样受沙箱约束。
  • 网络访问通常默认关闭；允许写入不代表允许访问互联网。
  • 工作区之外的路径通常需要额外授权，或直接被沙箱拒绝。
  • .git、Codex 自身配置目录等敏感位置可能保持只读保护，不能把“工作区可写”理解成“工作区内任何路径都可写”。
适合的任务：
  • 修改一个已有功能并运行本地测试。
  • 在项目目录内生成代码、测试和构建产物。
  • 修复格式、类型错误或小范围回归。
建议把 workspace-write 当作默认开发档，但在陌生项目中先用 read-only 完成检查，再切换到可写。

​
danger-full-access

danger-full-access 移除或显著扩大本地文件系统和命令执行的沙箱限制。它不是“更方便的工作区可写”，而是完全不同的风险等级。 典型能力可能包括：
  • 访问当前工作区以外的目录。
  • 修改用户主目录、共享目录或其他挂载目录。
  • 运行会影响系统状态的命令。
  • 在网络允许的情况下访问外部服务。
  • 读取当前进程账号能读到的配置、令牌和凭据。
只在以下条件同时满足时考虑：
  • 任务确实需要跨目录或系统级操作。
  • 在一次性容器、虚拟机或专用测试机中运行。
  • 环境中没有真实生产凭据和不可恢复数据。
  • 已准备快照、备份或可重建环境。
  • 操作范围和输出都有人审查。
不要因为某条命令在 workspace-write 下失败，就直接切到完全访问。先确认失败原因是路径不在工作区、网络关闭、命令需要提升权限，还是配置键写错。

​
三种审批策略

​
untrusted

untrusted 对不在可信集合内的命令更谨慎。只读、低风险的查询通常可以自动执行；可能修改状态、访问外部资源或执行未知脚本的命令会要求确认。 它适合：
  • 第一次打开不熟悉的仓库。
  • 处理来源不明的脚本或依赖。
  • 需要频繁阅读，但希望对执行动作逐项把关的任务。
  • 共享开发机或需要更高人工介入的工作。
注意：untrusted 不是沙箱模式，也不等于“绝对只读”。它控制的是命令审批判断，文件系统边界仍由 sandbox_mode 决定。

​
on-request

on-request 通常允许沙箱范围内的常见操作自动进行；当动作需要越过边界、联网、访问额外路径或执行高风险命令时暂停请求确认。 它适合日常开发：
批准前要看清楚：
  • 实际命令，而不是代理对命令的概述。
  • 当前工作目录和命令中的绝对路径。
  • 是否有管道、重定向、命令替换或多条命令串联。
  • 是否会发送数据、安装脚本、删除文件或修改权限。
  • 批准是一次性的，还是会影响后续相似命令。
“在工作区内”不自动意味着“无风险”。例如 npm test 可能执行项目中的任意脚本，make 可能调用删除或上传命令，git hooks 也可能在提交时执行额外逻辑。

​
never

never 表示不等待人工审批。它只关闭审批环节，不扩大沙箱边界。 安全的一个组合是：
这适合自动化只读分析，前提是读取范围本身没有敏感资料。 危险的组合是：
此时既没有有效的本地边界，也没有人工确认点。不要在日常主机、生产目录、共享工作站或含有 SSH 密钥的账号下使用。

​
权限组合速查表

下表是选择起点，不是对每个命令结果的绝对保证。具体行为仍要以 /status、审批提示和实际测试为准。 “审批严格”不能弥补“沙箱过宽”，“沙箱严格”也不能替代对敏感读取的审查。

​
CLI 参数：只影响这次启动

先查看本机实际参数名：
常用写法如下：
带任务文本启动：
在 Windows PowerShell 中，参数写法相同：
检查当前会话：
通常应关注这些信息：
  • 当前沙箱模式。
  • 当前审批策略。
  • 工作区或允许写入的目录。
  • 网络状态。
  • 当前模型和会话入口。
部分版本提供会话内的 /permissions 选择器。它可能显示权限预设、审批策略或新的 permission profile，而不一定直接显示三种旧沙箱名称。若菜单含义不清，退出后用明确的 --sandbox 和 --ask-for-approval 启动，不要凭按钮名称猜测权限。 命令行参数一般优先于配置文件中的同名默认值。验证优先级时，故意使用与默认值相反的参数，再通过 /status 和最小实验确认。

​
config.toml：设置默认行为

常见用户级配置位置是：
Windows 通常对应：
请先确认本机版本支持的配置键和文件位置。不要把包含访问令牌的配置提交到仓库，也不要让 Codex 直接覆盖配置后不审查 diff。 日常开发的基础配置示例：
更保守的默认配置：
CI 只读分析的示例：
这不会自动保证 CI 不读取秘密。CI 仍需使用最小权限账号、干净工作区和经过筛选的环境变量。

​
开启工作区网络时要谨慎

某些版本使用如下区段控制 workspace-write 的网络访问：
开启前先回答：
  • 需要访问哪个域名或服务？
  • 是否可以用离线缓存、内部镜像或预下载依赖代替？
  • 请求中是否会自动携带环境变量、Cookie、认证头或项目内容？
  • 是否有代理、TLS、DNS 和出站防火墙限制？
  • 安装脚本会不会执行任意代码？
网络一旦打开，风险不只是“能下载包”。程序可能把代码、环境信息或错误输出发送到外部地址；恶意依赖也可能在安装或测试阶段执行脚本。

​
配置预设与命令行覆盖

如果本机版本支持 profile，可以为不同工作流准备独立配置，并在启动时明确选择。示例结构可能类似：
使用方式以 codex --help 为准，例如：
不要把“配置预设 profile”和某些版本中的“permission profile”混为一谈。后者可能是单独的 Beta 能力，用于更细粒度描述文件系统和网络；如果版本提示两套机制不能混用，就不要同时设置 sandbox_mode、--sandbox 和新的权限档案。

​
工作区和可写目录

​
工作区不是整台机器

workspace-write 的工作区通常由启动目录和相关项目边界决定，也可能包含系统临时目录。不要靠猜测判断路径是否可写，进入会话后查看 /status 或用一个无害的临时文件测试。 建议先记录：
Windows PowerShell：
确认工作区范围时，尤其留意：
  • 当前目录是否是仓库根目录。
  • 是否包含父目录中的其他项目。
  • 临时目录是否被自动加入。
  • 符号链接、挂载点和 junction 是否指向工作区外。
  • 构建工具是否把产物写到工作区外。

​
受保护的敏感目录

不同版本和平台的保护细节可能不同，但以下路径应默认当作敏感区域：
  • <workspace>/.git。
  • <workspace>/.codex。
  • <workspace>/.agents。
  • 用户目录下的 .ssh、云 CLI 配置、密码管理器配置。
  • 项目中的 .env、证书、私钥、生产配置和备份。
  • 包管理器缓存和可能含认证信息的日志目录。
即使某些路径技术上可写，也不要把它们加入工作区或规则白名单。保护 Git 元数据尤其重要：修改 .git 可能破坏分支、索引、钩子、对象库或审查依据。

​
“能写目录”不等于“能执行任意脚本”

写入工作区后，文件可能被构建工具、编辑器、Git hook 或测试框架自动执行。例如：
  • 写入 package.json 后执行 npm install 触发 postinstall。
  • 写入 Makefile 后执行 make 运行任意 shell 命令。
  • 修改 .git/hooks 或配置后影响后续 Git 操作。
  • 生成 CI 配置后被远程流水线执行。
  • 写入模板或配置后，开发服务器加载外部脚本。
因此审批时不仅要问“写了什么”，还要问“谁会读取或执行这个文件”。

​
网络访问的边界

网络访问至少包含三层问题：
  1. 沙箱是否允许出站网络。
  2. 审批策略是否要求对网络命令确认。
  3. 具体程序是否会携带凭据、上传内容或执行远程返回值。
在网络关闭时，以下命令可能失败或被拦截：
失败不一定表示命令错误，可能只是沙箱没有网络权限。不要为了让一条安装命令成功就直接开启完全访问。 网络开启后的验证应使用无敏感内容的测试地址，并保存实际请求范围：
不要在实验中把以下内容发送到第三方：
  • 整个仓库压缩包。
  • .env 和配置文件。
  • SSH、云服务或包仓库令牌。
  • 客户数据、内部接口响应和日志。
  • 未发布的源代码和安全报告。
依赖安装建议使用锁文件、内部镜像、哈希校验和隔离缓存。不要把“能访问 npm、PyPI 或 GitHub”理解成“来自这些地方的一切脚本都可信”。

​
命令审批：每次批准前看什么

看到审批提示时，按以下顺序检查：

​
先看命令是否完整

确认没有被折叠的参数、重定向或隐含执行：
重点检查：
  • | 管道。
  • >、>> 重定向。
  • $(...) 或反引号命令替换。
  • &&、;、|| 串联命令。
  • xargs、find -exec、脚本解释器。
  • sudo、管理员权限和修改权限的参数。
  • 从网络下载后立即执行的模式。

​
再看路径和范围

把相对路径换算成实际路径。特别警惕：
Windows 中也要警惕递归删除、盘符根目录、用户目录和共享盘：
不要因为命令使用了“清理”“重置”“同步”“修复”等友好词汇就自动批准。

​
最后看外部副作用

以下动作需要单独确认：
  • 安装或升级依赖。
  • 发送 HTTP 请求、上传文件或推送代码。
  • 创建、修改或关闭云资源。
  • 提交、推送、创建 PR、合并分支。
  • 删除数据库、对象存储或远程分支。
  • 发送邮件、消息、工单或评论。
  • 修改系统服务、凭据、网络设置或防火墙。
批准时尽量只批准一次、只批准当前必要动作。不要把一串“以后类似命令都自动允许”当作方便的小优化。

​
命令规则与精细限制

如果本机版本支持命令规则，可以用规则把常见命令划分为允许、询问和禁止。规则语法与文件位置必须以当前版本文档为准；一些版本使用 ~/.codex/rules/ 下的 .rules 文件，并提供 codex execpolicy check 检查命令。 概念示例：
精细规则不能替代沙箱。允许 git 不代表允许所有 Git 子命令；允许查看 PR 不代表允许推送分支。多命令串联时必须逐条检查，不能因为第一段命令安全就放过后面的删除或外发动作。 通常应遵循“最严格规则优先”的思路：禁止高于询问，询问高于允许。若版本的匹配优先级不同，以 --help 和规则检查结果为准。

​
permission profiles 的谨慎用法

部分版本提供 Beta 的 permission profiles，用于更细地配置文件系统路径和网络域名。它可能允许：
  • 以工作区为默认可写范围。
  • 对某个目录设为只读。
  • 对 .env 或密钥文件明确拒绝。
  • 只允许少数网络域名。
概念性配置示例：
这类配置有三个前提：
  1. 先确认本机版本支持该键名、语法和内置 profile 名称。
  2. 确认它与旧的 sandbox_mode、--sandbox 是否互斥。
  3. 用实际读、写、联网测试验证规则，而不是只看配置文件没有报错。
路径规则通常需要处理具体路径优先级、通配符、符号链接和大小写差异。默认拒绝比默认允许更容易审查；网络也应优先采用域名白名单，而不是开放所有出站访问。

​
推荐组合

​
陌生仓库：先读后写

第一阶段：
让 Codex 完成：
  • 读取项目结构和约定。
  • 解释构建和测试入口。
  • 指出潜在危险脚本。
  • 提出修改计划，不落盘。
确认计划和范围后，第二阶段：
这样把“理解代码”和“修改代码”分成两个可审查步骤。

​
日常本地开发

这个组合通常能让本地编辑和测试顺畅进行，同时在访问工作区外、联网或执行高风险命令时给出确认机会。

​
只读 CI 检查

同时在 CI 中：
  • 使用没有生产权限的账号。
  • 不注入不需要的秘密。
  • 把工作目录限制为构建所需的最小范围。
  • 保存日志但过滤令牌和个人信息。
  • 让失败退出，不要通过自动批准掩盖错误。

​
隔离容器中的自动任务

只有在容器可销毁、凭据已清空、出站网络受限且任务可重复时，才考虑：
这不是主机安全配置，而是假设容器本身就是外层隔离边界。容器内仍可能泄露挂载目录、环境变量、Codex 登录凭据或内部网络访问权。

​
最小可重复测试

不要第一次就用真实项目和真实凭据测试权限。创建一个可删除的目录：
Windows PowerShell：
启动只读会话：
输入：
预期：
  • README.txt 可以被读取。
  • 创建 probe.txt 会被阻止或要求明确批准。
  • 未经批准时，probe.txt 不应出现。
退出后启动工作区可写：
输入：
预期：
  • probe.txt 在测试目录中出现。
  • 内容只有预期的一行。
  • 没有修改 .git 或其他目录。
测试网络默认值时，使用无敏感数据的请求：
在 workspace-write 下，预期可能是网络被拒绝、命令失败或请求审批；不要把某一种提示文字当成跨版本契约，重点是确认当前状态和实际边界。 测试工作区外写入时，先选择明确的临时目录，不要使用主目录：
预期是被沙箱阻止或请求批准。批准前核对绝对路径，测试完成后删除整个测试目录。

​
验收清单

每次调整权限后，至少保存以下证据：
  • codex --version 的版本。
  • 启动时使用的完整沙箱和审批参数。
  • /status 显示的生效模式。
  • 工作区目录和网络状态。
  • 测试使用的命令、目标路径和预期结果。
  • git status --short 和 git diff --check 的结果。
  • 是否发生了外部请求、依赖安装、提交或推送。
代码修改任务还应运行项目自己的最小验证，例如：
或：
不要照搬不存在于项目中的测试命令；先查看 README、package.json、pyproject.toml、Makefile 或 CI 配置。 如果权限测试发现模式与预期不同，先记录版本、平台和配置来源，再停止扩大权限。不要连续尝试多个高权限参数，最后却无法判断是哪一项产生了效果。

​
危险案例

​
案例一：在主目录开启完全访问

错误做法：
后果可能包括：
  • 扫描并输出 SSH 配置、云凭据和历史命令。
  • 修改主目录中的个人文件。
  • 删除无法从 Git 恢复的目录。
  • 读取浏览器、构建工具或包管理器的认证信息。
修复：立即停止会话，轮换可能暴露的凭据，检查文件和网络日志。不要只依赖“它说没有读取”。

​
案例二：把 network_access 当作安装依赖开关

错误做法：
然后让代理对未知项目运行安装脚本。风险在于依赖解析、安装钩子、远程脚本和错误日志都可能产生外部副作用。 改进方式：使用锁文件、可信镜像、隔离缓存和非生产凭据；先执行查看依赖的命令，再单独批准安装。

​
案例三：批准一个看似正常的测试命令

npm test、make test 或 pytest 可能加载项目配置、插件和脚本。恶意项目可以把数据外发、删除目录或修改权限。 改进方式：先读取脚本定义和测试入口，在 read-only 下审查，再在隔离环境中运行。对来源不明项目不要提供真实环境变量。

​
案例四：用“允许 Git”掩盖推送

git status 和 git diff 是低风险审查命令，但 git push 会把内容发送到远端。不要因为两者都以 git 开头就建立过宽的允许规则。 推送前必须确认：
  • 分支和远端正确。
  • diff 不包含密钥和临时文件。
  • 目标仓库和权限正确。
  • 推送是任务明确要求，而不是代理自行决定。

​
案例五：工作区中存在秘密

workspace-write 不会自动清理 .env、证书和备份文件。代理可能在诊断时读取它们，也可能把内容放进日志、补丁或回复。 改进方式：使用脱敏副本、最小化工作区、隔离环境变量，并明确提示“不要读取或输出秘密文件”。必要时使用更细的路径拒绝规则。

​
回滚策略

​
未提交的代码修改

先保存当前 diff：
确认没有同事或其他自动化任务的改动后，回滚目标文件：
不要对整个仓库直接执行恢复，除非已经核对所有未提交内容都属于本次实验。

​
配置修改

修改 config.toml 前先备份：
Windows PowerShell：
恢复时先退出 Codex 会话，再还原配置并用 /status 验证。不要在会话仍运行时假设配置已热加载。

​
已经发生外部副作用

文件修改可以用 Git 或备份恢复，但以下动作不能靠 git restore 撤销：
  • 远端推送。
  • 密钥泄露。
  • 云资源创建或删除。
  • 数据库写入。
  • 外部消息和邮件发送。
  • 依赖下载和供应链执行。
此时应立即停止自动化，保留日志，撤销或轮换凭据，使用服务自身的回滚、备份和审计机制。不要为了“清理痕迹”删除日志。

​
最终决策表

遇到新任务时，可以按下面顺序选择： 推荐的默认流程是：先 read-only 检查，再 workspace-write 修改；保持 on-request，只对必要动作批准；网络按需、按域名、按时段开放；完全访问只放在可销毁的隔离环境中。

​
小结

本页最重要的不是记住一条“万能配置”，而是形成两步判断：
  1. 沙箱决定 Codex 能触及的文件、命令和网络范围。
  2. 审批策略决定它何时停下来请求人工确认。
日常开发通常从下面这组配置开始：
陌生项目先收紧：
只读自动化可以使用 read-only + never，但仍要限制读取范围。danger-full-access + never 只适合隔离、可销毁且没有真实凭据的环境；不要把 --yolo 当成本机默认启动方式。 任何高权限操作都应满足：范围明确、数据脱敏、命令可解释、结果可验证、失败可停止、变更可回滚。做到这些，权限配置才真正成为控制手段，而不是一组看起来安全的字符串。 参考资料：参考/codex/15-permissions.md、参考/codex/02-core-concepts.md。