Codex / 配置
Codex 权限
学习 Codex permission profiles 的文件系统、网络、路径、glob、Unix socket 与旧 sandbox 设置迁移方式。
权限配置解决什么
Codex permissions 用 profile 描述一个会话的本地访问边界。它比单独设置 sandbox_mode 更细，可以同时表达文件系统可读写范围、网络访问规则、Unix socket 例外和可复用 workspace roots。
如果只是选择一个简单模式，可以继续使用 read-only、workspace-write 或 danger-full-access。若团队需要“这个项目可写、这些目录只读、.env 永远不可读、只允许访问指定域名”这样的细粒度规则，就应使用 permission profile。
文件系统权限
文件系统条目使用 read、write、deny。更具体的条目覆盖更宽泛的条目；同一路径上 deny 优先于 write，write 优先于 read。
上面的配置把运行工具所需的最小平台路径设为只读，让 workspace root 可写，同时把 .devcontainer 保持只读，并禁止读取任何 .env 文件。这比“整个项目都可写可读”更适合长期团队配置。
[permissions.project-edit.filesystem]
":minimal" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"| 访问级别 | 含义 | 典型用途 |
|---|---|---|
| read | 允许命令读取文件和列目录，但不能创建、修改、重命名或删除。 | 文档、依赖源码、共享库、只读参考材料。 |
| write | 允许读取并修改路径下文件，包括创建、重命名和删除。 | 当前项目 workspace、生成输出目录、明确需要编辑的子项目。 |
| deny | 同时拒绝读取和写入，用于从更宽的授权中挖掉敏感子路径。 | .env、密钥、私有配置、无关仓库。 |
支持的路径形式
permission profile 支持内置路径别名、绝对路径和 home 相对路径。:workspace_roots 可以写嵌套子路径，且子路径必须留在 workspace root 内。
[permissions.audit.filesystem]
":root" = "read"
[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
"docs" = "read"
"generated" = "deny"| 路径形式 | 含义 | 是否支持子路径 |
|---|---|---|
| :root | 文件系统根目录。只有确实需要广泛读覆盖时才使用。 | 仅 . |
| :minimal | 常见工具运行所需的平台和运行时路径。 | 仅 . |
| :workspace_roots | 当前会话 workspace roots 和 profile 定义的 workspace roots。 | 支持 |
| :tmpdir / :slash_tmp | 系统临时目录或 /tmp。 | 仅 . |
| /absolute/path | 平台绝对路径，例如 macOS/Linux 的 /path 或 Windows 的 C:\path。 | 支持 |
| ~/path | 当前用户 home 下路径；Windows 也支持 ~\work。 | 支持 |
用 deny 保护敏感文件
当敏感文件位置不固定时，用 deny glob 比列 exact path 更实用。放在 :workspace_roots 下的 glob 会相对每个有效 workspace root 解释。
deny glob 主要用于拒绝读取。read/write glob 在不同平台沙盒里的可移植性较弱，所以读写授权优先使用精确路径或子树规则。
Linux、WSL 和原生 Windows 上，无边界的 ** deny-read 可能需要在沙盒启动前预展开。glob_scan_max_depth 控制扫描深度，数值越高启动前扫描工作越多。
[permissions.project-edit.filesystem]
glob_scan_max_depth = 3
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"复用 workspace roots
当一个 profile 总是需要同时处理多个目录时，可以在 profile 中声明可复用 workspace roots。激活后，:workspace_roots 规则会同时应用到运行时 roots 和 profile roots。
这适合 monorepo 外加共享库、前后端分仓联调、文档仓和产品仓一起修改的场景。不要用 ../other-repo 这种父级穿越；官方会拒绝离开 workspace root 的嵌套子路径。
[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true网络权限
在 profile 中设置 enabled = true 才允许网络。网络打开后默认是完整网络行为，因此多数 profile 应继续定义域名规则。
exact host 只匹配自身，*.example.com 只匹配子域，**.example.com 同时匹配 apex 和子域。deny 优先于 allow，用于排除广告、追踪、生产或敏感端点。
网络代理监听设置如 proxy_url、socks_url、enable_socks5 等通常保持默认，除非你正在和特定运行时集成。dangerously_* 网络键是特殊逃生口，不适合普通本地开发。
[permissions.project-edit.network]
enabled = true
[permissions.project-edit.network.domains]
"example.com" = "allow"
"*.example.com" = "allow"
"**.example.com" = "allow"
"ads.example.com" = "deny"本地和私网
Codex 默认对本地/私网目标有保护，降低 DNS rebinding 和误访问本机服务的风险。若确实需要访问本地服务，优先精确允许 localhost 或 IP literal。
只有当 profile 必须访问解析到本地或私网地址的 allowlisted 主机时，才设置 allow_local_binding = true。泛域名规则不应被当成本地访问例外。
[permissions.project-edit.network]
enabled = true
allow_local_binding = true
[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"Unix sockets
Unix socket 适合 Docker 等本地工具，但它也是强能力入口，应谨慎启用。可以显式 allow 或 deny socket 路径。
被 deny 的 socket 会从有效 allowlist 中移除。开启 Unix socket 代理时，监听端点仍应保持 loopback，避免把本机能力暴露成远程入口。
[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"从旧设置迁移
permission profiles 适合替代旧的 sandbox_mode + sandbox_workspace_write 组合，尤其当你想复用一套同时描述文件系统和网络行为的 profile。一次会话里建议使用一种体系，不要混用。
| 目标 | 推荐起点 | 说明 |
|---|---|---|
| 只读工作流 | :read-only 或自定义只读 profile | 只开放必要读取范围，适合审查和理解代码。 |
| 工作区编辑 | :workspace 或自定义 project-edit profile | 通过 :workspace_roots 写入项目，只额外开放必要缓存/临时目录。 |
| 无限制本地执行 | :danger-full-access | 仅在你明确需要最宽访问模型且外部环境已隔离时使用。 |
企业约束仍然优先
permission profile 描述用户本地默认姿态，但组织托管 requirements 仍可添加不能被用户配置放宽的限制。
学习检查清单
把本页内容落到真实任务中，用入口、上下文、权限、验证和团队规则五个维度检查是否真正掌握。
学习检查清单
读完本页后，不要只记住概念名。你应该能把“Codex 权限”放回 Codex 的真实工程流程里：任务从哪里发起，系统会加载什么上下文，哪些动作需要审批，结果如何验证，失败时如何回退。
如果这是配置或参考页面，要特别确认配置放在哪里、是否会被提交、是否包含敏感信息、是否会扩大默认权限，以及如何在失败时排查实际生效的设置。
- 能用自己的话说明本页解决的具体问题，而不是只复述标题。
- 能写出一个最小示例任务，并标明目标、范围、禁止事项和验收标准。
- 能判断哪些信息应该放进当前提示，哪些应该沉淀到项目规则或配置里。
- 能说明哪些长期规则应该写进 AGENTS.md，哪些运行行为应该交给 config.toml、permission profile、skills 和 MCP。
- 能在任务完成后检查 diff、命令输出、测试结果、截图或 PR 说明，而不是只相信自然语言总结。
如果要把本页用于团队培训，可以让学员用 Codex 完成一个小任务：先只读解释，再提交计划，再执行最小改动，最后用真实验证命令和人工 diff 审查收尾。
Codex 实操注意事项
围绕本地环境、权限升级、远程入口、自动化失败和回滚补齐 Codex 使用中最容易被忽略的执行细节。
Codex 实操注意事项
这一页会影响 Codex 的默认行为。配置前要先判断它会不会扩大文件写入、网络访问、工具调用或无提示执行能力，并为团队保留审计和回滚方式。
处理“Codex 权限”相关任务时，建议始终先确认当前 Git 状态和工作目录。Codex 可以很快完成修改，但它不会自动知道哪些未提交改动来自用户、哪些文件不能碰、哪些命令会影响生产环境。
- 本地任务优先使用低风险分支或工作树，完成后用 git diff 审查。
- 涉及安装依赖、联网、数据库、部署、push、删除、reset 时，先要求 Codex 解释影响再批准。
- 远程或协作入口生成的结果，也要回到 PR、CI、构建日志和测试证据中确认。
- 自动化任务要提前定义失败输出和退出条件，避免 Codex 在错误方向上反复尝试。
把 Codex 当成能执行命令的工程队友，而不是只会写文本的助手。越靠近真实系统，越需要明确边界、证据和回滚。