EP02. “权限模式与项目设置”

首页 › AI 工具 › ChatGPT · Codex · EP02

约 16 分钟· #EP02#ChatGPT#Codex

Codex 敢不敢直接帮你改文件、跑命令，靠的是「权限模式」这一套机制——先搞懂这个，用起来才不会提心吊胆
讲三种权限模式怎么选、系统层面怎么把关
讲 config.toml 配置文件放哪里、常用配置项有哪些
讲 AGENTS.md 怎么写、Codex 怎么找到并合并这些指令文件
顺带讲 Git Worktrees——想让 Codex 在独立副本里干活、不干扰你手上的改动时会用到
前置知识：先看过 EP01，知道 Codex 有哪些入口、怎么开始用

重点内容

权限模式怎么选

Codex 每次要做「有风险」的操作（改文件、跑命令、连网络）之前，会照你设定的权限模式决定要不要先问你：

模式	行为	适合场景
Ask for approval（请求批准）	能读写当前工作区的文件、跑常规本地命令；超出工作区范围的操作会先问你	推荐的入门模式，第一次用、不熟悉的项目
Auto-review（自动批准/自动审查）	工作区内的读写照跑，超出范围的请求会自动审核决定放不放行	已经用熟了、项目相对熟悉；⚠️ 自动审核偶尔会判断错误，要留意
Full access（完全访问）	可以改电脑上任意文件、跑任何命令，完全不用批准	风险最高，只在你很信任这次任务范围、或是在隔离环境（worktree/容器）里才考虑用

设置位置：桌面 App「设置 → 常规 → 权限」；CLI 用 /permissions 指令；也可以写进 config.toml 固定默认值。

📌 默认情况下 Codex 只能读写它工作区里的文件，需要额外权限（比如碰工作区外的文件、连网络）时会另外请求——这是刻意设计的最小权限原则。

系统层面的 Sandbox

上面的权限模式不是「Codex 自己答应不乱来」，背后有操作系统层级的限制配合：

macOS：用系统自带的 Seatbelt 机制
Linux：用 Landlock + seccomp
Windows：用受限 token，或在 config.toml 设 [windows] sandbox = "elevated"（需要管理员权限）

就算 Codex 出错或被恶意内容误导，也不能超出被允许的文件/网络范围，sandbox_mode 常见值是 read-only（只读）、workspace-write（默认，能读写工作区）、danger-full-access（完全访问）。沙箱和权限模式是两件事、分工合作：沙箱定的是技术上碰不碰得到，权限模式决定的是碰之前要不要先停下来问你。

⚠️ 新版 Permission Profiles（Beta）正在取代上面这套设置：官方推出了一套新的权限系统，用 default_permissions + [permissions] 表来管，跟旧的 sandbox_mode/approval_policy 不能混用——两套系统二选一，官方原文是「configure either the new profiles, or the old sandbox settings, but not both」。新系统内建三个现成 Profile 可以直接套：:read-only（只读）、:workspace（能写工作区）、:danger-full-access（无限制），也能自订 Profile 用 extends 继承内建款再加规则。这套还在 Beta，细节变动快，这篇笔记先只提醒有这回事、原理上跟旧系统类似（一样是分「能碰到什么」和「要不要先问」两层），真的要切换建议先查当下的官方文档，企业管理员想全面换成新系统前，官方建议先把旧的 sandbox 设置清乾净，避免两边设置打架。

config.toml 配置文件

Codex 的设置存在两个位置：

用户级：~/.codex/config.toml（所有项目都套用）
项目级：.codex/config.toml（放在项目根目录或子文件夹，只对这个项目生效）

IDE 扩展里也能直接打开：右上角齿轮图标 → Codex 设置 → Open config.toml。

配置解析优先级（由高到低）：CLI 参数/--config 覆盖 → 项目配置（离当前目录越近越优先，且只信任受信项目）→ 具名 profile（~/.codex/{profile-name}.config.toml）→ 用户配置 → 云端托管默认值 → 系统配置（/etc/codex/config.toml）→ 内建默认值。

常用配置项：

配置项	范例	说明
`model`	`model = "gpt-5.6"`	设置默认模型
`approval_policy`	`approval_policy = "on-request"`	对应上面的权限模式
`sandbox_mode`	`sandbox_mode = "workspace-write"`	文件系统/网络访问范围
`web_search`	`web_search = "cached"`	网络搜索模式（cached / indexed / live / disabled）
`model_reasoning_effort`	`model_reasoning_effort = "high"`	推理深度，越高越慢但越仔细
`personality`	`personality = "friendly"`	沟通风格（friendly / pragmatic / none）
`log_dir`	`log_dir = "/path/to/logs"`	日志文件位置

[features] 表可以开关实验性功能，例如：

[features]
memories = true       # 记忆功能
multi_agent = true    # 多 agent 协作（Subagents，见 EP04）
web_search = true     # 网络搜索

也能用 CLI 指令临时开：codex --enable feature_name。

AGENTS.md 怎么写

AGENTS.md 是给 Codex（也兼容 Cursor、GitHub Copilot 等其他 AI 编程工具）看的「项目操作说明书」。Codex 按下面顺序查找并合并：

全局作用域：~/.codex/ 目录下，优先读 AGENTS.override.md，没有才读 AGENTS.md
项目作用域：从 Git 仓库根目录一路往下找到当前工作目录，每一层都照「AGENTS.override.md → AGENTS.md」的顺序检查
合并规则：由上到下拼接成一份完整指令，离当前目录越近的文件，优先级越高（会覆盖更上层的指令）

⚠️ 每个目录最多放一份（AGENTS.md 或 AGENTS.override.md 二选一），全部拼起来有大小上限（预设 32KB，可调）。每次运行或开新会话都会重新读取，不是读一次就快取死。想确认目前实际读到了什么，可以跑 codex --ask-for-approval never "Summarize current instructions"。

常见会写进去的内容：

测试要怎么跑（例如 npm test -- --runInBand）
哪些目录/文件不能碰（例如自动生成的 dist/ 文件夹）
命名规范、架构上的限制
改完 API 要附带什么说明
完成一个任务前要先做什么检查（例如「跑 lint + 最相关的测试再收工」）

范例片段：

# ~/.codex/AGENTS.md（全局）
## Working agreements
- 测试命令、包管理工具偏好

# 项目根/AGENTS.md
## Repository expectations
- 代码审查规范、文档更新要求

# 某子目录/AGENTS.override.md（局部覆盖）
## [服务名] rules
- 这个子目录专属的规则

💡 没有 AGENTS.md 也能用 Codex，只是它得每次都靠猜；写清楚之后，之后每个任务都能少答几次「这个能不能改」。CLI 里跑 /init 可以让 Codex 自己先扫一遍项目，生成一份 AGENTS.md 草稿。

Git Worktrees：给 Codex 一块独立地盘

Worktrees 是 Git 本身的功能：同一个项目开出好几份独立副本，各自有自己的文件，但共享同一份 .git 版本记录。让 Codex 在 worktree 里干活的好处：

不会打扰你自己手上正在改的文件
可以同时排好几个 Codex 任务并行跑
事后方便比对、也可以随时切回本地检查

设置方式：新开对话时在编辑器下方选 Worktree，选一个起始分支（main / 某个 feature 分支 / 当前分支），Codex 会基于它建一个 worktree（默认是 detached HEAD 状态）。做完之后两条路：Create branch here（把 worktree 转成正式分支，提交/推送/开 PR）或 Hand off（把整个对话交还本地，Codex 处理好该有的 Git 操作）。

📌 想让某些被 Git 忽略的文件（比如 .env）也一起复制进新 worktree，写进项目根目录的 .worktreeinclude 文件。Codex 管理的 worktree 默认只保留最近 15 个，会自动清理旧的。

官方把开一段新对话时能选的运行环境统一称为三种模式：Local（直接在当前项目目录跑）、Worktree（就是上面讲的隔离副本，一样在你自己电脑上跑）、Cloud（丢到远程配置好的云环境跑）——Local 和 Worktree 都算「本地」，差别只在要不要隔离；Cloud 才是真的换到别的机器上跑。

顺手一提：集成终端

每段对话都自带一个范围限定在当前项目/worktree 的终端，不用切到另一个窗口就能跑命令、看结果：应用右上角终端图标或按 Ctrl+\ 打开，Cmd+K 开指令面板，Ctrl+L 清空画面。适合手动跑 git status、npm test`、看开发服务器的输出——Codex 也能读到终端里显示的内容，拿来检查跑起来的服务/失败的构建。常用的命令可以在本地环境里定义成「可重复使用的操作」，桌面 App 会把它们显示成快捷方式。

常见错误

❌ 一路点「同意」不看内容——批准前先看它到底要跑什么命令/改什么文件
❌ 把密码、API key 这类敏感信息直接写进任务描述里——应该放在环境变量或密钥管理工具里
❌ 项目没有 AGENTS.md，又抱怨它老是改错地方——先跑 /init 或花几分钟手写清楚规矩
❌ 陌生/敏感项目一上来就用「Full access」模式——先从「Ask for approval」开始，熟悉了它的行为模式再放宽
❌ 以为 AGENTS.md 只要放一份在根目录就好——子目录如果需要不一样的规则，要另外放 AGENTS.override.md，不是自动继承猜测
💡 云端/定时任务如果一直构建失败，先检查是不是环境差异（脚本、语言版本、密钥、环境变量跟本地不一样）

Sources

官方文档：

Codex Permission modes — https://learn.chatgpt.com/codex/permission-modes
Codex Config Basics — https://learn.chatgpt.com/codex/config-file/config-basic
AGENTS.md — https://learn.chatgpt.com/codex/agent-configuration/agents-md
Git worktrees — https://learn.chatgpt.com/codex/environments/git-worktrees
Permissions (Profiles, Beta) — https://learn.chatgpt.com/codex/permissions
Sandboxing — https://learn.chatgpt.com/codex/sandboxing
Environment modes — https://learn.chatgpt.com/codex/environments/modes
Integrated terminal — https://learn.chatgpt.com/codex/integrated-terminal