结论先说
- 用
[sandbox_workspace_write]里的writable_roots精准扩权。当sandbox_mode = "workspace-write"时,Codex 默认只允许改动当前工作目录及临时目录;把仓库外需要联动的目录绝对路径写进writable_roots数组,即可在不破坏整体隔离的前提下精准放行。 - 工作区与
writable_roots内的.git与.codex默认锁死只读。这是 Codex 操作系统级沙箱的核心安全防线,即便目录本身可写,模型发起的命令也无法静默篡改.git提交历史、Git 钩子或.codex配置文件。 - 默认放行的
/tmp与$TMPDIR也可反向收紧。如果不希望沙箱内进程往系统临时目录落盘,可以把exclude_slash_tmp = true和exclude_tmpdir_env_var = true显式打开。 - 单次临时联调优先用
--add-dir,长期固定目录写进writable_roots,精细规则可升级 Permission Profiles。三者层层递进,彻底告别动辄切danger-full-access的高危习惯。 - 跨多仓联动修改与高频编译排障通常会话轮次更长,建议配好充足配额。国内若无外币卡,可在本站自助选购 ChatGPT Plus 或高配额 ChatGPT Pro,团队多人标准化部署也可查看 ChatGPT Business 团队定制。

图:本站根据 OpenAI Codex 官方文档:Sandboxing 整理的示意图
本文根据 OpenAI Codex 官方文档《Sandboxing》《Configuration Reference》整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 在本地同时维护前端、后端和公共
shared-types等多个同级目录,希望 Codex 在workspace-write模式下只多写一两个指定外部目录的开发者; - 运行构建工具或测试脚本时需要写入工作区外的缓存/产物目录,又不愿退回到
danger-full-access裸奔的工程师; - 好奇为什么在可写工作区里执行
git commit或改.git/hooks会被沙箱拒绝、想彻底摸清只读保护边界的用户。
一、[sandbox_workspace_write] 四个核心字段详解
在 Codex 沙箱体系中,sandbox_mode = "workspace-write" 是最常用的日常开发隔离档位(沙箱原理与操作系统实现可参考 /guides/codex-permissions-sandbox 与 /guides/codex-sandbox-macos-seatbelt-linux-bubblewrap-test)。它默认开放三个区域的写权限:当前工作目录(CWD)、/tmp 目录以及环境变量 $TMPDIR 指向的目录;磁盘其余路径全部只读。
当你需要在安全边界内微调这份可写清单时,可以在 config.toml 的 [sandbox_workspace_write] 表下配置四个官方字段:
writable_roots(字符串数组):列出当前工作区之外、额外允许写入的绝对路径列表,例如同级的共享协议库或独立构建输出目录;network_access(布尔值,默认false):控制沙箱内执行的子命令是否允许访问外部网络(例如npm install、pip拉依赖);exclude_tmpdir_env_var(布尔值,默认false):设为true时,撤销$TMPDIR环境变量目录的默认可写权限;exclude_slash_tmp(布尔值,默认false):设为true时,撤销/tmp目录的默认可写权限。
二、实战配置模板与 .git 只读保护机制
模板 1:放行仓库外共享类型包与构建缓存目录
假设你的主项目在 /workspace/web-app,但改接口时必须同步更新同级的 /workspace/shared-types 并把产物写入 /workspace/build-cache,可以在 ~/.codex/config.toml(或受信任仓库的 .codex/config.toml)中这样写:
toml
#:schema https://developers.openai.com/codex/config-schema.json
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
writable_roots = [
"/workspace/shared-types",
"/workspace/build-cache"
]
network_access = false
exclude_tmpdir_env_var = false
exclude_slash_tmp = false
Windows 环境使用正斜杠或转义反斜杠写入绝对路径即可,例如 "D:/projects/shared-types"。
模板 2:严格锁死系统临时目录的高安全配置
如果你希望所有临时编译产物都留在项目指定目录下,不污染宿主机的 /tmp 或 $TMPDIR,可以反向收紧:
toml
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
writable_roots = ["/workspace/isolated-tmp"]
exclude_tmpdir_env_var = true
exclude_slash_tmp = true
为什么 .git 和 .codex 在可写目录里仍然只读
很多用户第一次把仓库加进 workspace-write 或 writable_roots 时,发现修改业务代码完全正常,但一旦让 Codex 在沙箱里运行 git add、git commit 或改写 .codex/config.toml 就会遇到只读报错。
这不是配置失效,而是 Codex 的刻意保护机制:在工作区和所有 writable_roots 根目录下,沙箱都会把 .git、.codex 等元数据子目录重新挂载或标记为只读保护区域,防止失控命令静默篡改 Git 钩子(.git/hooks)、破坏分支历史或偷偷修改配置文件绕过沙箱。需要提交代码时,在交互模式(approval_policy = "on-request")下审批提权执行,或者由开发者本人直接在宿主机终端运行 git commit,是最稳妥的做法。
订阅与账号准备提示:跨仓库同步改接口、跑联调单测时,上下文文件和多轮校验消耗的会话额度明显高于单文件问答(限额说明见 /guides/codex-usage-limits)。如果高频触及额度上限,可在本站升级 ChatGPT Pro 充值 或 ChatGPT Pro 20x 高额度档;新注册 OpenAI 账号若卡在手机号验证,可查看 Codex 注册手机验证服务。
三、写权限受阻与边界排查分流
遇到「明明配了 writable_roots 还是写不进去」时,先按下面分流图定位原因,不要急着切无沙箱模式:

图:本站根据 OpenAI Codex 官方文档:Sandboxing 整理的示意图
- 检查是否用了相对路径或软链接。
writable_roots应填写规范的真实绝对路径;如果目标路径是符号链接,底层操作系统沙箱校验真实路径时可能会因为目标不在放行清单里而拦截,应填写解析后的实际目录。 - 确认当前处于
workspace-write模式。如果命令行传入了-s read-only,或者新版配置已启用default_permissions具名权限配置文件(详见 /guides/codex-permission-profiles-block-env-config),[sandbox_workspace_write]就不会按旧规则生效。 - 临时跨仓任务直接用
--add-dir。如果你只是偶尔一次性联调隔壁仓库,不必永久写进全局config.toml,启动命令行传入codex --add-dir ../shared-types就能仅对本次会话放行(跨仓联调实战见 /guides/codex-multi-repo-add-dir-frontend-backend-shared)。 - 需要按通配符屏蔽
.env时升级 Permission Profiles。[sandbox_workspace_write]面向目录级授权;若你既想放行外部目录,又想在可写目录里单独把**/.env设为"deny",推荐迁移到新版[permissions.<name>.filesystem]体系。
常见问题
问:能不能直接把用户主目录 ~ 或 / 写进 writable_roots 一劳永逸?
答:强烈不建议。把家目录或根目录放进 writable_roots 会让沙箱隔离形同虚设,一旦模型执行了误删或覆盖脚本,可能波及 ~/.ssh、系统配置和其他无关项目。应坚持最小权限原则,只列真正需要改写的具体业务子目录。
问:项目级 .codex/config.toml 里写了 writable_roots,为什么团队同事拉下来没生效?
答:首先,仓库级 .codex/config.toml 只有在当前项目被标记为受信任工作区后才会加载;其次,writable_roots 需要写绝对路径,不同同事电脑上的绝对目录路径往往不同,跨机协作建议把个人路径留在 ~/.codex/config.toml,或通过启动脚本传入 --add-dir。
问:国内没有外币信用卡,或者公司研发团队需要开增值税发票报销,怎么开通能跑 Codex 的订阅?
答:可在本站 AI 会员充值总览 按需选购 ChatGPT Plus、ChatGPT Plus 官网直充 或高配额的 ChatGPT Pro,团队多人统一部署可直接查看 ChatGPT Business 团队定制。支持支付宝、微信支付与 AlipayHK,自助兑换无需交出账号密码,并可开具增值税发票;实时价格以商品页展示为准,售后执行掉订阅按剩余天数折退、封号不在质保范围的政策。
相关教程
- Codex 权限审批与沙箱隔离模式详解
- Codex Permission Profiles 权限配置文件:屏蔽 .env 与最小权限实战
- Codex 多仓联调:--add-dir 联动前后端与共享包实战
- Codex 沙箱底层验证:macOS Seatbelt 与 Linux Bubblewrap 测试
参考资料
- OpenAI Developers 文档:Codex Configuration Reference — https://developers.openai.com/codex/config-reference
- OpenAI Codex 官方文档:Sandboxing — https://learn.chatgpt.com/docs/sandboxing
- OpenAI Codex 官方文档:Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
- OpenAI Codex GitHub 仓库 — https://github.com/openai/codex
0 条评论
还没有评论,来抢沙发~