第三章. Codex 高级配置

第三章. Codex 高级配置

3.1. 配置文件结构

Codex 的配置文件位于 ~/.codex/config.toml。配置分为三层：

  1. 全局配置：~/.codex/config.toml
  2. 项目配置：项目根目录/.codex/config.toml
  3. 命令行参数：codex -m o3 --sandbox read-only

优先级：命令行参数 > 项目配置 > 全局配置。

3.2. 基础配置

3.2.1. 模型配置

1
2
3
4
5
6
# 默认模型
model = "gpt-5.1-codex-max"
# 推理强度（low / medium / high）
model_reasoning_effort = "high"
# 详细程度（low / medium / high）
model_verbosity = "medium"

推理强度 控制 Codex 思考的深度：

  • low：快速响应，适合简单任务
  • medium：平衡速度和质量
  • high：深度思考，适合复杂任务

详细程度 控制 Codex 输出的详细程度：

  • low：只输出关键信息
  • medium：包含解释和推理过程
  • high：包含完整的思考过程

3.3. Profile 系统

Profile 是定义在 config.toml 中的配置组合，用于在不同工作流之间通过 -p 或 --profile 参数快速切换。

3.3.1. 日常开发 (Daily)

最平衡的设置，适合 90% 的开发场景。

1
2
3
4
5
[profiles.daily]
model = "gpt-5.2-codex"            # 速度与质量平衡
model_reasoning_effort = "medium"  # 中等推理，不浪费 Token
approval_policy = "on-failure"     # 仅在命令失败或高风险时询问
sandbox_mode = "workspace-write"   # 允许读写当前目录

使用场景：

  • 编写新 Feature
  • 修复常规 Bug
  • 日常重构

使用方式：

1
codex -p daily "给 User 模型添加邮箱验证逻辑"

3.3.2. 深度审查 (Deep Review)

牺牲速度换取极致的逻辑分析能力，适合“找茬”和架构设计。

1
2
3
4
5
[profiles.review]
model = "gpt-5.1-codex-max"        # 旗舰模型，擅长深度推理及上下文理解
model_reasoning_effort = "high"    # 开启深度思考模式
approval_policy = "never"          # 审查通常只需读取，无需执行命令，故免审批
sandbox_mode = "read-only"         # 强制只读，防止意外修改代码

使用场景：

  • 提交前的 Code Review
  • 安全漏洞审计
  • 复杂架构的重构建议

使用方式：

1
codex -p review "审查 src/auth 目录，找出可能的死锁或竞态条件，输出 Markdown 报告"

3.3.3. 极速模式 (Fast / YOLO)

成本最低、速度最快，适合简单任务或一次性脚本。

1
2
3
4
5
[profiles.fast]
model = "gpt-5.1-codex-mini"       # 轻量级模型，响应极快且便宜
model_reasoning_effort = "low"     # 关闭复杂推理
approval_policy = "never"          # 危险！从不询问，全自动执行
sandbox_mode = "workspace-write"

使用场景：

  • 快速生成脚手架代码
  • 编写简单的 Shell/Python 脚本
  • 原型验证（POC）

使用方式：

1
codex -p fast "用 React + Tailwind 写一个倒计时组件"

3.4. 性能优化配置

通过限制上下文和减少废话，可以降低 Token 消耗并提升响应速度。

1
2
3
4
5
6
7
8
# 1. 限制项目文档读取量 (默认 65536)
project_doc_max_bytes = 16384

# 2. 隐藏推理过程 (省流模式)
model_reasoning_summary = "none"

# 3. 降低回答啰嗦程度
model_verbosity = "low"

3.5. 常用 Slash 命令

在对话框输入 / 即可唤出命令菜单。以下是 Codex CLI (v0.87.0+) 的核心命令：

3.5.1 配置与控制

命令描述真实开发场景
/model选择模型和推理强度切换 gpt-5.1-codex-max 做深度审查，或 mini 做简单脚本
/approvals设置审批权限临时开启“自动批准” (-y) 以批量执行脚本
/skills增强特定任务能力关键：开启/关闭特定的 Agent 技能（如联网搜索、文件操作）
/experimental切换 Beta 功能尝鲜测试版特性（可能不稳定）

实验功能如下表所示：

功能名称真实用途与原理解析Windows/WSL 建议
Background terminal (默认没有开启)让 AI“一心二用”。 默认情况下，如果 AI 运行 npm run dev，它会一直卡住等待命令结束。开启此功能后，AI 可以将长任务挂在后台运行，同时继续和你对话写代码。强烈建议开启 特别适合启动本地服务器或运行耗时的构建任务。
Shell snapshot (Shell 快照)极速启动命令。 原理是在会话开始时“拍照”你的环境变量和配置，以后运行命令直接复用，不再每次都重新加载 .bashrc 或 .zshrc。 能显著减少命令执行的延迟（从 500ms 降至 50ms）。按需开启 ⚠️ 注意：在纯 Windows PowerShell 下可能无效或报错；在 WSL (Ubuntu) 中效果极佳。
Powershell UTF-8 support (PS UTF-8 支持)修复乱码。 强制 PowerShell 使用 UTF-8 编码，解决中文输出显示为 ???? 或乱码的问题。必须开启 只要你用 Windows，这就是必选项。
Steer conversation (对话操控模式)改变发送习惯。 - Enter: 立即发送（插队）。 - Tab: 放入队列（排队）。 当你有一个想法但不想打断 AI 当前正在写的代码时，按 Tab 把它加入队列，AI 忙完手头的事会自动处理。推荐开启 非常适合思维跳跃的开发者。

3.5.2 项目上下文

命令描述真实开发场景
/init初始化项目指令最重要：生成 AGENTS.md，告诉 Codex 这个项目的“家规”
/compact压缩上下文感觉 Codex 变慢或 Token 消耗过高时，用它总结对话并释放内存
/mention提及特定文件强制将不在当前上下文的文件（如 utils.ts）加入对话
/diff查看变更在提交代码前，检查 Codex 到底改了哪些文件（含未追踪文件）

3.5.3 会话管理

命令描述真实开发场景
/review审查当前变更让 Codex 自己检查刚刚写的代码有没有 Bug
/new开启新会话当前任务乱套了？直接重开，不仅清空上下文还能省钱
/resume恢复历史会话昨天没修完的 Bug，今天接着修（保持上下文）
/fork分叉会话神技：想尝试一个激进的重构但怕搞坏当前进度？Fork 出去试！

3.6. 项目家规：AGENTS.md (/init)

这是 Codex 最核心的高级功能之一。

与其每次都跟 Codex 废话“请使用 TypeScript，不要用 Any，样式用 Tailwind”，不如直接把这些规则写进 AGENTS.md。

  1. 生成文件：在项目根目录运行 /init，Codex 会自动生成一个模板。
  2. 配置规则：Codex 在回答任何问题前，都会先读这个文件。

AGENTS.md 真实配置模板（建议保存）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# AGENTS.md

## 项目技术栈
- 语言: TypeScript (Strict Mode)
- 框架: React 19, Next.js 15 (App Router)
- 样式: Tailwind CSS (Mobile First)
- 组件库: shadcn/ui

## 编码规范
- **禁止**使用 `any` 类型，必须定义 Interface。
- 组件必须使用 `export default function`。
- 所有 API 请求必须包含错误处理 (try/catch)。
- 文件名使用 kebab-case (如 `user-profile.tsx`)。

## 常用命令
- 启动: `pnpm dev`
- 测试: `pnpm test`
- 数据库迁移: `pnpm prisma migrate dev`

## 提交规范
- 使用 Conventional Commits (feat, fix, docs, style, refactor...)

效果：配置后，你只需要说“写一个登录页”，Codex 就会自动用 React 19 + Tailwind + shadcn/ui + TypeScript 严格模式生成，无需重复指令。

3.7. 无限扩展：MCP 工具 (/mcp)

MCP (Model Context Protocol) 是 Codex 连接外部世界的桥梁。

默认情况下 Codex 只能操作文件。配置 MCP 后，Codex 可以直接 连数据库查表、连 GitHub 提 PR、或者 连 Linear 读票。

如何添加 MCP 工具？

你可以通过命令或配置文件添加。以添加一个 “Context7”（用于抓取文档的工具）为例：

方式一：命令行（推荐，临时生效）

1
codex mcp add context7 -- npx -y @upstash/context7-mcp

方式二：配置文件（永久生效）
修改 ~/.codex/config.toml：

我们会在后续配置我个人常用的 mcp

1
2
3
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

使用 /mcp 命令可以查看当前已连接的所有工具状态。