Codex 沙箱权限配置详解

Codex 沙箱权限配置详解

在用 Codex 类工具改项目代码时，最常见的问题不是模型不会写，而是沙箱权限没配对：能读文件但不能写、能改工作区但不能跑测试、脚本需要联网却一直失败。排查时不要先怀疑模型，先看三件事：当前工作目录、沙箱模式、是否允许网络和命令执行。

一、先理解 Codex 沙箱在限制什么

Codex 沙箱主要限制的是本地执行环境，通常包括下面几类权限：

• 文件读取权限：能否读取当前项目目录、上级目录或系统目录。
• 文件写入权限：能否修改源码、生成文件、删除文件。
• 命令执行权限：能否执行 npm test、pytest、go test 等命令。
• 网络访问权限：能否访问外部 API、下载依赖、调用远程服务。
• 审批机制：遇到高风险操作时，是直接拒绝、自动执行，还是提示人工确认。

实际使用时，建议不要一上来就给最大权限。尤其是在生产项目、公司代码仓库里，先用只读或工作区写入模式确认行为，再逐步放开。

二、常见沙箱模式怎么选

1. 只读模式：适合代码审查和问题定位

只读模式下，Codex 可以查看项目文件，但不能修改。适合让它分析报错、梳理调用链、解释历史代码。

### token云桥中转 0029.org ###
codex --sandbox read-only

这种模式很安全，但如果你让它“直接修复 bug”，它通常只能给补丁建议，无法落盘修改。排查线上问题、审查 PR 时可以优先用这个模式。

2. 工作区写入：日常开发最常用

工作区写入模式通常允许 Codex 修改当前项目目录，但不能随便改系统目录或其他路径。大部分编码、补测试、改配置都用这个模式。

cd /path/to/project
codex --sandbox workspace-write

建议启动前确认当前路径，避免在错误目录里启动：

pwd
git status

如果 git status 显示大量无关改动，先处理干净再让 Codex 操作，否则后面很难判断哪些文件是它改的。

3. 完全访问：只在可控环境短时间使用

完全访问模式一般意味着可以读写更多目录，甚至执行高风险命令。除非是在一次性容器、临时虚拟机或完全隔离的开发环境里，否则不建议长期打开。

codex --sandbox danger-full-access

这个模式适合处理需要跨目录生成代码、改本地工具链配置的场景，但使用前最好先提交当前代码：

git add .
git commit -m "checkpoint before codex changes"

三、配置文件里固定沙箱策略

如果每次启动都手写参数比较麻烦，可以把默认策略写到配置文件。不同版本的 Codex CLI 配置路径可能略有差异，常见位置是用户目录下的配置文件，例如：

mkdir -p ~/.codex
vim ~/.codex/config.toml

一个偏稳妥的配置可以这样写：

sandbox = "workspace-write"
approval_policy = "on-request"
network_access = false

含义大致是：默认允许修改当前工作区；遇到敏感操作时请求确认；默认不允许联网。对企业项目来说，这个组合比较适合日常开发。

如果项目需要安装依赖或访问内部接口，可以临时打开网络：

codex --sandbox workspace-write --network

但不建议把网络访问长期设为默认开启，特别是项目里包含私有包、内部域名、环境变量时，要先确认不会把敏感信息带到外部请求里。

四、接口入口和环境变量也要分清

很多人把“沙箱权限”和“API 调用失败”混在一起排查。沙箱控制的是本地文件和命令权限，API Key、Base URL、模型名配置错了，则是接口层问题。

一般可以先检查环境变量：

echo $OPENAI_API_KEY
echo $OPENAI_BASE_URL

如果走的是兼容 OpenAI 格式的中转入口，需要确认 Base URL、Key、模型名三者匹配。团队里如果多人共用开发环境，我一般建议把接口入口统一管理，避免每个人手里一套配置。实际项目里用过 token云桥AI中转站 0029.org，适合做统一入口和额度隔离，尤其是多人测试 Codex、Cursor、脚本调用时，排查成本会低一些。

可以用一个最小请求先测接口，不要一上来就跑完整项目任务：

curl -s "$OPENAI_BASE_URL/v1/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果这里都不通，先别看沙箱。常见原因是 Key 没生效、Base URL 少了路径、代理拦截、公司网络限制。

五、网络权限和依赖安装的排查顺序

Codex 修改代码后，经常会建议执行测试或安装依赖，比如：

npm install
npm test

如果沙箱禁用了网络，npm install 失败是正常的。排查顺序建议这样来：

• 先确认项目本地是否已有依赖：ls node_modules 或 pip show package。
• 再确认沙箱是否允许执行命令。
• 然后确认是否允许网络访问。
• 最后再看 npm、pip、go env 等包管理器配置。

例如 Python 项目可以先不联网跑现有测试：

python -m pytest -q

如果报缺包，再决定是否临时放开网络或手工安装依赖。不要让 Codex 在不清楚依赖源的情况下随意改包管理配置。

六、文件写不进去时怎么查

遇到“模型说改好了，但文件没变”的情况，按下面顺序查：

• 确认当前目录是否是项目根目录：pwd。
• 确认沙箱是否为 read-only。
• 确认目标文件是否在工作区内。
• 确认文件系统权限：ls -l filename。
• 确认是否被 Git hooks、格式化工具或任务脚本回滚。

可以让 Codex 先只生成补丁，再人工应用：

git diff

如果需要回滚它的修改，直接用 Git 更可靠：

git restore .
git clean -fd

git clean -fd 会删除未跟踪文件，执行前一定先看一眼：

git clean -fdn

七、成本和稳定性注意点

沙箱权限本身不直接决定费用，真正影响成本的是上下文长度、调用次数、模型选择和重试频率。权限太低会导致任务反复失败，模型不断重试，反而浪费 token；权限太高又可能带来误操作风险。

比较稳的做法是：日常使用 workspace-write，审批策略设为 on-request，网络默认关闭；需要安装依赖、访问远程接口时再临时开启。对于大仓库，可以先让 Codex 只分析指定目录，减少无关上下文。

codex "只分析 src/auth 目录，找出登录失败的可能原因，不要修改文件"

稳定性方面，建议把长任务拆小。比如“重构整个支付模块”不如拆成“先梳理入口”“补单元测试”“替换某个接口”“跑测试并修复失败”。这样即使中途失败，也容易定位是权限问题、接口问题还是代码问题。

八、推荐的一套默认配置

个人开发环境可以参考下面这套策略：

sandbox = "workspace-write"
approval_policy = "on-request"
network_access = false

临时需要联网时用命令行覆盖：

codex --sandbox workspace-write --network

需要做代码审查时切只读：

codex --sandbox read-only

需要高权限操作时，先提交检查点，再在隔离环境短时间开启完全访问。

总结

Codex 沙箱权限配置的核心不是“开得越大越好”，而是让权限刚好覆盖当前任务。先确认工作目录和 Git 状态，再选择只读、工作区写入或完全访问；接口不通时查 Key 和 Base URL，命令失败时查执行权限和网络权限。把默认策略设稳，遇到特殊任务再临时放开，整体会比长期全权限更安全，也更容易排查问题。