<!-- title: Codex别只会回车：七个被忽略的隐藏开关 -->
<!-- domain: tips-tricks -->

# Codex 别只会回车：七个被忽略的隐藏开关

OpenAI 的 Codex CLI 在国内被当成"能改代码的 ChatGPT"。绝大多数人装完就开始一问一答，顶多敲个 `codex --full-auto` 就觉得自己已经"用起来了"。但翻一遍官方 reference 你会发现：它有 20 多个子命令、几十个 flag，还有一整套藏在 `~/.codex/config.toml` 里的配置层。真正决定你效率、成本和安全的，从来不是对话框里那几句话，而是那些默认不会弹出来的开关。这篇拆 7 个国内中文文档几乎没人讲的隐藏机制——AGENTS.md 三层覆盖、Profile 切换"人格"、execpolicy 命令白名单、exec 结构化输出、fork 无损分叉、feature flags 实验开关、sandbox 精准放权——每个都给具体命令、预期效果和适用场景，看完就能抄。

先看一张图，理解你每敲一次 `codex`，背后有多少层配置在被叠加和校验。大多数人只用到最顶上那一层。

```mermaid
flowchart TD
    A["运行 codex -p yolo '修个 bug'"] --> B["AGENTS.md 指令链<br/>global → 项目根 → 当前目录 (≤32KiB)"]
    A --> C["config.toml 基础配置<br/>+ yolo.config.toml 叠加"]
    A --> D["命令行 -c key=value<br/>(最高优先级覆盖)"]
    B --> E["合并成一条 system prompt"]
    C --> F["解析 feature flags<br/>+ sandbox 等级 + model"]
    D --> F
    E --> G["Agent 开始执行"]
    F --> G
    G --> H{"execpolicy 白名单拦截"}
    H -->|allowed| I["workspace-write 沙箱内运行"]
    H -->|blocked / prompted| J["拒绝或弹审批"]
```

---

## 技巧一：AGENTS.md 不是"放一个文件"，而是三层覆盖链

国内教程基本只教你"在项目根放一个 AGENTS.md"。但这只是冰山一角。官方文档明确写了 Codex 的指令发现（discovery）是**分层、带优先级**的：

- **全局层**：在 `~/.codex/`（或你设的 `CODEX_HOME`）下，Codex 先找 `AGENTS.override.md`，没有再读 `AGENTS.md`，只用第一个非空文件。
- **项目层**：从 Git 根目录一路向下走到你当前工作目录，每一级都检查 `AGENTS.override.md` → `AGENTS.md`，每级最多取一个文件，最后**从根到当前目录拼接**，越靠近当前目录的越晚出现、优先级越高。
- **硬上限**：合并后超过 `project_doc_max_bytes`（默认 **32 KiB**）就停止追加。

**怎么用**：
1. 全局写"工作约定"：`mkdir -p ~/.codex && cat > ~/.codex/AGENTS.md`，写进"改 JS 后必跑 npm test""加生产依赖前先问我"。
2. 需要临时覆盖、又不想删全局文件？放一个 `~/.codex/AGENTS.override.md`，用完删掉即恢复。
3. 大型 monorepo 里，子包目录各放一个 AGENTS.md，让 Codex 在不同子项目自动切换规范。

**适用场景**：你有多个仓库、或同一个仓库不同目录规范不同。一条全局约定省掉每个项目重复粘贴，override 文件适合"今天先放开某个限制、明天再收回来"。

**预期效果**：每次新开会话，Codex 自动继承你的约定，不用每次粘贴"请用 pnpm、请跑测试"。验证方法：`codex --ask-for-approval never "Summarize the current instructions."`，它会把 `~/.codex/AGENTS.md` 里的条目背给你听。

---

## 技巧二：一个 `-p` 切换"全自动"和"严只读"两套人格

每次都敲 `codex --sandbox workspace-write --ask-for-approval never` 又长又容易敲错。Profile 就是给这套组合起个名字。`-p <name>`（或 `--profile`）会把 `$CODEX_HOME/<name>.config.toml` **叠加**在基础配置之上。

**怎么用**：建两个 profile 文件。

`~/.codex/yolo.config.toml`（放手干、沙箱内写）：
```toml
sandbox_mode = "workspace-write"
approval_policy = "never"
model = "gpt-5.4"
```

`~/.codex/audit.config.toml`（只读审查、不碰文件）：
```toml
sandbox_mode = "read-only"
approval_policy = "on-request"
```

之后：`codex -p yolo "重构这个函数"`、`codex -p audit "review 这个 PR 的安全风险"`。

**适用场景**：同一台机器上既要快速迭代、又要严格 code review；或团队共享一套 profile 文件统一行为。

**预期效果**：两秒钟切人格，不用记一长串 flag，也避免"忘了加 --sandbox 结果它乱写一通"。

---

## 技巧三：execpolicy 白名单——让 full-auto 真正安全

很多人怕 `--full-auto`，是因为它等于把 shell 权限整个交出去。但 Codex 有个被严重低估的 `execpolicy`：你可以用 `.rules` 文件预先定义**哪些命令放行、哪些要审批、哪些直接拦截**，而且能**离线验证**不消耗一次模型调用。

**怎么用**：
1. 写规则文件（放 `~/.codex/rules/` 下），声明白名单/黑名单。
2. 离线测试某条命令会怎么判：
```bash
codex execpolicy check --rules ~/.codex/rules/my.rules -- rm -rf node_modules
```
3. 配合 exec 跑自动化时加 `--ignore-rules=false` 让规则生效，规则外命令一律拦。

**适用场景**：CI 里让 Codex 自动跑、又怕它执行危险命令；或者限制它只能跑 `pnpm test / lint / build` 这几条。

**预期效果**：把"全自动"从赌命变成"在白名单里全自动"。`codex execpolicy check` 还会输出匹配到的最严格规则和 JSON 决策，方便你写测试断言。

---

## 技巧四：`codex exec` + `--output-schema`——把 Codex 当可编程管道

90% 的人只用交互式 TUI，没碰过 `codex exec`（别名 `codex e`）。它非交互、能流式输出、能强制结构化，是把 Codex 嵌进脚本和 CI 的钥匙。

**怎么用**：
```bash
# 跑完把最终自然语言结论落到文件，CI 友好
codex exec --sandbox read-only --output-last-message report.md "分析这个仓库的依赖风险"

# 强制 JSON Schema 结构化输出，Codex 会校验工具产出
codex exec --output-schema risk.schema.json "列出所有不安全的依赖"

# 流式 JSONL 事件，方便下游解析每一步
codex exec --json "生成 API 文档"
```

几个被忽略的开关：
- `--ephemeral`：跑完不落会话文件，一次性任务用它省磁盘。
- `--skip-git-repo-check`：在非 Git 目录也能跑，适合临时文件夹。
- `--oss`：用本地 Ollama 的开源模型 provider，**不联网、不花 API 钱**，敏感代码审计首选。

**适用场景**：批量给多个仓库跑安全扫描、把 Codex 当一个"会写代码的 jq"、CI 里自动生成变更说明。

**预期效果**：从"陪聊"升级成"无人值守的命令行 worker"，输出可直接被脚本消费。

---

## 技巧五：`fork --last` 无损分叉，比 `/compact` 安全

对话越聊越长，很多人用 `/compact` 压缩上下文，但压缩有信息损失。Codex 给了另一条路：`codex fork`——把一条会话**复制成新线程**探索另一个方向，原会话原封不动。

**怎么用**：
```bash
codex fork --last          # 直接 fork 最近一条会话
codex resume --last        # 接着最近一条往下聊（原会话续命）
codex exec resume --last --all  # 跨目录找最近会话继续非交互任务
```

**适用场景**：你聊到一个方案，想"再试一种完全不同的实现"，又怕把当前上下文搞乱；或者想保留一条"已知能跑通"的会话当安全网。

**预期效果**：一次 `fork` 开一条分支，输了不亏、成了即赚，再也不用在一条会话里反复 `/clear`。

---

## 技巧六：feature flags——藏在 config.toml 里的实验开关

Codex 有一层"隐藏配置层"叫 feature flags，官方 reference 自己也把它列成稳定命令 `codex features`。很多新功能（比如 `undo` 撤销、TUI 微调）默认不亮，要你手动开。

**怎么用**：
```bash
codex features list                      # 看所有 flag、成熟度和当前状态
codex features enable undo               # 永久写入 config.toml，以后都生效
codex --enable undo "..."               # 只对这次调用临时开
codex -c features.undo=true "..."       # 等价的 -c 写法
```

**适用场景**：想抢先体验实验功能，或在 profile 里给某套人格单独打开某个 flag（feature flags 还能按 profile 作用域配置）。

**预期效果**：别人还在等"官方默认放出"，你已经手动点亮 `undo` 这类实用开关。`features list` 会标出 Experimental / Beta / Stable，按需取舍。

---

## 技巧七：sandbox 三档 + `--add-dir` 精准放权，别动不动 danger-full-access

最后一道命门是沙箱。Codex 给了三档：`read-only`、`workspace-write`、`danger-full-access`。国内常见错误有二：要么全程 `read-only` 导致啥都干不了，要么一急就上 `--dangerously-bypass-approvals-and-sandbox`（即 `--yolo`）。中间其实有个被忽略的 `--add-dir`。

**怎么用**：
```bash
# 主工作区写、外加给另一个目录写权限，比全开 danger 安全得多
codex --sandbox workspace-write --add-dir ../shared-lib "把共用库也一起改了"

# macOS 上 sandbox 拒了某命令又不知道为啥？开日志抓
codex sandbox --log-denials --permissions-profile strict -- ls /secrets

# 配置里也能直接写持久权限，用 named permissions profile
codex --profile strict "..."
```

审批策略 `-a`（`--ask-for-approval`）现在是 `untrusted | on-request | never`，旧的 `on-failure` 已废弃——如果你照老教程写 `--ask-for-approval on-failure` 会报错，换成 `on-request`（交互）或 `never`（非交互）。

**适用场景**：跨仓库重构、需要写 `~/.config` 之类工作区外的路径、调试"为什么这条命令被沙箱拒了"。

**预期效果**：用最小权限原则跑全自动，权限边界清晰、被拒有日志可查，而不是一刀切 `--yolo` 把整台机器暴露给模型。

---

## 信息差总结：你以为的 Codex vs 真正能省事/保命的 Codex

| 维度 | 大多数人的用法 | 你应该知道的隐藏开关 |
|---|---|---|
| 项目指令 | 只放一个 AGENTS.md | 三层覆盖：global + override + 项目级，`AGENTS.override.md` 临时覆盖 |
| 配置 | 每次手敲一长串 flag | `-p <profile>` 一个命令切换"全自动/严只读"人格 |
| 全自动安全 | 要么不敢用，要么 `--yolo` | `execpolicy` 白名单 + `execpolicy check` 离线验证 |
| 非交互 | 不知道有 `codex exec` | `exec --output-schema/--output-last-message` 当管道用 |
| 长会话 | 用 `/compact` 丢信息 | `fork --last` 无损分叉探索另一条路 |
| 新功能 | 等官方默认放出 | `codex features enable` 手动点亮实验开关 |
| 沙箱 | read-only 或 danger 二选一 | `workspace-write` + `--add-dir` + `--log-denials` 精准放权 |
| 成本/隐私 | 全走云 API | `--oss` 接本地 Ollama 离线跑 |

---

## 行动指南（按优先级，今晚就能做）

1. **先把全局 AGENTS.md 立起来**：`mkdir -p ~/.codex`，写进你的代码风格、测试命令、依赖规则。这是 ROI 最高的一步，所有项目立刻受益。
2. **建两个 profile**：`yolo.config.toml`（workspace-write + never）和 `audit.config.toml`（read-only + on-request），从此告别长 flag。
3. **给自动化上护栏**：写一份 execpolicy `.rules` 白名单，CI 里用 `codex exec --sandbox workspace-write` 跑非交互任务，规则外一律拦。
4. **试一次 fork**：下次纠结"要不要换方案"时，`codex fork --last` 开一条分支试，别在主会话里冒险。
5. **跑一次 `codex doctor`**：它会输出一份覆盖安装、配置、认证、Git、线程的健康报告，`--summary` 看汇总、`--json` 喂脚本。很多人装完从来不体检，配置错了都不自知。

> **一句话总结**：Codex CLI 的差距不在"会不会对话"，而在"会不会用 config.toml + flag 给它套上正确的护栏和人格"。这些开关官方文档都写了，只是默认不弹出来——谁先配上，谁就先拿到效率和安全的信息差。

---

**参考来源**
- Codex CLI 官方命令行参考（所有 flag、子命令、sandbox/approval 语义）：https://developers.openai.com/codex/cli/reference
- AGENTS.md 自定义指令与三层发现机制：https://developers.openai.com/codex/guides/agents-md
- Codex CLI Feature Flags 与 TUI 调优：隐藏的配置层：https://codex.danielvaughan.com/2026/03/28/codex-cli-feature-flags-tui-tuning/
- Codex CLI Cheat Sheet（命令、快捷键、sandbox、AGENTS.md）：https://computingforgeeks.com/codex-cli-cheat-sheet/
- Codex Approval 与 Sandbox 模式配置详解：https://ofox.ai/blog/codex-cli-config-toml-deep-dive/

---
> 本文由「51学通信」技术团队出品。51学通信由通信行业18年老兵**爱卫生**（微信ID: gprshome201101）维护。
> 聚焦5G/6G核心网、3GPP标准、AI工具实战。知识星球「51学通信」提供深度技术答疑和行业洞察。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)