一 教程定位上一篇教程通过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 配置从高到低为CLI 参数和 --config 临时覆盖项目 .codex/config.toml--profile 指定的 Profile用户 ~/.codex/config.toml系统配置Codex 内置默认值例如用户配置sandbox_mode read-only项目配置sandbox_mode workspace-write如果项目已被标记为可信进入该项目后项目配置将覆盖用户配置。如果启动时执行codex --sandbox read-onlyCLI 参数又会覆盖项目配置。因此排查权限问题时不能只检查一个文件。应同时检查启动命令 项目 .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 网络出口 可访问仓库十一 三种沙箱对比模式读取项目修改项目项目外写入网络推荐场景read-only是否否受限分析、审查workspace-write是是默认否受限日常开发danger-full-access是是是是外部隔离环境日常工程建议⚠️注意80% 任务 workspace-write首次接触仓库 read-only外部隔离自动化 根据风险评估使用 workspace-write 或完全访问第三部分审批策略十二✅ 什么是审批策略沙箱决定操作边界审批策略决定 Codex 在需要越过边界或执行敏感命令时如何处理。常用策略untrusted on-request never十三untrusted配置approval_policy untrustedCodex只会自动执行被视为可信的安全读取操作。可能修改状态、运行外部程序或具有风险的命令需要用户批准。适合✅推荐陌生仓库 教学环境 敏感项目 新成员初次使用 安全优先的代码审查推荐组合sandbox_mode read-only approval_policy untrusted这种组合会频繁询问但安全边界清晰。十四on-request配置approval_policy on-requestCodex 在沙箱内正常工作只有需要超出边界时才发起审批。适合日常功能开发 测试驱动修复 局部重构 Docker 构建 项目内文档更新推荐组合sandbox_mode workspace-write approval_policy on-request approvals_reviewer user这是本系列推荐的默认开发组合。十五never配置approval_policy neverCodex 不会暂停等待审批。注意这不等于自动获得所有权限。如果当前使用sandbox_mode read-only approval_policy never那么禁止的写入操作会直接失败。如果使用sandbox_mode workspace-write approval_policy neverCodex 可以在工作区内自动修改和运行命令但无法通过请求批准来突破沙箱。适合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 falseignore_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查看 Hooksed -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_accesstrue不建议为了偶尔安装一次依赖永久把所有项目都设置为网络开放。三十一 什么时候需要网络常见联网任务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三十七 什么是配置 ProfileProfile 用来保存不同场景的配置组合。例如readonly-audit daily-dev ci-automation当前版本使用独立文件~/.codex/readonly-audit.config.toml ~/.codex/daily-dev.config.toml ~/.codex/ci-automation.config.toml启动时codex --profile daily-devProfile 会覆盖用户主配置但仍可能被项目配置和 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 静态报告 第三方依赖调查三十九 日常开发 Profilesandbox_mode workspace-write approval_policy on-request approvals_reviewer user [sandbox_workspace_write] network_access false启动codex --profile daily-dev四十 CI 自动化 Profilesandbox_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_accesstrue临时限制环境变量codex \ --config shell_environment_policy.include_only[PATH,HOME]--config的值按照 TOML 解析不是 JSON。字符串经常需要额外引号codex \ --config sandbox_moderead-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 Runnersandbox_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_accesstrue重新测试。测试后退出当前会话恢复默认网络关闭状态。第十三部分危险配置检查五十三 搜索危险组合检查用户和项目配置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_accessfalse 依赖安装需要联网 测试调用了外部服务 构建脚本会下载资源处理⚠️注意确认任务确实需要联网 临时开启本次网络 不要永久开放所有项目五十八 NVM 或 Node.js 找不到如果配置allow_login_shell false而 Node.js 只通过 Shell 初始化脚本加载Codex 子进程可能找不到node。解决顺序检查 PATH。使用稳定的 Node 绝对路径。配置项目工具链。必要时恢复 allow_login_shelltrue。不要为了找到 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 小时实操安排六十二⏱️ 015 分钟检查现有配置执行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识别⚠️注意当前沙箱 审批策略 网络状态 可信项目 是否存在危险配置六十三️ 1530 分钟建立用户默认配置创建~/.codex/config.toml采用workspace-write on-request user reviewer network_accessfalse 环境变量过滤六十四️ 3045 分钟配置可信项目检查项目.codex内容。确认安全后在用户配置中增加[projects./home/developer/projects/city-snapshot-platform] trust_level trusted第三方实验项目标记为trust_level untrusted六十五 4560 分钟建立三个 Profile创建readonly-audit.config.toml daily-dev.config.toml ci-automation.config.toml分别测试codex --profile readonly-audit codex --profile daily-dev六十六 6075 分钟测试沙箱验证⚠️注意只读模式不能写文件 工作区模式可以修改项目 项目外写入触发审批 网络访问受到限制测试完成后删除临时文件。六十七✅ 7590 分钟检查并提交项目配置检查git status --short git diff -- .codex/config.toml确认项目配置中没有⚠️注意个人路径 Secret API Key 模型提供方认证 危险完全访问配置建议分支fea-codexquanxianCommitchore: add safe Codex project configuration第十六部分可直接交给 Codex 的配置任务六十八 完整提示词⚠️注意请检查并规划当前项目的 Codex 权限配置。第一阶段只分析不修改文件。请检查~/.codex/config.toml 是否存在。项目 .codex/config.toml 是否存在。当前项目是否为 trusted。当前 sandbox_mode。当前 approval_policy。当前网络访问配置。writable_roots。shell_environment_policy。是否存在危险配置组合。是否存在项目 Hook。不得输出auth.jsonAPI KeyToken密码云平台 Secret请输出三套配置方案只读审查。日常开发。隔离 CI 自动化。日常开发要求sandbox_mode workspace-writeapproval_policy on-requestapprovals_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注意用户级文件不提交 Git。只有项目 .codex/config.toml 可以进入 Git。项目配置不得包含个人路径和 Secret。修改完成后验证 TOML。运行只读和工作区写入测试。输出每项测试结果。暂时不要使用 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
一 教程定位上一篇教程通过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 配置从高到低为CLI 参数和 --config 临时覆盖项目 .codex/config.toml--profile 指定的 Profile用户 ~/.codex/config.toml系统配置Codex 内置默认值例如用户配置sandbox_mode read-only项目配置sandbox_mode workspace-write如果项目已被标记为可信进入该项目后项目配置将覆盖用户配置。如果启动时执行codex --sandbox read-onlyCLI 参数又会覆盖项目配置。因此排查权限问题时不能只检查一个文件。应同时检查启动命令 项目 .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 网络出口 可访问仓库十一 三种沙箱对比模式读取项目修改项目项目外写入网络推荐场景read-only是否否受限分析、审查workspace-write是是默认否受限日常开发danger-full-access是是是是外部隔离环境日常工程建议⚠️注意80% 任务 workspace-write首次接触仓库 read-only外部隔离自动化 根据风险评估使用 workspace-write 或完全访问第三部分审批策略十二✅ 什么是审批策略沙箱决定操作边界审批策略决定 Codex 在需要越过边界或执行敏感命令时如何处理。常用策略untrusted on-request never十三untrusted配置approval_policy untrustedCodex只会自动执行被视为可信的安全读取操作。可能修改状态、运行外部程序或具有风险的命令需要用户批准。适合✅推荐陌生仓库 教学环境 敏感项目 新成员初次使用 安全优先的代码审查推荐组合sandbox_mode read-only approval_policy untrusted这种组合会频繁询问但安全边界清晰。十四on-request配置approval_policy on-requestCodex 在沙箱内正常工作只有需要超出边界时才发起审批。适合日常功能开发 测试驱动修复 局部重构 Docker 构建 项目内文档更新推荐组合sandbox_mode workspace-write approval_policy on-request approvals_reviewer user这是本系列推荐的默认开发组合。十五never配置approval_policy neverCodex 不会暂停等待审批。注意这不等于自动获得所有权限。如果当前使用sandbox_mode read-only approval_policy never那么禁止的写入操作会直接失败。如果使用sandbox_mode workspace-write approval_policy neverCodex 可以在工作区内自动修改和运行命令但无法通过请求批准来突破沙箱。适合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 falseignore_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查看 Hooksed -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_accesstrue不建议为了偶尔安装一次依赖永久把所有项目都设置为网络开放。三十一 什么时候需要网络常见联网任务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三十七 什么是配置 ProfileProfile 用来保存不同场景的配置组合。例如readonly-audit daily-dev ci-automation当前版本使用独立文件~/.codex/readonly-audit.config.toml ~/.codex/daily-dev.config.toml ~/.codex/ci-automation.config.toml启动时codex --profile daily-devProfile 会覆盖用户主配置但仍可能被项目配置和 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 静态报告 第三方依赖调查三十九 日常开发 Profilesandbox_mode workspace-write approval_policy on-request approvals_reviewer user [sandbox_workspace_write] network_access false启动codex --profile daily-dev四十 CI 自动化 Profilesandbox_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_accesstrue临时限制环境变量codex \ --config shell_environment_policy.include_only[PATH,HOME]--config的值按照 TOML 解析不是 JSON。字符串经常需要额外引号codex \ --config sandbox_moderead-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 Runnersandbox_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_accesstrue重新测试。测试后退出当前会话恢复默认网络关闭状态。第十三部分危险配置检查五十三 搜索危险组合检查用户和项目配置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_accessfalse 依赖安装需要联网 测试调用了外部服务 构建脚本会下载资源处理⚠️注意确认任务确实需要联网 临时开启本次网络 不要永久开放所有项目五十八 NVM 或 Node.js 找不到如果配置allow_login_shell false而 Node.js 只通过 Shell 初始化脚本加载Codex 子进程可能找不到node。解决顺序检查 PATH。使用稳定的 Node 绝对路径。配置项目工具链。必要时恢复 allow_login_shelltrue。不要为了找到 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 小时实操安排六十二⏱️ 015 分钟检查现有配置执行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识别⚠️注意当前沙箱 审批策略 网络状态 可信项目 是否存在危险配置六十三️ 1530 分钟建立用户默认配置创建~/.codex/config.toml采用workspace-write on-request user reviewer network_accessfalse 环境变量过滤六十四️ 3045 分钟配置可信项目检查项目.codex内容。确认安全后在用户配置中增加[projects./home/developer/projects/city-snapshot-platform] trust_level trusted第三方实验项目标记为trust_level untrusted六十五 4560 分钟建立三个 Profile创建readonly-audit.config.toml daily-dev.config.toml ci-automation.config.toml分别测试codex --profile readonly-audit codex --profile daily-dev六十六 6075 分钟测试沙箱验证⚠️注意只读模式不能写文件 工作区模式可以修改项目 项目外写入触发审批 网络访问受到限制测试完成后删除临时文件。六十七✅ 7590 分钟检查并提交项目配置检查git status --short git diff -- .codex/config.toml确认项目配置中没有⚠️注意个人路径 Secret API Key 模型提供方认证 危险完全访问配置建议分支fea-codexquanxianCommitchore: add safe Codex project configuration第十六部分可直接交给 Codex 的配置任务六十八 完整提示词⚠️注意请检查并规划当前项目的 Codex 权限配置。第一阶段只分析不修改文件。请检查~/.codex/config.toml 是否存在。项目 .codex/config.toml 是否存在。当前项目是否为 trusted。当前 sandbox_mode。当前 approval_policy。当前网络访问配置。writable_roots。shell_environment_policy。是否存在危险配置组合。是否存在项目 Hook。不得输出auth.jsonAPI KeyToken密码云平台 Secret请输出三套配置方案只读审查。日常开发。隔离 CI 自动化。日常开发要求sandbox_mode workspace-writeapproval_policy on-requestapprovals_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注意用户级文件不提交 Git。只有项目 .codex/config.toml 可以进入 Git。项目配置不得包含个人路径和 Secret。修改完成后验证 TOML。运行只读和工作区写入测试。输出每项测试结果。暂时不要使用 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
