Codex sandbox_workspace_write.writable_roots 配置详解:精准放行仓库外共享目录且锁死 .git 只读

前后端分仓或共享类型包在当前目录之外,一写入就被 Codex 沙箱拦截,但直接开 danger-full-access 风险太大。本文详解 [sandbox_workspace_write] 的 writable_roots、临时目录开关与 .git 只读保护机制。

NNathaniel bigo··原创首发·AI 辅助撰写
13 分钟读完
资料核对于 2026-11-19 · 依据官方文档与公开资料整理 Plus 账号

结论先说

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

沙箱写权限受阻与 .git 只读报错分流排查

图:本站根据 OpenAI Codex 官方文档:Sandboxing 整理的示意图

  1. 检查是否用了相对路径或软链接。writable_roots 应填写规范的真实绝对路径;如果目标路径是符号链接,底层操作系统沙箱校验真实路径时可能会因为目标不在放行清单里而拦截,应填写解析后的实际目录。
  2. 确认当前处于 workspace-write 模式。如果命令行传入了 -s read-only,或者新版配置已启用 default_permissions 具名权限配置文件(详见 /guides/codex-permission-profiles-block-env-config),[sandbox_workspace_write] 就不会按旧规则生效。
  3. 临时跨仓任务直接用 --add-dir。如果你只是偶尔一次性联调隔壁仓库,不必永久写进全局 config.toml,启动命令行传入 codex --add-dir ../shared-types 就能仅对本次会话放行(跨仓联调实战见 /guides/codex-multi-repo-add-dir-frontend-backend-shared)。
  4. 需要按通配符屏蔽 .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,自助兑换无需交出账号密码,并可开具增值税发票;实时价格以商品页展示为准,售后执行掉订阅按剩余天数折退、封号不在质保范围的政策。

相关教程

参考资料

  • 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

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同产品的其他教程

  1. 01

    用 ChatGPT 整理家庭装修预算明细、隐蔽工程验收清单与主材优缺点对比表实战

    第一次装修面对几十页施工报价单、密密麻麻的水电防水隐蔽项目与五花八门的主材参数,极易踩坑增项。本文梳理用 ChatGPT 审查装修报价漏项、生成带公式的预算明细表、定制工地隐蔽工程验收单与主材对比表的实战提示词。

    ChatGPT0
  2. 02

    用 ChatGPT 做费曼学习法读书共读:反向追问检验自己是否真读懂专业书籍与整理书单笔记

    读完一本专业硬书常感觉「合上书就忘」,直接让 AI 概括全书又容易产生懂了的错觉。本文介绍用 ChatGPT 结合 Study Mode 与费曼学习法做反向追问共读,通过通俗复述、挑刺盲区到沉淀书单卡片的完整流程与提示词。

    ChatGPT0
  3. 03

    用 ChatGPT 做外贸产品多语种目录、展会邀约与客户跟进节奏表(附脱敏与本地化提示词)

    做外贸展会与海外推广时,手工翻译十几款产品目录费时且容易留下一堆中式英文,展后客户跟进也常缺节奏。本文梳理用 ChatGPT 先脱敏建术语库、再批量产出多语种目录、展前邀约函与展后 21 天跟进节奏表的实战流程与提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写高质量技术专栏文章、开源项目 Release Notes 与版本更新日志实战

    让 AI 直接凭空写技术文章容易满篇空洞套话,直接甩 Git 记录写更新日志又常常漏掉破坏性变更。本文整理用 ChatGPT 结合真实代码片段、压测数据与 PR 摘要,高效产出深度技术专栏、GitHub Release Notes 与 CHANGELOG 的实战工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做产品用户访谈纪要编码、提炼高频痛点需求池与 RICE 优先级打分实战

    手头攒了十几份用户访谈逐字稿,手工贴便利贴归纳痛点耗时又容易带入主观偏见。本文分享用 ChatGPT 完成脱敏检查、逐份开放式编码、跨样本聚类高频痛点并搭建 RICE 优先级打分表的 5 步实战流,附可直接复制的三段核心提示词。

    ChatGPT0
  6. 06

    ChatGPT 网页版上传超过 10 个文件或回形针附件按钮变灰怎么办:打包合并与配额限制排查

    在 ChatGPT 网页版批量分析文档时,常遇到一次选超 10 个文件被拦截或输入框回形针按钮变灰。本文依据 OpenAI 文件上传与存储说明,梳理 6 类常见报错的分流排查法,提供 ZIP 打包、本地合并与 Projects 复用方案及可直接复制的解包提示词。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~