Codex workspace-write 怎么配？Sandbox 模式与权限指南

Codex workspace-write 允许模型生成的命令在当前工作目录和明确配置的 writable roots 中写入文件。它不等于“自动批准所有操作”，也不会自动打开网络。 Sandbox 决定命令可以触达哪里；approval policy（批准策略）则单独决定 Codex 什么时候必须停下来，请求越过当前边界的授权。

普通代码库任务可以从 workspace-write 加 on-request 批准开始。只需要检查、不应该修改文件时使用 read-only。不要为了解决一个路径被拦截的问题直接切到 danger-full-access；更安全的做法是只增加任务真正需要的目录，或者收窄任务范围。

本文依据 OpenAI 官方 Codex 文档与开源 openai/codex 仓库撰写，事实核验于 2026 年 9 月 11 日。它提供配置和排错方法，不代表对每一种操作系统或企业托管环境作出安全保证。

三种 Codex Sandbox 模式有什么区别

Codex 当前为模型生成的命令提供三种常用 Sandbox 模式：

OpenAI 的 Agent 批准与安全指南建议版本控制目录使用 workspace-write 加按需批准。官方 Developer Commands 参考也明确建议：只是需要多写一个目录时，应增加具体路径，而不是强行改成 danger-full-access。

如果你还没决定任务应该留在本地代码库，还是交给远程环境，可以先比较 Codex Cloud 与 Codex CLI的权限边界。

Sandbox 和 approval policy 是两层控制

两项设置回答的是不同问题：

• Sandbox 模式： 进程在不离开 Sandbox 的情况下，可以触达哪些文件、目录和命令网络边界？
• Approval policy： 某个动作需要越过当前边界时，Codex 什么时候必须暂停并请求批准？

例如，下面的命令选择 Workspace 写入边界，并保留交互式升级授权：

codex --sandbox workspace-write --ask-for-approval on-request

留在当前 Sandbox 内的命令可以直接运行；写入 Workspace 之外或访问被拦截网络的动作可能需要批准。把 approval_policy 改成 never 并不会扩大 Sandbox，只会取消询问机会，因此越界动作必须继续被拦截或失败。

--dangerously-bypass-approvals-and-sandbox 又是另一回事：它会同时关闭两层控制。OpenAI 把这条路径标为高风险，只建议在已经独立隔离的环境中使用，不应该成为普通 Codex 配置。

当前 Workspace 到底包括哪里

对于 CLI，--cd 会在 Codex 开始处理任务前设置工作目录，这个目录就是任务的主要 Workspace Root。交互式 Session 中应使用 /status 查看实际 Workspace 与权限，不要想当然地认为当前 Terminal Tab、Git Repository 和可写边界完全相同。

workspace-write 下有几条重要路径规则：

1. 当前工作目录可以写入。
2. sandbox_workspace_write.writable_roots 会增加其他绝对路径，不会替换当前目录。
3. --add-dir /absolute/path 可以只为当前一次 CLI 运行增加一个可写目录。
4. /tmp 和环境临时目录默认可能属于 Workspace；可以分别在配置中排除。
5. OpenAI 会在默认可写 Root 中把 .git、.agents 和 .codex 递归保护为只读；如果 .git 是指针文件，它指向的真实 Git 目录也受保护。

可写清单并不是完整的数据保密策略。Writable Root 说明命令能在哪里修改文件，但不能用来证明其他用户文件一定不可读。如果读取隔离也很重要，应使用合适的 Permission Profile，或者外层 Container / Virtual Machine，只向任务暴露必要数据。

Codex Agent 页面汇总了 Agent.Space 当前 Codex 入口与相关文章；它的产品边界和本地 Codex CLI Sandbox 不是一套权限系统。

一份保守、可审计的 config.toml

下面的配置保留交互式批准，把普通写入限制在项目和一个生成物目录，移除默认临时目录写权限，并保持命令网络关闭：

approval_policy = "on-request"sandbox_mode = "workspace-write"
[sandbox_workspace_write]network_access = falseexclude_slash_tmp = trueexclude_tmpdir_env_var = truewritable_roots = ["/absolute/path/to/generated-artifacts"]

请把示例替换成真实存在的绝对路径。任务只需要一个输出目录时，不要加入整个 Home、磁盘 Root 或范围很大的父目录。把配置放在正确的用户或管理员配置层；面对不熟悉的仓库，应先审查 Project-local Configuration，再决定是否信任。

如果只想在一次运行中设置边界，可以把范围直接写进命令：

codex \  --cd /absolute/path/to/repository \  --sandbox workspace-write \  --ask-for-approval on-request \  --add-dir /absolute/path/to/generated-artifacts

这条命令不会启用出站网络，网络仍然是单独的决定。

网络边界要单独处理

本地 workspace-write 模式默认关闭命令网络。只有任务有明确需求时才启用：

[sandbox_workspace_write]network_access = true

这个 Boolean 会授予命令网络访问，但不会限制目标域名。OpenAI 另外提供 network_proxy 功能来控制域名策略。只打开 Proxy 不会自动授予网络；只打开网络而不启用 Proxy，则会允许直接出站访问。

排错时必须分清这一点。依赖安装失败，可能是目标路径不可写、命令网络关闭、Registry 被目标规则拦截，也可能是缺少认证。批准或放宽错误的层级既解决不了根因，也可能让任务触达过大的范围。

如果要同时检查 Secret、外部指令、破坏性命令与结果审阅，可以继续阅读 Coding Agent Workspace 安全清单。

workspace-write 被拒绝时怎么排查

Codex 报告动作被阻止时，按下面顺序检查：

1. 识别具体操作

记录命令、目标路径，以及它真正需要的是读取、写入、网络连接、本地端口还是外部副作用。“Permission denied” 本身还不是诊断结论。

2. 查看实际 Workspace

交互式 Session 使用 /status。脚本运行则检查 --cd 和每一个 --add-dir。一个 Terminal 已经打开某个仓库，并不代表另一个 Codex 进程也把它作为当前 Workspace。

3. 检查 Sandbox 模式

只读审阅时有意使用 read-only。任务必须修改代码库时使用 workspace-write，不要直接跳到 Full Access。

4. 对照保护路径和可写路径

确认目标位于当前目录或某个狭窄的额外 Root 中。如果目标是 .git、.agents 或 .codex，即使父仓库可写，默认保护仍会生效。

5. 独立诊断网络

命令需要下载 Package 或调用 API 时，检查 sandbox_workspace_write.network_access 和现有目标策略。一次写入批准不能被解释为网络授权。

6. 在 Sandbox 中复现

OpenAI 提供 codex sandbox macos、codex sandbox linux 和 codex sandbox windows Helper，用相应 Codex Policy 运行一条命令。macOS 还可以使用 --log-denials，在命令结束后输出 Sandbox 拒绝记录。不同操作系统的执行方式不同，应在真正失败的环境中复现。

7. 审查最终 Diff

命令能够运行，只能证明它通过了当前边界，不能证明修改正确。合并前仍需检查文件、运行相关验证，并拒绝无关变化。

常见配置误区

• 用 danger-full-access 解决一个路径错误。 应增加一个必要目录，或者把输出移回 Workspace。
• 把批准当成 Sandbox。 Approval Prompt 是决策点，不是长期文件系统策略。
• 以为 writable_roots 会替换 Workspace。 它是在当前工作目录之外增加 Root。
• 加入相对路径或范围过大的 Root。 应使用一个你确实允许被修改的具体绝对路径。
• 以为 workspace-write 会开启网络。 网络必须单独启用。
• 忽略受保护的仓库元数据。 默认策略下 .git、.agents 和 .codex 仍为只读。
• 关闭询问就期待获得更多权限。 approval_policy = "never" 改的是交互，不是 Sandbox 边界。
• 在不同环境中验证。 macOS、Linux、Native Windows、WSL2 和外层 Container 的隔离方式不同。

用完成任务所需的最小边界

检查时用 read-only，普通代码修改用 workspace-write，输出目录在项目之外时只增加一个准确 Root。命令不需要外网就保持 Network Off，并用 on-request Approval 处理例外动作。

如果你想使用托管项目环境，而不是配置本地 CLI，可以把这套边界与在 Agent.Space 使用 Codex 的流程和公开的 Agent.Space Workspace进行比较。两种产品不是同一套权限模型；选择前应确认文件放在哪里、谁能继续任务，以及哪些动作仍然可审查。

官方信源

• OpenAI：Agent 批准与安全
• OpenAI：Configuration Reference
• OpenAI：Developer Commands
• openai/codex：workspace-write 权限模板