Codex CLI 实战指南：20+ 高效技巧（模型切换、会话恢复、MCP 集成）

┌─────────────────────────────────────────┐
│           Codex CLI (TUI)               │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  Composer    │  │  Approval Engine │  │
│  │  (输入交互)  │  │  (权限控制)       │  │
│  └─────────────┘  └──────────────────┘  │
│  ┌─────────────────────────────────────┐ │
│  │         Sandbox (OS 级沙箱)         │ │
│  │  - 文件系统隔离                      │ │
│  │  - 网络访问控制                      │ │
│  │  - 进程执行限制                      │ │
│  └─────────────────────────────────────┘ │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  MCP Client │  │  Web Search      │  │
│  │  (工具扩展)  │  │  (网络搜索)       │  │
│  └─────────────┘  └──────────────────┘  │
└─────────────────────────────────────────┘
              │
              ▼
     OpenAI API (gpt-5.3-codex)

# macOS / Linux
npm install -g @openai/codex

# 或者用 Homebrew（macOS）
brew install openai-codex

# 验证安装
codex --version

codex login
# 会打开浏览器进行 OAuth 认证

# 修改配置文件 ~/.codex/config.toml
preferred_auth_method = "apikey"

# 或者临时切换
codex --config preferred_auth_method="apikey"

# 切回 ChatGPT 认证
codex --config preferred_auth_method="chatgpt"

# 添加到 ~/.zshrc 或 ~/.bashrc
alias cx='codex -m gpt-5.3-codex -c model_reasoning_effort="high" --search'

# 日常开发：高推理 + 网络搜索 + 自动模式
alias cx='codex -m gpt-5.3-codex -c model_reasoning_effort="high" --search'

# 代码审查：只读模式，防止误改
alias cxr='codex -m gpt-5.3-codex --sandbox read-only --ask-for-approval never'

# 快速问答：轻量模型，省成本
alias cxq='codex -m o4-mini -c model_reasoning_effort="medium"'

# 全自动模式：适合信任度高的项目（慎用）
alias cxa='codex -m gpt-5.3-codex --full-auto --search'

# CI/CD 脚本模式：非交互式
alias cxci='codex exec'

# ~/.codex/config.toml

# 默认配置
model = "gpt-5.3-codex"
model_reasoning_effort = "high"
web_search = "live"

# 代码审查 profile
[profiles.review]
sandbox_mode = "read-only"
approval_policy = "never"

# 轻量模式 profile
[profiles.quick]
model = "o4-mini"
model_reasoning_effort = "medium"
web_search = "disabled"

codex --profile review   # 代码审查模式
codex --profile quick    # 轻量快速模式
codex                    # 使用默认配置

# 方式一：交互式选择器（推荐）
codex resume
# 显示最近会话列表，高亮选择后按 Enter 恢复

# 方式二：恢复最近一次会话
codex resume --last

# 方式三：恢复特定会话
codex resume <SESSION_ID>
# SESSION_ID 可以从选择器、/status 命令或 ~/.codex/sessions/ 目录获取

# 方式四：跨目录恢复
codex resume --all
# 默认只显示当前目录的会话，加 --all 显示所有目录的会话

你：帮我重构 auth 模块，先分析当前代码结构
Codex：[分析了一堆文件]
你：好的，我先下班了，明天继续
# 第二天
$ codex resume --last
你：继续昨天的重构，从第二步开始

# 任务 A：重构认证
codex    # 开始任务 A
# ... 工作中 ...
# Ctrl+C 退出

# 任务 B：修复 Bug
codex    # 开始任务 B
# ... 修完了 ...

# 回到任务 A
codex resume   # 选择任务 A 的会话继续

# 模式一：自动编辑，但运行不可信命令时需批准
codex --sandbox workspace-write --ask-for-approval untrusted

# 模式二：只读，从不请求批准（纯聊天/分析场景）
codex --sandbox read-only --ask-for-approval never

# 模式三：完全自动（仅在隔离环境中使用！）
codex --dangerously-bypass-approvals-and-sandbox
# 别名：--yolo（OpenAI 官方真的用了这个名字）

# untrusted：只有不可信命令才需要审批（默认）
codex -a untrusted

# on-failure：命令失败时才请求审批
codex -a on-failure

# on-request：只在 Codex 主动请求时审批
codex -a on-request

# never：从不请求审批
codex -a never

# 方式一：启动时指定
codex -m gpt-5.3-codex
codex --model gpt-5

# 方式二：运行中切换
/model    # 交互式选择模型和推理等级

# 配置文件设置
model_reasoning_effort = "high"    # 高：复杂任务，消耗更多 token
model_reasoning_effort = "medium"  # 中：日常开发（默认）
model_reasoning_effort = "low"     # 低：简单任务，省 token

# 标准格式
codex -c model_reasoning_summary_format="none"

# 实验性格式（更详细的推理过程）
codex -c model_reasoning_summary_format="experimental"

1. ~/.codex/AGENTS.override.md   ← 全局覆盖（最高优先级）
2. ~/.codex/AGENTS.md            ← 全局默认
3. <项目根>/AGENTS.override.md   ← 项目覆盖
4. <项目根>/AGENTS.md            ← 项目默认
5. <子目录>/AGENTS.override.md   ← 子目录覆盖
6. <子目录>/AGENTS.md            ← 子目录默认
   ... 一直到当前工作目录

# ~/.codex/config.toml

# 自定义备用文件名（按顺序尝试）
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# 合并后的最大字节数限制
project_doc_max_bytes = 65536    # 默认 32KB

# 项目指导

## 代码规范
- 使用 TypeScript strict 模式
- 所有函数必须有 JSDoc 注释
- 测试覆盖率不低于 80%
- 使用 pnpm 作为包管理器，禁止使用 npm 或 yarn

## 架构约束
- 遵循 Clean Architecture 分层
- 数据库操作只能在 repository 层
- API 路由使用 RESTful 命名规范

## 测试规范
- 单元测试使用 Vitest
- E2E 测试使用 Playwright
- 运行命令：pnpm test

## 部署
- 主分支：main
- 部署命令：pnpm deploy
- 环境变量在 .env.example 中有模板

## 禁止事项
- 不要修改 .github/workflows/ 下的文件
- 不要直接操作数据库，使用 ORM
- 不要在代码中硬编码密钥

# 全局偏好
- 使用中文进行交流
- 代码注释使用中文
- 先分析后执行，不要直接动手
- 每次修改前说明原因

# tests/ 目录的特殊规则
- 测试文件命名：*.test.ts
- 使用 describe/it 结构
- Mock 数据放在 __fixtures__ 目录

codex --sandbox read-only --ask-for-approval never "总结一下当前加载的指令"

CLI 参数 & --config 覆盖      ← 最高优先级
       │
Profile 配置 (--profile)
       │
项目配置 (.codex/config.toml)
       │
用户配置 (~/.codex/config.toml)
       │
系统配置 (/etc/codex/config.toml)
       │
内置默认值                     ← 最低优先级

# ~/.codex/config.toml

# 默认模型
model = "gpt-5.3-codex"

# 审批策略
approval_policy = "on-request"

# 沙箱模式
sandbox_mode = "workspace-write"

# 网络搜索
web_search = "live"    # "cached" | "live" | "disabled"

# 推理等级
model_reasoning_effort = "high"

# 沟通风格
personality = "pragmatic"    # "friendly" | "pragmatic" | "none"

# Shell 环境变量策略
[shell_environment_policy]
include_only = ["PATH", "HOME", "LANG"]

# 日志目录
log_dir = "/path/to/codex-logs"

# 特性标志
[features]
shell_snapshot = true
undo = true
web_search = true

# 项目信任级别
[projects."/Users/me/work/my-project"]
trust_level = "trusted"

[projects."/Users/me/work/another-project"]
trust_level = "trusted"

# .codex/config.toml（项目级）
model = "gpt-5.3-codex"
model_reasoning_effort = "high"

# 项目特定的 MCP 服务器
[mcp_servers.my-db]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { "DATABASE_URL" = "postgresql://..." }

Config Layer 1: /etc/codex/config.toml (not found)
Config Layer 2: ~/.codex/config.toml (loaded)
Config Layer 3: /project/.codex/config.toml (loaded)
Config Layer 4: Profile "review" (active)
Config Layer 5: CLI overrides: model_reasoning_effort=high

# 缓存搜索（默认）：使用 OpenAI 维护的索引缓存
web_search = "cached"

# 实时搜索：获取最新网页数据
web_search = "live"

# 关闭搜索
web_search = "disabled"

# 命令行方式
codex --search    # 启用实时搜索

# 配置文件方式（永久生效）
# ~/.codex/config.toml
web_search = "live"

# 在对话中引用文件
@src/auth/login.ts 这个文件的登录逻辑有 Bug，帮我修一下

# 引用整个目录
@src/components/ 帮我给这个目录下所有组件添加单元测试

# CLI 方式
codex -i screenshot.png "这个页面的布局有问题，帮我修"
codex --image wireframe.png,design.png "按照这个设计稿实现页面"

# 交互式：直接粘贴图片
# 在 Codex 输入框中 Cmd+V 粘贴截图

/mention src/auth/     # 把整个 auth 目录加入上下文
/mention package.json  # 引用特定文件

# 基础用法
codex exec "修复所有 ESLint 报错"

# JSON 输出（适合脚本解析）
codex exec --json "分析这个仓库的安全漏洞"

# 结合管道使用
codex exec "列出所有 TODO 注释" | grep "FIXME"

# .github/workflows/codex-review.yml
name: Codex Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Codex CLI
        run: npm install -g @openai/codex
      - name: Run Code Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec --json \
            --config preferred_auth_method="apikey" \
            "审查这个 PR 的代码变更，关注安全性和性能问题"

# .git/hooks/pre-commit
#!/bin/bash
codex exec "检查暂存区的代码是否有明显的安全问题或 Bug"
if [ $? -ne 0 ]; then
    echo "Codex 发现了潜在问题，请检查后再提交"
    exit 1
fi

# 添加 Context7 文档搜索
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 添加带环境变量的服务器
codex mcp add my-db --env DATABASE_URL=postgresql://... -- npx -y @modelcontextprotocol/server-postgres

# 查看所有 MCP 服务器
codex mcp list

# 删除 MCP 服务器
codex mcp remove context7

# ~/.codex/config.toml

# STDIO 类型的 MCP 服务器
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
MY_VAR = "my_value"

# HTTP 类型的 MCP 服务器
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

[mcp_servers.figma.http_headers]
X-Figma-Region = "us-east-1"

[mcp_servers.my-server]
command = "node"
args = ["my-server.js"]
cwd = "/path/to/server"           # 工作目录
enabled = true                     # 是否启用（false 可以临时禁用而不删除）
required = true                    # 启动失败时是否中止 Codex
startup_timeout_sec = 15           # 启动超时（默认 10 秒）
tool_timeout_sec = 120             # 工具执行超时（默认 60 秒）
enabled_tools = ["tool_a", "tool_b"]   # 白名单：只允许这些工具
disabled_tools = ["dangerous_tool"]     # 黑名单：禁用这些工具

/mcp
# 如果看到你配置的工具名，说明连接成功

# 允许 Codex 同时访问多个目录
codex --add-dir /path/to/shared-library

/compact
# Codex 会总结之前的对话，释放上下文空间

# 审查当前工作区的变更
/review

# 审查与特定分支的差异
/review Compare changes against main branch

# 审查特定 commit
/review Analyze commit abc1234

# 自定义审查重点
/review Focus on security vulnerabilities and performance issues

# ~/.codex/config.toml

# 当 Agent 完成一轮工作时执行通知
[notification_hook]
command = "osascript"
args = ["-e", "display notification \"Codex 已完成任务\" with title \"Codex CLI\""]

[notification_hook]
command = "terminal-notifier"
args = ["-title", "Codex CLI", "-message", "任务已完成", "-sound", "default"]

# 启用某个功能
codex features enable shell_snapshot

# 禁用某个功能
codex features disable shell_snapshot

# 启动时临时启用/禁用
codex --enable shell_snapshot
codex --disable web_search

# 允许 Codex 写入额外的目录
codex --add-dir /path/to/shared-lib --add-dir /path/to/configs

# 为 bash 生成补全脚本
codex completions bash >> ~/.bashrc

# 为 zsh 生成补全脚本
codex completions zsh >> ~/.zshrc

# 为 fish 生成补全脚本
codex completions fish >> ~/.config/fish/completions/codex.fish

# 1. 重新登录
codex logout
codex login

# 2. 如果使用代理，确保代理配置正确
export HTTPS_PROXY=http://127.0.0.1:7890

# 3. 检查是否是 API Key 过期
codex --config preferred_auth_method="apikey"

# 1. 检查命令是否正确
npx -y @upstash/context7-mcp  # 手动运行看看是否报错

# 2. 检查环境变量
echo $MY_ENV_VAR  # 确认变量已设置

# 3. 增加启动超时
# 在 config.toml 中设置
[mcp_servers.my-server]
startup_timeout_sec = 30

# 方案一：压缩上下文
/compact

# 方案二：开新会话，用简洁的提示重述需求
/new

# 方案三：分解任务
# 不要在一个会话里做太多事情

# 明确引用目标文件
@src/auth/login.ts 只修改这个文件的第 42 行

# 使用 Read Only 模式先分析
/permissions -> Read Only
你：分析一下 @src/auth/ 目录的代码结构
# 确认理解正确后再切回 Auto 模式动手改