配置、模式与 Profiles
配置的目的不是追求“最强权限”，而是让不同类型的任务使用稳定、可解释的运行边界。先使用默认配置，只有在重复遇到明确问题时才增加自定义项。
配置从哪里来#
实际行为可能同时受到以下层次影响：
- 官方和组织级策略；
- 用户级
~/.codex/config.toml； - 项目中的
AGENTS.md； - 当前启动参数；
- 当前对话中的明确指令。
遇到“为什么没有按预期执行”，应沿这条链排查，而不是反复改提示词。
执行模式的核心维度#
模式通常围绕三件事组合：
- 文件系统：只读、只写工作区，或更宽范围；
- 审批：何时必须由人确认；
- 网络：是否允许访问外部地址。
按任务选边界#
| 任务 | 文件权限 | 网络 | 审批 |
|---|---|---|---|
| 代码解释 / 审查 | 只读 | 通常不需要 | 最少 |
| 常规开发 | 工作区写入 | 依赖安装时按需 | 外部或高风险动作确认 |
| 资料研究 | 只读 | 指定来源 | 首次访问或敏感域确认 |
| 发布 / 运维 | 最小必要范围 | 指定服务 | 每个不可逆动作确认 |
| CI 自动任务 | 隔离工作区 | 固定依赖源 | 预先定义，无交互 |
用 Profiles 切换场景#
如果当前版本支持 Profiles，可以把反复使用的配置组合命名，而不是频繁手改全局文件。示意：
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "untrusted"
[profiles.development]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
字段和值仅作结构示例，必须以你安装版本的官方参考为准。Profile 适合表达运行环境，不适合塞入项目业务规则。
高级配置的使用顺序#
每增加一项配置，都回答三个问题：
- 它解决了哪个可复现问题？
- 如何验证它真的生效？
- 如何恢复默认？
推荐顺序：
- 先用默认设置复现；
- 只改一个字段；
- 重启会话验证；
- 记录版本和结果；
- 再决定是否长期保留。
CLI 临时参数与全局配置#
一次性实验优先使用启动参数或临时 Profile；长期一致性才写入用户配置。原因很简单：全局修改会影响所有仓库，容易把一个项目的特殊需求带到另一个项目。
不应该写进配置的内容#
- API 密钥或可直接使用的生产凭证；
- 项目业务约定；
- 某次任务的临时验收标准；
- 为绕过一次失败而永久开放的高权限；
- 未理解含义、从他人配置复制来的字段。
项目约定写入 AGENTS.md，密钥使用系统或 CI 的秘密管理，临时需求放在任务提示中。
配置变更记录模板#
### 2026-07-13：开发模式允许工作区写入
- 原因：需要让 Codex 编辑仓库文件
- 影响：仅当前工作区可写
- 验证：能修改 tracked 文件，工作区外仍被阻止
- 回退：删除 sandbox_mode 自定义项
排查配置冲突#
- 记录
codex --version； - 暂存并移走自定义
config.toml； - 在全新会话重试最小任务；
- 检查仓库和父目录中的
AGENTS.md； - 逐项恢复配置；
- 对照官方设置页确认字段仍有效。
配置越少，行为越容易解释。稳定优先于花哨。