> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 01-权限沙箱与审批策略

> 掌握 Codex 的沙箱权限、命令审批、网络访问和可写目录配置，按任务风险选择模式并验证、回滚高权限操作。

## 本页解决什么问题

Codex 不只是回答问题的聊天工具。它可以读取文件、编辑代码、启动命令、运行测试，并根据结果继续下一步。权限配置决定了这些动作能到哪里，审批策略决定了哪些动作需要停下来等你确认。

本页专门讲两个独立的控制面：

* 沙箱模式：`read-only`、`workspace-write`、`danger-full-access`。
* 审批策略：`untrusted`、`on-request`、`never`。

还会覆盖以下实际操作：

* 用 CLI 参数只改变当前会话。
* 用 `config.toml` 设置默认值。
* 判断命令为什么被批准、阻止或要求确认。
* 理解工作区、临时目录、`.git` 和敏感文件的边界。
* 控制网络访问和可写目录。
* 组合权限时避免“审批很严但沙箱已经过宽”的错觉。
* 用最小实验测试配置，并在结果不对时回滚。
* 识别 `--yolo` 或完全访问模式带来的危险后果。

具体选项、默认值和交互界面可能随 Codex 版本变化。执行前先运行本机的 `codex --help`，进入会话后用 `/status` 查看当前生效状态；本文示例中的命令和配置项以官方文档及常见 CLI 版本为基础。

## 先记住两个独立旋钮

沙箱和审批经常被混为一谈，但它们解决的是不同问题。

| 控制项  | 它回答的问题                | 常用配置键             | 常用 CLI 参数                   |
| ---- | --------------------- | ----------------- | --------------------------- |
| 沙箱模式 | Codex 的进程和子命令最多能访问哪里？ | `sandbox_mode`    | `--sandbox` 或 `-s`          |
| 审批策略 | 哪些命令执行前需要人工确认？        | `approval_policy` | `--ask-for-approval` 或 `-a` |

可以把沙箱理解为物理边界，把审批理解为决策流程。审批不能把一个已经开放的文件系统重新变成只读；沙箱也不代表每一步都会弹窗。

例如：

* `read-only` + `never`：只能在只读边界内工作，而且不主动询问。
* `workspace-write` + `on-request`：工作区内可以自动编辑，越出边界时询问。
* `danger-full-access` + `on-request`：即使仍然询问，获批后也可能访问整台机器。
* `danger-full-access` + `never`：没有沙箱和人工审批两层保护，风险最高。

因此不要只看“是否需要批准”这一件事。每次使用前同时检查“能访问的范围”和“会不会询问”。

## 开始前的四项检查

在陌生仓库、临时目录或包含敏感数据的机器上，先确认上下文：

```bash theme={null}
pwd
codex --version
codex --help
git status --short --branch
```

Windows PowerShell 可使用：

```powershell theme={null}
Get-Location
codex --version
codex --help
git status --short --branch
```

然后确认四件事：

1. 当前目录确实是目标项目，而不是主目录、下载目录或生产挂载点。
2. 当前账号不是不必要的管理员账号，环境变量中没有多余的生产凭据。
3. 工作区是否有 Git；没有 Git 时，修改通常更难审查和恢复。
4. 这次任务是否需要联网、安装依赖、写出工作区、访问外部服务或删除文件。

先写出明确的非目标也很重要，例如：

```text theme={null}
只修改 src/ 下与登录相关的文件。
不要访问生产服务，不要安装依赖，不要提交或推送。
完成后展示 git diff，并运行指定的单元测试。
```

任务范围越明确，审批时越容易判断一条命令是否合理。

## 三种沙箱模式

### `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` 通常允许沙箱范围内的常见操作自动进行；当动作需要越过边界、联网、访问额外路径或执行高风险命令时暂停请求确认。

它适合日常开发：

```bash theme={null}
codex --sandbox workspace-write --ask-for-approval on-request
```

批准前要看清楚：

* 实际命令，而不是代理对命令的概述。
* 当前工作目录和命令中的绝对路径。
* 是否有管道、重定向、命令替换或多条命令串联。
* 是否会发送数据、安装脚本、删除文件或修改权限。
* 批准是一次性的，还是会影响后续相似命令。

“在工作区内”不自动意味着“无风险”。例如 `npm test` 可能执行项目中的任意脚本，`make` 可能调用删除或上传命令，`git hooks` 也可能在提交时执行额外逻辑。

### `never`

`never` 表示不等待人工审批。它只关闭审批环节，不扩大沙箱边界。

安全的一个组合是：

```bash theme={null}
codex --sandbox read-only --ask-for-approval never
```

这适合自动化只读分析，前提是读取范围本身没有敏感资料。

危险的组合是：

```bash theme={null}
codex --sandbox danger-full-access --ask-for-approval never
```

此时既没有有效的本地边界，也没有人工确认点。不要在日常主机、生产目录、共享工作站或含有 SSH 密钥的账号下使用。

## 权限组合速查表

下表是选择起点，不是对每个命令结果的绝对保证。具体行为仍要以 `/status`、审批提示和实际测试为准。

| 沙箱                   | 审批           | 预期体验         | 推荐场景       | 主要风险          |
| -------------------- | ------------ | ------------ | ---------- | ------------- |
| `read-only`          | `untrusted`  | 读取谨慎，动作频繁询问  | 陌生仓库审查     | 输出可能包含敏感内容    |
| `read-only`          | `on-request` | 读取自动，越界动作询问  | 只读分析和计划    | 误批准写入或联网      |
| `read-only`          | `never`      | 安静的只读分析      | CI 只读检查    | 读取范围过大时泄露信息   |
| `workspace-write`    | `untrusted`  | 工作区内也可能对命令询问 | 不可信依赖或共享机器 | 审批过多导致误点      |
| `workspace-write`    | `on-request` | 工作区内顺畅，越界时询问 | 日常开发，首选    | 项目脚本本身可能有副作用  |
| `workspace-write`    | `never`      | 自动修改工作区，不询问  | 隔离测试环境     | 错误修改不易及时发现    |
| `danger-full-access` | `untrusted`  | 系统范围较大，仍逐步询问 | 专用维护环境     | 一次误批准影响很广     |
| `danger-full-access` | `on-request` | 高权限但保留确认点    | 一次性受控环境    | 误判命令后影响主机     |
| `danger-full-access` | `never`      | 完全自动化        | 可销毁容器或 VM  | 主机和凭据可能被破坏或外传 |

“审批严格”不能弥补“沙箱过宽”，“沙箱严格”也不能替代对敏感读取的审查。

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

先查看本机实际参数名：

```bash theme={null}
codex --help
codex exec --help
```

常用写法如下：

```bash theme={null}
codex --sandbox read-only --ask-for-approval untrusted
```

```bash theme={null}
codex -s workspace-write -a on-request
```

带任务文本启动：

```bash theme={null}
codex -s workspace-write -a on-request "先检查测试失败原因，只修改相关文件，不要提交"
```

在 Windows PowerShell 中，参数写法相同：

```powershell theme={null}
codex --sandbox workspace-write --ask-for-approval on-request
```

检查当前会话：

```text theme={null}
/status
```

通常应关注这些信息：

* 当前沙箱模式。
* 当前审批策略。
* 工作区或允许写入的目录。
* 网络状态。
* 当前模型和会话入口。

部分版本提供会话内的 `/permissions` 选择器。它可能显示权限预设、审批策略或新的 permission profile，而不一定直接显示三种旧沙箱名称。若菜单含义不清，退出后用明确的 `--sandbox` 和 `--ask-for-approval` 启动，不要凭按钮名称猜测权限。

命令行参数一般优先于配置文件中的同名默认值。验证优先级时，故意使用与默认值相反的参数，再通过 `/status` 和最小实验确认。

## `config.toml`：设置默认行为

常见用户级配置位置是：

```text theme={null}
~/.codex/config.toml
```

Windows 通常对应：

```text theme={null}
%USERPROFILE%\.codex\config.toml
```

请先确认本机版本支持的配置键和文件位置。不要把包含访问令牌的配置提交到仓库，也不要让 Codex 直接覆盖配置后不审查 diff。

日常开发的基础配置示例：

```toml theme={null}
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

更保守的默认配置：

```toml theme={null}
sandbox_mode = "read-only"
approval_policy = "untrusted"
```

CI 只读分析的示例：

```toml theme={null}
sandbox_mode = "read-only"
approval_policy = "never"
```

这不会自动保证 CI 不读取秘密。CI 仍需使用最小权限账号、干净工作区和经过筛选的环境变量。

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

某些版本使用如下区段控制 `workspace-write` 的网络访问：

```toml theme={null}
[sandbox_workspace_write]
network_access = true
```

开启前先回答：

* 需要访问哪个域名或服务？
* 是否可以用离线缓存、内部镜像或预下载依赖代替？
* 请求中是否会自动携带环境变量、Cookie、认证头或项目内容？
* 是否有代理、TLS、DNS 和出站防火墙限制？
* 安装脚本会不会执行任意代码？

网络一旦打开，风险不只是“能下载包”。程序可能把代码、环境信息或错误输出发送到外部地址；恶意依赖也可能在安装或测试阶段执行脚本。

### 配置预设与命令行覆盖

如果本机版本支持 profile，可以为不同工作流准备独立配置，并在启动时明确选择。示例结构可能类似：

```toml theme={null}
# ~/.codex/daily.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

```toml theme={null}
# ~/.codex/audit.toml
sandbox_mode = "read-only"
approval_policy = "untrusted"
```

使用方式以 `codex --help` 为准，例如：

```bash theme={null}
codex --profile audit
```

不要把“配置预设 profile”和某些版本中的“permission profile”混为一谈。后者可能是单独的 Beta 能力，用于更细粒度描述文件系统和网络；如果版本提示两套机制不能混用，就不要同时设置 `sandbox_mode`、`--sandbox` 和新的权限档案。

## 工作区和可写目录

### 工作区不是整台机器

`workspace-write` 的工作区通常由启动目录和相关项目边界决定，也可能包含系统临时目录。不要靠猜测判断路径是否可写，进入会话后查看 `/status` 或用一个无害的临时文件测试。

建议先记录：

```bash theme={null}
pwd
find . -maxdepth 2 -type d -print
```

Windows PowerShell：

```powershell theme={null}
Get-Location
Get-ChildItem -Directory -Force
```

确认工作区范围时，尤其留意：

* 当前目录是否是仓库根目录。
* 是否包含父目录中的其他项目。
* 临时目录是否被自动加入。
* 符号链接、挂载点和 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. 具体程序是否会携带凭据、上传内容或执行远程返回值。

在网络关闭时，以下命令可能失败或被拦截：

```bash theme={null}
curl https://example.com
npm install
pip install -r requirements.txt
git fetch origin
```

失败不一定表示命令错误，可能只是沙箱没有网络权限。不要为了让一条安装命令成功就直接开启完全访问。

网络开启后的验证应使用无敏感内容的测试地址，并保存实际请求范围：

```bash theme={null}
curl -I https://example.com
```

不要在实验中把以下内容发送到第三方：

* 整个仓库压缩包。
* `.env` 和配置文件。
* SSH、云服务或包仓库令牌。
* 客户数据、内部接口响应和日志。
* 未发布的源代码和安全报告。

依赖安装建议使用锁文件、内部镜像、哈希校验和隔离缓存。不要把“能访问 npm、PyPI 或 GitHub”理解成“来自这些地方的一切脚本都可信”。

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

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

### 先看命令是否完整

确认没有被折叠的参数、重定向或隐含执行：

```bash theme={null}
command --help
```

重点检查：

* `|` 管道。
* `>`、`>>` 重定向。
* `$(...)` 或反引号命令替换。
* `&&`、`;`、`||` 串联命令。
* `xargs`、`find -exec`、脚本解释器。
* `sudo`、管理员权限和修改权限的参数。
* 从网络下载后立即执行的模式。

### 再看路径和范围

把相对路径换算成实际路径。特别警惕：

```bash theme={null}
rm -rf .
rm -rf ../
find / -delete
chmod -R 777 .
```

Windows 中也要警惕递归删除、盘符根目录、用户目录和共享盘：

```powershell theme={null}
Remove-Item -Recurse -Force .
Remove-Item -Recurse -Force $HOME
```

不要因为命令使用了“清理”“重置”“同步”“修复”等友好词汇就自动批准。

### 最后看外部副作用

以下动作需要单独确认：

* 安装或升级依赖。
* 发送 HTTP 请求、上传文件或推送代码。
* 创建、修改或关闭云资源。
* 提交、推送、创建 PR、合并分支。
* 删除数据库、对象存储或远程分支。
* 发送邮件、消息、工单或评论。
* 修改系统服务、凭据、网络设置或防火墙。

批准时尽量只批准一次、只批准当前必要动作。不要把一串“以后类似命令都自动允许”当作方便的小优化。

## 命令规则与精细限制

如果本机版本支持命令规则，可以用规则把常见命令划分为允许、询问和禁止。规则语法与文件位置必须以当前版本文档为准；一些版本使用 `~/.codex/rules/` 下的 `.rules` 文件，并提供 `codex execpolicy check` 检查命令。

概念示例：

```text theme={null}
命令前缀：rg、git status、git diff
决策：allow

命令前缀：git push、curl、npm install
决策：prompt

命令前缀：rm -rf、格式化磁盘、读取私钥
决策：forbidden
```

精细规则不能替代沙箱。允许 `git` 不代表允许所有 Git 子命令；允许查看 PR 不代表允许推送分支。多命令串联时必须逐条检查，不能因为第一段命令安全就放过后面的删除或外发动作。

通常应遵循“最严格规则优先”的思路：禁止高于询问，询问高于允许。若版本的匹配优先级不同，以 `--help` 和规则检查结果为准。

## permission profiles 的谨慎用法

部分版本提供 Beta 的 permission profiles，用于更细地配置文件系统路径和网络域名。它可能允许：

* 以工作区为默认可写范围。
* 对某个目录设为只读。
* 对 `.env` 或密钥文件明确拒绝。
* 只允许少数网络域名。

概念性配置示例：

```toml theme={null}
default_permissions = "project-edit"

[permissions.project-edit]
extends = ":workspace"

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

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

[permissions.project-edit.network.domains]
"registry.example.com" = "allow"
```

这类配置有三个前提：

1. 先确认本机版本支持该键名、语法和内置 profile 名称。
2. 确认它与旧的 `sandbox_mode`、`--sandbox` 是否互斥。
3. 用实际读、写、联网测试验证规则，而不是只看配置文件没有报错。

路径规则通常需要处理具体路径优先级、通配符、符号链接和大小写差异。默认拒绝比默认允许更容易审查；网络也应优先采用域名白名单，而不是开放所有出站访问。

## 推荐组合

### 陌生仓库：先读后写

第一阶段：

```bash theme={null}
codex --sandbox read-only --ask-for-approval untrusted
```

让 Codex 完成：

* 读取项目结构和约定。
* 解释构建和测试入口。
* 指出潜在危险脚本。
* 提出修改计划，不落盘。

确认计划和范围后，第二阶段：

```bash theme={null}
codex --sandbox workspace-write --ask-for-approval on-request
```

这样把“理解代码”和“修改代码”分成两个可审查步骤。

### 日常本地开发

```toml theme={null}
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

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

### 只读 CI 检查

```bash theme={null}
codex --sandbox read-only --ask-for-approval never
```

同时在 CI 中：

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

### 隔离容器中的自动任务

只有在容器可销毁、凭据已清空、出站网络受限且任务可重复时，才考虑：

```bash theme={null}
codex --sandbox danger-full-access --ask-for-approval never
```

这不是主机安全配置，而是假设容器本身就是外层隔离边界。容器内仍可能泄露挂载目录、环境变量、Codex 登录凭据或内部网络访问权。

## 最小可重复测试

不要第一次就用真实项目和真实凭据测试权限。创建一个可删除的目录：

```bash theme={null}
mkdir -p /tmp/codex-permission-test
cd /tmp/codex-permission-test
git init
printf 'baseline\n' > README.txt
```

Windows PowerShell：

```powershell theme={null}
New-Item -ItemType Directory -Force "$env:TEMP\codex-permission-test"
Set-Location "$env:TEMP\codex-permission-test"
git init
Set-Content -Path README.txt -Value "baseline"
```

启动只读会话：

```bash theme={null}
codex --sandbox read-only --ask-for-approval on-request
```

输入：

```text theme={null}
读取 README.txt，说明它的内容；然后尝试创建 probe.txt，但不要绕过当前权限。
```

预期：

* `README.txt` 可以被读取。
* 创建 `probe.txt` 会被阻止或要求明确批准。
* 未经批准时，`probe.txt` 不应出现。

退出后启动工作区可写：

```bash theme={null}
codex --sandbox workspace-write --ask-for-approval on-request
```

输入：

```text theme={null}
创建 probe.txt，只写入一行 probe；不要访问工作区外，不要联网。
```

预期：

* `probe.txt` 在测试目录中出现。
* 内容只有预期的一行。
* 没有修改 `.git` 或其他目录。

测试网络默认值时，使用无敏感数据的请求：

```text theme={null}
尝试访问 https://example.com 并只返回状态；不要发送本地文件或环境变量。
```

在 `workspace-write` 下，预期可能是网络被拒绝、命令失败或请求审批；不要把某一种提示文字当成跨版本契约，重点是确认当前状态和实际边界。

测试工作区外写入时，先选择明确的临时目录，不要使用主目录：

```text theme={null}
尝试在工作区外的临时测试目录创建 outside.txt；如果需要批准先停下，不要继续。
```

预期是被沙箱阻止或请求批准。批准前核对绝对路径，测试完成后删除整个测试目录。

## 验收清单

每次调整权限后，至少保存以下证据：

* `codex --version` 的版本。
* 启动时使用的完整沙箱和审批参数。
* `/status` 显示的生效模式。
* 工作区目录和网络状态。
* 测试使用的命令、目标路径和预期结果。
* `git status --short` 和 `git diff --check` 的结果。
* 是否发生了外部请求、依赖安装、提交或推送。

代码修改任务还应运行项目自己的最小验证，例如：

```bash theme={null}
git diff --stat
git diff --check
npm test
```

或：

```bash theme={null}
pytest -q
```

不要照搬不存在于项目中的测试命令；先查看 README、`package.json`、`pyproject.toml`、Makefile 或 CI 配置。

如果权限测试发现模式与预期不同，先记录版本、平台和配置来源，再停止扩大权限。不要连续尝试多个高权限参数，最后却无法判断是哪一项产生了效果。

## 危险案例

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

错误做法：

```bash theme={null}
cd ~
codex --yolo
```

后果可能包括：

* 扫描并输出 SSH 配置、云凭据和历史命令。
* 修改主目录中的个人文件。
* 删除无法从 Git 恢复的目录。
* 读取浏览器、构建工具或包管理器的认证信息。

修复：立即停止会话，轮换可能暴露的凭据，检查文件和网络日志。不要只依赖“它说没有读取”。

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

错误做法：

```toml theme={null}
[sandbox_workspace_write]
network_access = true
```

然后让代理对未知项目运行安装脚本。风险在于依赖解析、安装钩子、远程脚本和错误日志都可能产生外部副作用。

改进方式：使用锁文件、可信镜像、隔离缓存和非生产凭据；先执行查看依赖的命令，再单独批准安装。

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

`npm test`、`make test` 或 `pytest` 可能加载项目配置、插件和脚本。恶意项目可以把数据外发、删除目录或修改权限。

改进方式：先读取脚本定义和测试入口，在 `read-only` 下审查，再在隔离环境中运行。对来源不明项目不要提供真实环境变量。

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

`git status` 和 `git diff` 是低风险审查命令，但 `git push` 会把内容发送到远端。不要因为两者都以 `git` 开头就建立过宽的允许规则。

推送前必须确认：

* 分支和远端正确。
* diff 不包含密钥和临时文件。
* 目标仓库和权限正确。
* 推送是任务明确要求，而不是代理自行决定。

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

`workspace-write` 不会自动清理 `.env`、证书和备份文件。代理可能在诊断时读取它们，也可能把内容放进日志、补丁或回复。

改进方式：使用脱敏副本、最小化工作区、隔离环境变量，并明确提示“不要读取或输出秘密文件”。必要时使用更细的路径拒绝规则。

## 回滚策略

### 未提交的代码修改

先保存当前 diff：

```bash theme={null}
git diff --binary > /tmp/codex-change.patch
git status --short
```

确认没有同事或其他自动化任务的改动后，回滚目标文件：

```bash theme={null}
git restore --source=HEAD -- path/to/file
```

不要对整个仓库直接执行恢复，除非已经核对所有未提交内容都属于本次实验。

### 配置修改

修改 `config.toml` 前先备份：

```bash theme={null}
cp ~/.codex/config.toml ~/.codex/config.toml.bak
```

Windows PowerShell：

```powershell theme={null}
Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.bak"
```

恢复时先退出 Codex 会话，再还原配置并用 `/status` 验证。不要在会话仍运行时假设配置已热加载。

### 已经发生外部副作用

文件修改可以用 Git 或备份恢复，但以下动作不能靠 `git restore` 撤销：

* 远端推送。
* 密钥泄露。
* 云资源创建或删除。
* 数据库写入。
* 外部消息和邮件发送。
* 依赖下载和供应链执行。

此时应立即停止自动化，保留日志，撤销或轮换凭据，使用服务自身的回滚、备份和审计机制。不要为了“清理痕迹”删除日志。

## 最终决策表

遇到新任务时，可以按下面顺序选择：

| 问题                    | 选择                       |
| --------------------- | ------------------------ |
| 只需要阅读、分析或给方案吗？        | `read-only`              |
| 需要修改当前项目代码吗？          | `workspace-write`        |
| 必须跨工作区访问，且环境可销毁吗？     | 才考虑 `danger-full-access` |
| 对来源不明的命令要逐项把关吗？       | `untrusted`              |
| 日常开发，希望工作区内顺畅、越界时询问吗？ | `on-request`             |
| 是否真的有隔离环境和自动化需求？      | 才考虑 `never`              |
| 是否需要联网？               | 默认关闭，按域名和任务最小化开放         |
| 是否包含密钥或客户数据？          | 移出工作区，或使用脱敏副本            |
| 是否能用 Git、快照或备份恢复？     | 不能恢复时不要提高权限              |

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

## 小结

本页最重要的不是记住一条“万能配置”，而是形成两步判断：

1. 沙箱决定 Codex 能触及的文件、命令和网络范围。
2. 审批策略决定它何时停下来请求人工确认。

日常开发通常从下面这组配置开始：

```toml theme={null}
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

陌生项目先收紧：

```bash theme={null}
codex --sandbox read-only --ask-for-approval untrusted
```

只读自动化可以使用 `read-only` + `never`，但仍要限制读取范围。`danger-full-access` + `never` 只适合隔离、可销毁且没有真实凭据的环境；不要把 `--yolo` 当成本机默认启动方式。

任何高权限操作都应满足：范围明确、数据脱敏、命令可解释、结果可验证、失败可停止、变更可回滚。做到这些，权限配置才真正成为控制手段，而不是一组看起来安全的字符串。

参考资料：`参考/codex/15-permissions.md`、`参考/codex/02-core-concepts.md`。