Codex 工程化落地指南 05：.codex/config.toml 与权限配置——沙箱： 审批、网络访问与可信项目

一：🎯 教程定位

上一篇教程通过AGENTS.md解决了“Codex 应该遵守什么开发规则”的问题。

但是，AGENTS.md只是行为说明，并不是系统级安全边界。

即使规则中写着：

⚠️注意：禁止访问项目外目录。 禁止联网下载未知程序。 禁止执行生产部署。 禁止读取云平台密钥。

如果 Codex 实际拥有完整文件系统、网络和 Shell 权限，这些要求仍然只是一层指令约束。

真正的工程化配置应分成两部分：

✅推荐：AGENTS.md → 告诉 Codex 应该怎么做

config.toml → 限制 Codex 实际能做什么

本篇将重点配置：

⚠️注意：用户级配置 项目级配置 配置优先级 项目可信状态 文件系统沙箱 命令审批策略 网络访问 额外可写目录 Shell 环境变量过滤 命名配置 Profile CLI 临时覆盖 CI 非交互模式 危险权限防护

最终形成三种常用模式：

只读审查模式 日常开发模式 隔离自动化模式

二：📌 教程信息

目标读者：Codex 中级用户、开发人员、DevOps 工程师 预计时长：约 1.5 小时 难度等级：★★☆ 环境：Windows 11 + WSL2 Ubuntu 案例项目：城市随手拍平台

三：🎯 学习目标

完成本篇后，你应该能够：

⚠️注意：理解 Codex 配置文件的加载顺序 区分用户级配置与项目级配置 配置 read-only、workspace-write 和 danger-full-access 配置 untrusted、on-request 和 never 审批策略 为未知仓库设置只读模式 为日常开发设置低摩擦权限 控制 workspace-write 模式的出站网络 限制传递给子进程的环境变量 标记项目为 trusted 或 untrusted 使用命名 Profile 切换权限 使用 CLI 参数进行单次覆盖 为 codex exec 配置非交互权限 识别并避免危险配置组合

第一部分：理解 Codex 配置体系

四：📁 配置文件存放位置

Codex 默认使用以下用户目录：

~/.codex

在 WSL2 Ubuntu 中，通常是：

/home/developer/.codex

用户级主配置文件：

~/.codex/config.toml

项目级配置文件：

项目根目录/.codex/config.toml

示例：

city-snapshot-platform/ ├── AGENTS.md ├── .codex/ │ └── config.toml ├── server/ ├── citizen-h5/ └── admin-web/

两者作用不同。

用户级配置

适合保存个人默认设置：

默认沙箱 默认审批策略 Shell 环境变量规则 模型和服务提供方 个人 MCP 配置 通知和遥测配置 可信项目列表

项目级配置

适合保存仓库需要的共同配置：

项目沙箱要求 项目是否允许联网 额外可写缓存目录 项目根目录标识 项目专用规则或 Hook

项目级配置应提交到 Git 前进行安全审查。

五：🔢 配置优先级

Codex 配置从高到低为：

1. CLI 参数和 --config 临时覆盖
2. 项目 .codex/config.toml
3. --profile 指定的 Profile
4. 用户 ~/.codex/config.toml
5. 系统配置
6. Codex 内置默认值

例如用户配置：

sandbox_mode = "read-only"

项目配置：

sandbox_mode = "workspace-write"

如果项目已被标记为可信，进入该项目后，项目配置将覆盖用户配置。

如果启动时执行：

codex --sandbox read-only

CLI 参数又会覆盖项目配置。

因此，排查权限问题时，不能只检查一个文件。

应同时检查：

启动命令 项目 .codex/config.toml 使用的 Profile 用户 config.toml

六：🔗 从项目根目录到当前目录的配置链

Codex 会从项目根目录向当前工作目录查找.codex/config.toml。

示例：

city-snapshot-platform/ ├── .codex/ │ └── config.toml └── server/ ├── .codex/ │ └── config.toml └── src/

当你从：

city-snapshot-platform/server/src

启动 Codex 时，可能依次加载：

根目录/.codex/config.toml server/.codex/config.toml

如果两者设置相同字段，距离当前目录更近的配置优先。

例如根目录：

sandbox_mode = "workspace-write"

后端目录：

sandbox_mode = "read-only"

从server/内运行时，后端配置将覆盖根目录配置。

这适用于需要对敏感子项目设置更严格权限的场景。

第二部分：沙箱模式

七：🔒 什么是沙箱

沙箱控制 Codex 执行命令时能够访问和修改的文件系统范围，以及是否能够直接访问网络。

沙箱不决定 Codex“想不想”执行某个操作，而是决定该操作在技术上是否被允许。

常用模式：

read-only workspace-write danger-full-access

八：🔒read-only：只读模式

配置：

sandbox_mode = "read-only"

适合：

首次阅读陌生仓库 代码审查 架构分析 安全检查 需求影响分析 检查第三方项目 CI 中的只读报告任务

在该模式中，Codex可以读取项目内容，但不能直接修改文件。需要执行超出当前只读边界的操作时，会根据审批策略请求批准或被拒绝。

推荐组合：

sandbox_mode = "read-only" approval_policy = "untrusted" approvals_reviewer = "user"

更加安静的非交互只读模式：

sandbox_mode = "read-only" approval_policy = "never"

此时 Codex 不会弹出审批请求，所有沙箱之外的操作直接无法执行。

适合：

CI 代码扫描 文档一致性检查 仓库结构报告 静态审查任务

九：📝workspace-write：工作区写入模式

配置：

sandbox_mode = "workspace-write"

这是日常本地开发的推荐模式。

Codex 可以：

读取当前项目 修改当前项目文件 创建项目内文件 运行常规本地测试 运行 Lint 运行类型检查 执行构建

但默认边界仍然是当前工作区。

当 Codex 需要：

修改项目外文件 访问额外目录 使用被限制的网络 执行沙箱外命令

会根据审批策略处理。

推荐组合：

sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user"

这意味着：

项目内常规操作自动进行 越过边界时询问用户 审批由用户完成

十：⚠️danger-full-access：完全访问模式

配置：

sandbox_mode = "danger-full-access"

该模式会移除文件系统和网络沙箱边界。

Codex 可能访问：

项目外目录 用户 Home 目录 SSH 配置 云平台配置 Docker Socket 系统工具 网络资源 其他项目

如果再配置：

approval_policy = "never"

就形成：

没有沙箱 没有审批

这是最危险的组合。

不适合作为：

个人电脑默认配置 普通项目配置 未知仓库配置 带生产凭证的开发机配置

只有在以下环境中才可谨慎评估：

一次性容器 临时虚拟机 隔离 CI Runner 没有生产凭证 没有重要文件 任务结束后销毁

即使外部环境已经隔离，也应限制：

Git 权限 云 IAM Secret 网络出口 可访问仓库

十一：📊 三种沙箱对比

日常工程建议：

⚠️注意：80% 任务： workspace-write

首次接触仓库： read-only

外部隔离自动化： 根据风险评估使用 workspace-write 或完全访问

第三部分：审批策略

十二：✅ 什么是审批策略

沙箱决定操作边界，审批策略决定 Codex 在需要越过边界或执行敏感命令时如何处理。

常用策略：

untrusted on-request never

十三：🔒untrusted

配置：

approval_policy = "untrusted"

Codex只会自动执行被视为可信的安全读取操作。

可能修改状态、运行外部程序或具有风险的命令需要用户批准。

适合：

✅推荐：陌生仓库 教学环境 敏感项目 新成员初次使用 安全优先的代码审查

推荐组合：

sandbox_mode = "read-only" approval_policy = "untrusted"

这种组合会频繁询问，但安全边界清晰。

十四：💬on-request

配置：

approval_policy = "on-request"

Codex 在沙箱内正常工作，只有需要超出边界时才发起审批。

适合：

日常功能开发 测试驱动修复 局部重构 Docker 构建 项目内文档更新

推荐组合：

sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user"

这是本系列推荐的默认开发组合。

十五：🚫never

配置：

approval_policy = "never"

Codex 不会暂停等待审批。

注意，这不等于自动获得所有权限。

如果当前使用：

sandbox_mode = "read-only" approval_policy = "never"

那么禁止的写入操作会直接失败。

如果使用：

sandbox_mode = "workspace-write" approval_policy = "never"

Codex 可以在工作区内自动修改和运行命令，但无法通过请求批准来突破沙箱。

适合：

CI 非交互任务 隔离容器中的自动检查 明确边界的批量修改 没有用户可以实时审批的任务

不适合与danger-full-access组合成普通本地默认配置。

十六：🔄on-failure已不推荐

旧配置中可能看到：

approval_policy = "on-failure"

当前应改成：

approval_policy = "on-request"

交互式开发使用on-request，非交互任务使用never，更加清晰。

十七：👤 审批者

配置：

approvals_reviewer = "user"

表示审批请求交给用户。

部分环境还支持：

approvals_reviewer = "auto_review"

表示由自动审查 Agent 处理符合条件的审批请求。

本系列基础阶段推荐：

approvals_reviewer = "user"

因为开发人员需要先理解：

哪些操作触发审批 为什么触发 操作将修改什么 是否会访问网络

等团队建立稳定规则后，再考虑自动审查。

第四部分：推荐的用户级配置

十八：🛠️ 创建用户配置

在 WSL 中执行：

mkdir -p ~/.codex chmod 700 ~/.codex touch ~/.codex/config.toml chmod 600 ~/.codex/config.toml

编辑：

nano ~/.codex/config.toml

十九：👍 日常开发推荐配置

# 日常本地开发默认配置 sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" # WSL + NVM 环境通常依赖 Shell 初始化。 # 确认 Node、Python 和项目工具路径稳定后，可再评估关闭。 allow_login_shell = true [sandbox_workspace_write] network_access = false [shell_environment_policy] inherit = "core" ignore_default_excludes = false exclude = [ "AWS_*", "AZURE_*", "GOOGLE_*", "GCP_*", "*TOKEN*", "*SECRET*", "*PASSWORD*", "*PRIVATE_KEY*" ]

配置含义：

⚠️注意：允许修改项目 越界时询问 审批交给用户 工作区内默认禁止直接出站联网 过滤常见云密钥和 Secret 环境变量

二十：❓ 为什么不直接继承全部环境变量

开发终端中可能存在：

AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AZURE_CLIENT_SECRET GOOGLE_APPLICATION_CREDENTIALS DATABASE_URL NPM_TOKEN GITHUB_TOKEN

如果子进程完整继承这些变量，Codex 执行的任意工具也可能读取它们。

推荐至少使用：

[shell_environment_policy] inherit = "core" ignore_default_excludes = false

ignore_default_excludes = false会保留默认的敏感变量过滤机制。

不要轻易设置：

ignore_default_excludes = true

否则包含KEY、SECRET、TOKEN等名称的变量可能被传递给 Codex 启动的子进程。

二十一：🔐 更严格的环境变量配置

用于高敏感项目：

[shell_environment_policy] inherit = "none" ignore_default_excludes = false include_only = [ "PATH", "HOME", "USER", "LANG", "TERM", "SHELL", "TMPDIR" ]

这种模式安全性更高，但可能导致：

NVM 无法加载 Python 环境路径丢失 Java Home 丢失 私有包管理器配置不可用

因此应配合项目工具链逐项验证。

不要为了修复路径问题直接改成继承全部变量，应明确添加必要变量。

第五部分：项目可信状态

二十二：🛡️ 为什么需要信任项目

项目仓库中的.codex/config.toml可能改变：

沙箱模式 审批策略 网络权限 可写目录 Hook 本地规则

恶意仓库可能尝试：

扩大写入范围 启用网络 添加执行 Hook 降低审批等级 影响 Codex 命令行为

因此，Codex 只有在项目被标记为可信时，才会加载项目级.codex/配置层。

项目被标记为不可信时：

忽略项目 .codex/config.toml 忽略项目本地 Hook 忽略项目本地规则 继续加载用户级和系统级配置

二十三：🔍 信任项目之前检查什么

首次克隆仓库后，先检查：

find .codex -maxdepth 3 -type f -print 2>/dev/null

查看项目配置：

sed -n '1,240p' .codex/config.toml 2>/dev/null

查看 Hook：

sed -n '1,240p' .codex/hooks.json 2>/dev/null

重点搜索：

rg -n \ "danger-full-access|approval_policy|network_access|writable_roots|command|hook" \ .codex 2>/dev/null

只有在确认以下内容后再信任：

⚠️注意：仓库来源可信 项目配置经过审查 没有未知 Hook 没有扩大到敏感目录 没有启用不必要网络 没有危险权限组合

二十四：🔑 在用户配置中标记项目

WSL 路径示例：

[projects."/home/developer/projects/city-snapshot-platform"] trust_level = "trusted"

未知或暂不信任的仓库：

[projects."/home/developer/projects/third-party-demo"] trust_level = "untrusted"

路径应使用真实绝对路径。

查看路径：

git rev-parse --show-toplevel

不要根据 Windows 文件资源管理器路径填写 WSL 项目。

错误示例：

C:\Users\developer\projects\city-snapshot-platform

正确示例：

/home/developer/projects/city-snapshot-platform

二十五：🌳 Worktree 也要单独注意

Git Worktree 可能位于：

/home/developer/worktrees/fea-yonghuzhuce

它与主仓库路径不同。

如果使用路径级可信配置，需要确认 Worktree 是否也被识别为可信项目。

不要默认认为：

主仓库可信

所有任意位置的 Worktree 都自动可信

并行开发时应检查每个 Worktree 的生效配置。

第六部分：项目级配置

二十六：🛠️ 创建项目配置

在项目根目录执行：

cd ~/projects/city-snapshot-platform mkdir -p .codex touch .codex/config.toml

项目配置可以进入 Git：

.codex/config.toml

但必须经过代码审查。

二十七：👍 推荐项目配置

# 城市随手拍平台 Codex 项目配置 sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" project_root_markers = [".git"] [sandbox_workspace_write] network_access = false

该配置表示：

项目内可以修改 项目外操作需要批准 不默认允许出站网络 使用 Git 根目录作为项目根

二十八：🚫 哪些配置不应写在项目文件中

以下配置应放在用户级配置，而不是提交到仓库：

模型服务提供方认证 OpenAI API 路由 企业模型代理 用户通知命令 个人遥测配置 个人认证文件 个人 Profile 选择

项目配置不应包含：

API Key Token 用户名密码 个人 Home 路径 个人专用代理凭证

部分涉及模型提供方、认证、通知和遥测的字段即使写入项目配置，也会被 Codex 忽略并产生警告。

二十九：⚠️ 项目配置不能代替团队安全策略

即使项目写着：

sandbox_mode = "read-only"

用户仍可能通过 CLI 临时覆盖：

codex --sandbox workspace-write

因为 CLI 参数优先级更高。

因此企业治理还需要：

受管配置 操作系统权限 仓库保护 CI Runner 隔离 云 IAM Secret 管理 审计

项目配置主要用于提供安全默认值，而不是不可绕过的企业强制策略。

第七部分：网络访问

三十：🌐 本地工作区网络

在workspace-write模式中，可以通过：

[sandbox_workspace_write] network_access = false

显式关闭沙箱内出站网络。

需要联网安装依赖时，可以：

临时批准网络访问 或为本次启动进行 CLI 覆盖

一次性覆盖：

codex \ --config sandbox_workspace_write.network_access=true

不建议为了偶尔安装一次依赖，永久把所有项目都设置为网络开放。

三十一：🌐 什么时候需要网络

常见联网任务：

npm install pnpm install pip install Maven 下载依赖 拉取容器镜像 查询外部技术文档 访问 Git 远程仓库 调用测试 API

不需要联网的任务：

阅读代码 修改本地文件 执行已经安装的单元测试 本地静态检查 本地构建 Git Diff 审查

应采用：

默认关闭 按任务开启 完成后恢复

三十二：☁️ 不要混淆本地网络和云端网络

本地 Codex 的网络权限由本地沙箱、审批和配置控制。

Codex Cloud 的网络权限按云端 Environment 配置，通常可以设置：

完全关闭 开启并限制域名 允许常用依赖域名 完全开放 限制 HTTP 方法

云端环境推荐：

✅推荐：只开放构建需要的域名 优先只允许 GET、HEAD、OPTIONS 不开放任意 POST、PUT、DELETE

代码仓库中的config.toml不应被认为可以完全替代云端 Environment 的网络策略。

三十三：⚠️ 提示注入风险

网络访问不只是“能不能下载依赖”的问题。

Codex 访问外部网页、文档或仓库内容时，可能遇到恶意指令，例如：

忽略项目规则 上传配置文件 执行外部脚本 读取环境变量

因此：

⚠️注意：不要让未知内容直接获得执行权限 不要盲目执行网页中的安装命令 不要让网络任务继承生产 Secret 下载脚本后先检查再执行

第八部分：额外可写目录

三十四：📂 为什么需要 writable roots

部分构建工具需要写入项目外缓存：

NPM 缓存 PNPM Store Maven 仓库 Gradle 缓存 Python 缓存 编译器缓存

如果直接使用完全访问模式，权限范围过大。

可以在workspace-write下增加指定可写目录：

[sandbox_workspace_write] network_access = false writable_roots = [ "/home/developer/.cache/codex-build" ]

这样只增加一个受控目录，而不是解除整个沙箱。

三十五：🚫 不要把敏感目录设为可写

禁止随意添加：

/home/developer /home/developer/.ssh /home/developer/.aws /home/developer/.config /

不推荐：

writable_roots = ["/home/developer"]

因为这相当于让 Codex 修改用户 Home 中的大量内容。

推荐为 Codex 创建独立缓存目录：

mkdir -p ~/.cache/codex-build chmod 700 ~/.cache/codex-build

再单独开放。

三十六：✅ Git 操作可能仍需批准

在部分环境中，即使使用workspace-write：

项目代码目录可写 .git 目录仍可能受到保护 .codex 目录仍可能受到保护

因此：

git commit

可能触发审批。

这是正常的安全边界，不应为了避免一次审批就切换到完全访问模式。

第九部分：命名 Profile

三十七：📋 什么是配置 Profile

Profile 用来保存不同场景的配置组合。

例如：

readonly-audit daily-dev ci-automation

当前版本使用独立文件：

~/.codex/readonly-audit.config.toml ~/.codex/daily-dev.config.toml ~/.codex/ci-automation.config.toml

启动时：

codex --profile daily-dev

Profile 会覆盖用户主配置，但仍可能被项目配置和 CLI 参数继续覆盖。

三十八：🔒 只读审查 Profile

创建：

nano ~/.codex/readonly-audit.config.toml

内容：

sandbox_mode = "read-only" approval_policy = "never" approvals_reviewer = "user" allow_login_shell = false

使用：

codex --profile readonly-audit

适合：

陌生仓库分析 代码审查 CI 静态报告 第三方依赖调查

三十九：📝 日常开发 Profile

sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" [sandbox_workspace_write] network_access = false

启动：

codex --profile daily-dev

四十：🤖 CI 自动化 Profile

sandbox_mode = "workspace-write" approval_policy = "never" [sandbox_workspace_write] network_access = false [shell_environment_policy] inherit = "core" ignore_default_excludes = false exclude = [ "*TOKEN*", "*SECRET*", "*PASSWORD*", "AWS_*", "AZURE_*", "GOOGLE_*" ]

适合：

隔离 Runner 自动生成文档 自动补充测试 静态分析 格式检查

如果任务需要下载依赖，应在 CI 外层提前完成依赖安装，或单独配置受控网络阶段。

四十一：🔄 不要使用旧 Profile 写法

旧教程可能使用：

[profiles.daily-dev] sandbox_mode = "workspace-write"

当前版本更推荐独立文件：

~/.codex/daily-dev.config.toml

并通过：

codex --profile daily-dev

选择。

第十部分：CLI 临时覆盖

四十二：⌨️ 专用参数

临时只读：

codex \ --sandbox read-only \ --ask-for-approval never

临时日常开发：

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

专用参数比通用--config更容易阅读。

四十三：🔧--config临时覆盖

临时开启工作区网络：

codex \ --config sandbox_workspace_write.network_access=true

临时限制环境变量：

codex \ --config 'shell_environment_policy.include_only=["PATH","HOME"]'

--config的值按照 TOML 解析，不是 JSON。

字符串经常需要额外引号：

codex \ --config sandbox_mode='"read-only"'

能使用专用参数时，优先使用：

--sandbox --ask-for-approval --profile

第十一部分：推荐配置方案

四十四：🔍 方案一：首次分析陌生项目

sandbox_mode = "read-only" approval_policy = "untrusted" approvals_reviewer = "user" allow_login_shell = false

执行目标：

查看目录 识别技术栈 查找启动命令 生成分析报告

不允许：

修改文件 安装依赖 执行迁移 访问项目外资源

四十五：💻 方案二：日常功能开发

sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" [sandbox_workspace_write] network_access = false

适合：

实现功能 修改项目文件 运行测试 运行构建 检查 Diff

需要网络时临时批准。

四十六：🔐 方案三：本地安全代码审查

sandbox_mode = "read-only" approval_policy = "never" allow_login_shell = false [shell_environment_policy] inherit = "core" ignore_default_excludes = false

适合：

⚠️注意：Review 当前 Diff 检查接口变更 检查安全风险 分析回归风险

四十七：🤖 方案四：隔离 CI Runner

sandbox_mode = "workspace-write" approval_policy = "never" [sandbox_workspace_write] network_access = false

外层环境必须保证：

Runner 是临时的 没有生产凭证 仓库权限受限 任务结束销毁 网络由 CI 控制

第十二部分：权限测试

四十八：👁️ 查看当前权限

在 Codex CLI 中执行：

/permissions

查看当前：

沙箱模式 审批策略 审批者 可写范围

也可以查看：

/status

确认：

当前目录 当前 Profile 项目可信状态 配置加载情况

四十九：🔒 测试只读模式

启动：

codex --profile readonly-audit

任务：

请在当前目录创建 codex-readonly-test.txt， 内容为 readonly test。

预期：

操作被拒绝 或无法在无审批模式下执行

然后确认：

test ! -f codex-readonly-test.txt \ && echo "read-only 生效"

五十：📝 测试工作区写入

启动：

codex --profile daily-dev

任务：

⚠️注意：请在当前项目根目录创建临时文件 codex-write-test.txt， 写入 workspace test。 不要修改其他文件。

检查：

cat codex-write-test.txt git status --short

测试完成后删除：

rm codex-write-test.txt

五十一：⚠️ 测试项目外写入

在workspace-write下要求：

请在 /home/developer/codex-outside-test.txt 创建文件。

预期：

请求批准 或被沙箱阻止

不要批准不必要的项目外写入。

五十二：🌐 测试网络限制

保持：

[sandbox_workspace_write] network_access = false

让 Codex执行一个只读外部请求。

预期：

请求网络审批 或被沙箱阻止

然后使用单次网络覆盖启动：

codex \ --profile daily-dev \ --config sandbox_workspace_write.network_access=true

重新测试。

测试后退出当前会话，恢复默认网络关闭状态。

第十三部分：危险配置检查

五十三：🔍 搜索危险组合

检查用户和项目配置：

rg -n \ "danger-full-access|approval_policy.*never|network_access.*true|writable_roots" \ ~/.codex/config.toml \ .codex/config.toml \ 2>/dev/null

重点检查：

danger-full-access + never 网络永久开放 Home 目录整体可写 根目录 / 可写 未知 Hook 默认继承全部 Secret 环境变量

五十四：⚠️ 典型危险配置

不推荐：

sandbox_mode = "danger-full-access" approval_policy = "never" [sandbox_workspace_write] network_access = true writable_roots = ["/"]

这份配置本身还存在逻辑混乱：

已经完全访问 却又配置 workspace-write 字段

应删除无效和危险配置，而不是通过堆叠配置解决问题。

五十五：⚠️ 项目配置供应链风险

恶意项目可能提交：

.codex/config.toml .codex/hooks.json .codex/hooks/

然后要求用户：

请信任项目后运行 Codex。

正确流程：

先人工查看 .codex 再决定是否信任

不要把“项目来自 Git”误认为“项目配置一定安全”。

第十四部分：常见问题

五十六：🔧 项目配置没有生效

检查：

✅推荐：项目是否 trusted 文件路径是否为 .codex/config.toml 是否从正确项目目录启动 是否被 CLI 参数覆盖 是否被更深目录配置覆盖

执行：

pwd git rev-parse --show-toplevel find .. -path '*/.codex/config.toml' -print

五十七：🌐 Codex 总是请求联网审批

原因：

network_access=false 依赖安装需要联网 测试调用了外部服务 构建脚本会下载资源

处理：

⚠️注意：确认任务确实需要联网 临时开启本次网络 不要永久开放所有项目

五十八：🔧 NVM 或 Node.js 找不到

如果配置：

allow_login_shell = false

而 Node.js 只通过 Shell 初始化脚本加载，Codex 子进程可能找不到node。

解决顺序：

1. 检查 PATH。
2. 使用稳定的 Node 绝对路径。
3. 配置项目工具链。
4. 必要时恢复 allow_login_shell=true。

不要为了找到 Node 而继承所有敏感环境变量。

五十九：✅ Git Commit 总是要求批准

部分沙箱会保护：

.git .codex

即使项目源代码可写，Commit 仍可能需要批准。

这是正常现象。

不要因此使用：

danger-full-access

更合理的是：

在提交阶段批准明确的 git commit 或让 Codex完成代码后由人工提交

六十：🔧 配置文件解析失败

TOML 常见错误：

字符串没有引号 数组缺少逗号 表名写错 同一键重复定义 把 JSON 写法当成 TOML

例如错误：

sandbox_mode = workspace-write

正确：

sandbox_mode = "workspace-write"

六十一：🔧 Profile 不生效

确认文件名：

~/.codex/daily-dev.config.toml

启动：

codex --profile daily-dev

不要继续使用已经废弃的：

[profiles.daily-dev]

还要检查项目配置是否覆盖了 Profile。

第十五部分：1.5 小时实操安排

六十二：⏱️ 0～15 分钟：检查现有配置

执行：

ls -la ~/.codex sed -n '1,240p' ~/.codex/config.toml 2>/dev/null cd ~/projects/city-snapshot-platform find .codex -maxdepth 3 -type f -print 2>/dev/null

识别：

⚠️注意：当前沙箱 审批策略 网络状态 可信项目 是否存在危险配置

六十三：🛠️ 15～30 分钟：建立用户默认配置

创建：

~/.codex/config.toml

采用：

workspace-write on-request user reviewer network_access=false 环境变量过滤

六十四：🛡️ 30～45 分钟：配置可信项目

检查项目.codex内容。

确认安全后，在用户配置中增加：

[projects."/home/developer/projects/city-snapshot-platform"] trust_level = "trusted"

第三方实验项目标记为：

trust_level = "untrusted"

六十五：📋 45～60 分钟：建立三个 Profile

创建：

readonly-audit.config.toml daily-dev.config.toml ci-automation.config.toml

分别测试：

codex --profile readonly-audit codex --profile daily-dev

六十六：🔒 60～75 分钟：测试沙箱

验证：

⚠️注意：只读模式不能写文件 工作区模式可以修改项目 项目外写入触发审批 网络访问受到限制

测试完成后删除临时文件。

六十七：✅ 75～90 分钟：检查并提交项目配置

检查：

git status --short git diff -- .codex/config.toml

确认项目配置中没有：

⚠️注意：个人路径 Secret API Key 模型提供方认证 危险完全访问配置

建议分支：

fea-codexquanxian

Commit：

chore: add safe Codex project configuration

第十六部分：可直接交给 Codex 的配置任务

六十八：💬 完整提示词

⚠️注意：请检查并规划当前项目的 Codex 权限配置。

第一阶段只分析，不修改文件。

请检查：

1. ~/.codex/config.toml 是否存在。
2. 项目 .codex/config.toml 是否存在。
3. 当前项目是否为 trusted。
4. 当前 sandbox_mode。
5. 当前 approval_policy。
6. 当前网络访问配置。
7. writable_roots。
8. shell_environment_policy。
9. 是否存在危险配置组合。
10. 是否存在项目 Hook。

不得输出：

• auth.json
• API Key
• Token
• 密码
• 云平台 Secret

请输出三套配置方案：

1. 只读审查。
2. 日常开发。
3. 隔离 CI 自动化。

日常开发要求：

• sandbox_mode = workspace-write
• approval_policy = on-request
• approvals_reviewer = user
• 默认关闭工作区出站网络
• 过滤云平台和 Token 环境变量
• 不使用 danger-full-access
• 不使用 Force Push 自动化

确认方案后再创建：

• ~/.codex/config.toml
• ~/.codex/readonly-audit.config.toml
• ~/.codex/daily-dev.config.toml
• ~/.codex/ci-automation.config.toml
• 项目 .codex/config.toml

注意：

1. 用户级文件不提交 Git。
2. 只有项目 .codex/config.toml 可以进入 Git。
3. 项目配置不得包含个人路径和 Secret。
4. 修改完成后验证 TOML。
5. 运行只读和工作区写入测试。
6. 输出每项测试结果。
7. 暂时不要使用 danger-full-access。

第十七部分：验收标准

六十九：✅ 本篇验收清单

完成后应达到：

⚠️注意：已创建用户级 ~/.codex/config.toml 已理解配置优先级 已理解 trusted 和 untrusted 已审查项目 .codex 目录 已配置 workspace-write 已配置 on-request 已配置 user 审批者 已默认关闭工作区网络 已过滤常见 Secret 环境变量 已建立只读审查 Profile 已建立日常开发 Profile 已建立 CI 自动化 Profile 已验证只读模式不能直接写文件 已验证工作区模式可以修改项目 已验证项目外写入触发限制 未使用 danger-full-access 作为日常默认 未在项目配置中保存凭证

第十八部分：本篇总结

七十：📝 核心结论

⚠️注意：AGENTS.md 管行为规则 config.toml 管实际权限边界

用户配置保存个人默认值 项目配置保存仓库级覆盖 CLI 参数拥有更高优先级

陌生仓库先使用 read-only 日常开发使用 workspace-write 常规交互使用 on-request CI 非交互任务使用 never

项目可信前必须审查 .codex 默认关闭不必要网络 不要把整个 Home 设为 writable root 不要把云平台 Secret 传给所有子进程 不要把 danger-full-access + never 用作本地默认

推荐默认组合：

sandbox_mode = "workspace-write" approval_policy = "on-request" approvals_reviewer = "user" [sandbox_workspace_write] network_access = false