沙箱与安全

Codex 能在本地执行 Shell 与写文件，因此 沙箱（Sandbox） 与 审批（Approvals） 是产品核心，而非可选装饰。

两个独立维度

维度	配置键 / CLI	回答的问题
沙箱	`sandbox_mode`, `-s`	技术上允许读写的范围
审批	`approval_policy`, `-a`	越界时是否必须问人

二者 组合使用。例如工作区内自动执行 + 越界暂停：

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

sandbox_mode 取值

值	行为
`read-only`	只读，适合规划、审查、问答
`workspace-write`	可写当前工作区（及配置的 writable_roots）
`danger-full-access`	高权限，仅隔离环境使用

默认本地自动化推荐：workspace-write。

approval_policy 取值

值	行为
`untrusted`	不可信命令需批准
`on-request`	沙箱内自动，超出边界再询问（推荐）
`never`	不弹审批（CI 脚本常用，风险自负）

TUI 中 /permissions 可临时切换（如切到只读讨论方案）。

常见组合

场景	建议
日常本地开发	`workspace-write` + `on-request`
只读分析	`read-only` + `on-request`
受信 CI（只读 checkout）	`workspace-write` + `never` + 严格目录
完全信任的单人 VM	仍避免 `--yolo`，除非 VM 可一键销毁

--yolo（--dangerously-bypass-approvals-and-sandbox）：跳过沙箱与审批，禁止在主开发机默认使用。

config.toml 持久化

# ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
# 可写根目录扩展，见官方 Protected paths 文档
# writable_roots = ["..."]

扩展写目录优先用 --add-dir，而非直接 danger-full-access。

网络访问

默认本地执行时 网络常关闭或受限（视 OS 沙箱实现）。需要 npm install、拉 API 时会触发审批或策略升级。
Cloud 环境策略独立配置。

调试沙箱行为

使用与 Codex 内部一致的 sandbox helper：

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] -- echo test

# Linux
codex sandbox linux [--permissions-profile <name>] -- echo test

# Windows
codex sandbox windows [--permissions-profile <name>] -- echo test

用于验证某命令是否会被拒绝。

企业：requirements.toml

托管设备上，组织可通过 requirements.toml 禁止危险组合，例如：

禁止 approval_policy = "never"
禁止 sandbox_mode = "danger-full-access"

参见 Managed configuration。

安全清单

仓库无 .env 提交；AGENTS.md 写明勿读生产密钥
默认 workspace-write + on-request
敏感操作前 git diff + 人工 commit
MCP token 最小权限
CI 使用只读 token 与隔离 runner

下一步

配置与 CLI 参考：全部配置项索引
架构与运行机制：沙箱在 Agent 循环中的位置

#沙箱与安全

#两个独立维度

#sandbox_mode 取值

#approval_policy 取值

#常见组合

#config.toml 持久化

#网络访问

#调试沙箱行为

#企业：requirements.toml

#安全清单

#下一步