Codex CLI 深度指南：安装配置、安全模型与 20+ 高手技巧

┌─────────────────────────────────────────┐
│           Codex CLI (TUI)               │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  Composer    │  │  Approval Engine │  │
│  │  (输入界面)   │  │  (权限审批)       │  │
│  └─────────────┘  └──────────────────┘  │
│  ┌─────────────────────────────────────┐ │
│  │         Sandbox (操作系统级)         │ │
│  │  - 文件系统隔离                      │ │
│  │  - 网络访问控制                      │ │
│  │  - 进程执行限制                      │ │
│  └─────────────────────────────────────┘ │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  MCP 客户端  │  │  Web 搜索        │  │
│  │  (工具扩展)   │  │  (实时/缓存)      │  │
│  └─────────────┘  └──────────────────┘  │
└─────────────────────────────────────────┘
              │
              ▼
     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"

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 搜索
web_search = "live"    # "cached" | "live" | "disabled"

# 推理强度
model_reasoning_effort = "high"

# 交互风格
personality = "pragmatic"    # "friendly" | "pragmatic" | "none"

# 功能开关
[features]
shell_snapshot = true
undo = true
web_search = true

# 信任的项目（跳过信任确认）
[projects."/Users/me/work/my-project"]
trust_level = "trusted"

# ~/.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"

# 全自动 Profile（谨慎使用）
[profiles.auto]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

codex --profile review   # 只读模式做代码审查
codex --profile quick    # 快速省钱模式
codex                    # 默认高性能配置

# 添加到 ~/.zshrc 或 ~/.bashrc

# 日常开发：高推理 + Web 搜索
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"'

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

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

# 自动编辑，但不受信任的命令需审批
codex --sandbox workspace-write --ask-for-approval untrusted

# 只读，永不询问（纯分析模式）
codex --sandbox read-only --ask-for-approval never

# 全自动 + 沙箱保护（减少摩擦）
codex --full-auto

# 完全绕过一切保护（危险！仅限隔离环境）
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 resume
# 显示最近的会话，选择后回车

# 恢复最近的会话
codex resume --last

# 恢复指定会话
codex resume <SESSION_ID>

# 显示所有目录的会话
codex resume --all

你：重构认证模块，先分析一下现有结构
Codex：[分析文件，列出方案]
你：我得走了，明天继续
# 第二天：
$ codex resume --last
你：从第 2 步继续重构

# 任务 A：认证模块重构
codex    # 开始任务 A，做一会儿...
# Ctrl+C 退出

# 任务 B：修个 Bug
codex    # 开始任务 B，修完搞定

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

# 启动时指定
codex -m gpt-5.3-codex
codex --model gpt-5

# 会话中切换
/model    # 交互式模型/推理选择器

# 在 config.toml 中设置
model_reasoning_effort = "high"    # 或 "medium" / "low"

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

# 项目规范

## 代码标准
- 使用 TypeScript 严格模式
- 所有函数必须有 JSDoc 注释
- 测试覆盖率不低于 80%
- 使用 pnpm 作为包管理器（不用 npm 或 yarn）

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

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

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

codex --sandbox read-only --ask-for-approval never "总结一下你加载的指令内容"

# 添加 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

# 移除服务器
codex mcp remove context7

# ~/.codex/config.toml

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

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

[mcp_servers.my-server]
command = "node"
args = ["my-server.js"]
cwd = "/path/to/server"
enabled = true                     # 开关，不用删除配置
required = true                    # 启动失败则中止 Codex
startup_timeout_sec = 15           # 默认 10 秒
tool_timeout_sec = 120             # 默认 60 秒
enabled_tools = ["tool_a", "tool_b"]   # 白名单
disabled_tools = ["dangerous_tool"]     # 黑名单

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

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

# 关闭
web_search = "disabled"

codex --search    # 启用实时搜索

# 给 Codex 额外目录的写入权限
codex --add-dir /path/to/shared-library

# 基本用法
codex exec "Fix all ESLint errors"

# JSON 输出（方便脚本解析）
codex exec --json "Analyze this repo for security vulnerabilities"

# 与其他工具配合
codex exec "List all TODO comments" | 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" \
            "Review code changes in this PR for security and performance issues"

# .git/hooks/pre-commit
#!/bin/bash
codex exec "Check staged code for obvious security issues or bugs"
if [ $? -ne 0 ]; then
    echo "Codex found potential issues. Please review before committing."
    exit 1
fi

# 重新认证
codex logout
codex login

# 如果使用代理
export HTTPS_PROXY=http://127.0.0.1:7890

# 检查 API Key
codex --config preferred_auth_method="apikey"

# 手动测试命令
npx -y @upstash/context7-mcp

# 检查环境变量
echo $MY_ENV_VAR

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

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

# 方案 2：用简短总结开启新会话
/new

# 方案 3：拆分任务
# 不要把太多任务塞进一个会话

# ~/.codex/config.toml

# macOS 通知
[notification_hook]
command = "osascript"
args = ["-e", "display notification \"Task complete\" with title \"Codex CLI\""]

[notification_hook]
command = "terminal-notifier"
args = ["-title", "Codex CLI", "-message", "Task complete", "-sound", "default"]