OpenAI Codex CLI 深度实战：当 Rust 遇上 AI Agent——从终端原生架构到生产级代码助手的完全指南（2026）

作者前言：2025 年 5 月，OpenAI 在 GitHub 上开源了 Codex CLI——一个基于终端的 AI 编程代理工具。2026 年，Codex 迎来密集更新：移动端接入、CLI 迭代至 0.134.0a2、6 个角色专属插件、Sites 建站部署、Annotations 精细修改……这一系列动作标志着 AI 编程助手从"代码补全"到"自主 Agent"的范式转变。本文将从 Rust 架构设计、安全沙箱机制、工程实践到生产级部署，全方位拆解 Codex CLI 的技术内核。

目录

1. 背景介绍：AI 编程工具的三次浪潮
2. Codex CLI 核心架构：Rust 重写背后的工程哲学
3. 安全模型深度拆解：Landlock、Seatbelt 与操作系统级沙箱
4. 安装与配置完全指南：跨平台实战
5. AGENTS.md 与项目指令系统：让 AI 理解你的项目
6. MCP 工具集成：扩展 AI 的能力边界
7. Codex SDK 与多前端架构：一个引擎多种场景
8. 上下文压缩与 Token 优化：让长会话成为可能
9. 实战案例：用 Codex CLI 重构一个 Go 微服务
10. Hooks 与自动化流水线：把 Codex 接入 CI/CD
11. 移动端远程操控：手机变开发机终端
12. 角色专属插件系统：62 款应用、110 个技能的即插即用
13. Sites 建站部署：一句话生成可分享的交互网站
14. Annotations 精细修改：点选任意内容片段局部迭代
15. 性能优化与最佳实践：让 Codex 跑得更快更稳
16. 与 Claude Code、Cursor 的横向对比：谁更适合你的场景
17. 2026 年 6 月重大更新解读：额度收紧与商业化转向
18. 未来展望：AI 编程助手的下一个三年
19. 总结与行动清单

1. 背景介绍：AI 编程工具的第三次浪潮

1.1 第一次浪潮：代码补全时代（2010-2021）

回想起 2010 年代中期的 IDE 插件，Kite、TabNine、Copilot 的早期版本……它们核心做的是一件事：预测下一个 token。

技术栈：

• 模型：CodeParrot、GPT-2 级别的小模型
• 部署：本地运行或轻量 API 调用
• 交互：你打字，它补全
• 局限：无法理解上下文、无法执行操作、只是"高级自动补全"

1.2 第二次浪潮：对话式编程助手（2021-2024）

2021 年 GitHub Copilot 正式发布，2022 年 ChatGPT 爆火，AI 编程进入"对话时代"。

核心技术突破：

• LLM 理解能力跃升：GPT-3.5/4、Claude 2/3 能理解自然语言需求
• Context Window 扩大：从 4K 到 128K，能塞进整个代码库
• 工具调用（Tool Use）：AI 可以执行命令、读写文件、调用 API
• 产品形态：Chat 界面 + IDE 插件

代表产品：

• GitHub Copilot Chat
• Cursor（基于 VSCode 改造）
• Continue.dev（开源方案）
• Aider（终端 + Git 集成）

但这一代产品有个核心痛点：AI 的"手"太短——它能给建议，但执行流程需要你手动复制粘贴、手动运行命令、手动创建文件。

1.3 第三次浪潮：AI Agent 自主编程（2024-2026）

2024 年底到 2025 年，AI 编程进入"Agent 时代"。核心变化：

从"建议"到"执行"：AI 不仅能理解需求，还能自主规划、执行、验证、迭代。

从"单轮对话"到"多步推理"：Agent Loop（代理循环）让 AI 可以：

1. 理解任务
2. 制定计划
3. 执行步骤（读文件、写代码、运行测试）
4. 检查结果
5. 根据反馈调整
6. 循环直到完成

代表产品：

• OpenAI Codex CLI（本文主角）：Rust 编写的终端 AI Agent
• Claude Code：Anthropic 的官方 CLI 工具
• Devin：声称能"自主完成整个开发任务"的 AI 工程师
• Cline：VSCode 中的 AI Agent 插件（60,712 stars）
• OpenCode：Go 语言实现的终端 AI 助手

1.4 为什么是 Rust？

OpenAI 选择 Rust 重写 Codex CLI，背后有深刻的工程考量：

工程哲学思考：为什么不直接用 Python？——AI 公司的"基础设施自研"趋势。OpenAI、Anthropic、Google DeepMind 都在把核心工具链从 Python 转向 Rust/Go。原因：当你的用户是数百万开发者，工具的启动速度、内存占用、安全性，每一个都值得用系统语言重写。

2. Codex CLI 核心架构：Rust 重写背后的工程哲学

2.1 整体架构图

┌─────────────────────────────────────────────────────┐
│                   User (Terminal)                    │
│             输入自然语言指令 / 确认执行                │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│              Codex CLI (Rust Binary)                 │
│  ┌────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │  REPL Loop │  │  Tool Exec  │  │  Sandbox   │ │
│  │  (主循环)   │  │  (工具执行)  │  │  (沙箱)    │ │
│  └──────┬─────┘  └──────┬──────┘  └──────┬─────┘ │
│         │                │                │       │
│  ┌──────▼─────┐  ┌──────▼──────┐  ┌──────▼─────┐ │
│  │ LLM Client │  │  Tool Router│  │ OS Sandbox │ │
│  │ (API调用)   │  │  (工具路由) │  │ (Landlock/ │ │
│  └────────────┘  └─────────────┘  │  Seatbelt) │ │
│                                   └────────────┘ │
└──────────────────┬──────────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────────┐
│              OpenAI API (GPT-5 / codex 模型)         │
│  - 推理能力                                          │
│  - 工具调用规划                                      │
│  - 上下文压缩 (compact API)                          │
└─────────────────────────────────────────────────────┘

2.2 主循环（Agent Loop）详解

Codex CLI 的核心是一个 异步事件循环，用 Tokio 驱动。伪代码逻辑：

// 注意：以下是概念性伪代码，非真实源码
async fn agent_loop(session: &mut Session) {
    loop {
        // 1. 获取用户输入（自然语言指令）
        let user_input = read_user_input().await;
        
        // 2. 构建上下文（历史消息 + 项目文件 + 工具结果）
        let context = session.build_context(user_input).await;
        
        // 3. 调用 LLM（GPT-5 / codex 模型）
        let llm_response = llm_client
            .chat_with_tools(context, &session.tools)
            .await?;
        
        // 4. 解析 LLM 响应
        match llm_response {
            Response::Text(text) => {
                // 纯文本回复，直接展示给用户
                print_to_terminal(text);
            }
            Response::ToolCalls(tool_calls) => {
                // LLM 请求执行工具
                for tool_call in tool_calls {
                    // 5. 检查沙箱权限
                    if !sandbox.check_permission(&tool_call).await {
                        ask_user_approval(tool_call).await;
                    }
                    
                    // 6. 执行工具
                    let result = execute_tool(tool_call).await;
                    
                    // 7. 将结果返回给 LLM，继续循环
                    session.add_tool_result(tool_call.id, result);
                }
            }
            Response::TaskComplete => {
                // 任务完成，退出循环
                break;
            }
        }
        
        // 8. 上下文压缩（长会话时触发）
        if session.context_too_large() {
            session.compact_context().await;
        }
    }
}

关键设计决策：

1. 为什么用异步？

   • 工具执行可能是 IO 密集型的（读文件、运行命令、调用外部 API）
   • 异步能让 UI 保持响应（显示进度条、流式输出）
   • Tokio 的 work-stealing 调度器能充分利用多核

2. 为什么上下文压缩重要？

   • GPT-5 的 context window 是 128K tokens（约 10 万汉字）
   • 但 AI Agent 的会话可能持续数小时，涉及几十轮工具调用
   • 不做压缩，很快就会爆窗口
   • Codex CLI 的策略：对 codex 模型调用 compact() API（返回加密 blob），对非 codex 模型用本地 LLM 压缩

3. 为什么权限检查在工具执行层，而不是 LLM 层？

   • 防御深度：LLM 可能被 prompt injection 攻击，不能只依赖它的"自我约束"
   • 用户控制：关键操作（写文件、执行 Shell 命令）必须用户确认
   • 沙箱兜底：即使 LLM 和工具层都被绕过，操作系统级沙箱仍能限制损害

2.3 与 Claude Code 的架构对比

实战建议：如果你在 macOS 上开发，两者体验相近。但如果你需要部署到 Linux 服务器做 CI/CD，Codex CLI 的 Landlock 沙箱比 Claude Code 的 Seatbelt-only 方案更安全。

3. 安全模型深度拆解：Landlock、Seatbelt 与操作系统级沙箱

3.1 为什么 AI Agent 需要沙箱？

想象这个场景：

用户：帮我优化一下这个项目的性能
AI：好的，我先看看项目结构……
     [执行] find . -name "*.go" | xargs wc -l
     [发现] 有个 build.sh 脚本，看起来可以优化……
     [执行] cat build.sh
     [误解] 这个 rm -rf 命令可以简化……
     [执行] 修改后的 build.sh
     ……项目被删了……

这不是假设。2024-2025 年，多个 AI 编程工具都出现过"误删文件"的事故。原因：

• LLM 的"意图理解"不完美
• Prompt injection（提示词注入）攻击
• 用户指令本身有歧义

解决方案：操作系统级沙箱——不让 AI 碰到它不该碰的文件。

3.2 Codex CLI 的三种沙箱模式

Codex CLI 通过 --sandbox 参数控制沙箱强度：

# 模式 1：只读（最安全）
codex --sandbox=read-only
# AI 可以读任何文件，但不能写、不能执行命令

# 模式 2：工作区可写（推荐）
codex --sandbox=workspace-write
# AI 可以读写当前项目目录，但不能碰系统文件

# 模式 3：完全访问（不安全，仅开发用）
codex --sandbox=danger-full-access
# 不做任何沙箱限制，AI 能为所欲为

实现原理：

Linux: Landlock LSM

Landlock 是 Linux 5.13+ 的内核特性，允许 unprivileged 进程自限制权限。

// Landlock 核心 API（概念性）
int landlock_create_ruleset(const struct landlock_ruleset_attr *attr, size_t size, __u32 flags);
int landlock_add_rule(int ruleset_fd, enum landlock_rule_type rule_type, const void *rule_attr, __u32 flags);
int landlock_restrict_self(int ruleset_fd, __u32 flags);

Codex CLI 的 Rust 实现（简化）：

// 注意：概念性代码，展示原理
#[cfg(target_os = "linux")]
mod sandbox_linux {
    use landlock::{AccessFs, Ruleset};
    
    pub fn apply_workspace_write_sandbox(workdir: &Path) -> Result<()> {
        let ruleset = Ruleset::new()
            // 允许读所有文件
            .handle_access(AccessFs::from_read())?
            // 允许写工作区
            .add_rule(PathRule::new(workdir, AccessFs::from_write()))?
            // 禁止执行任何命令
            .add_rule(PathRule::new("/usr/bin", AccessFs::execute().invert()))?
            .create()?;
        
        ruleset.restrict_self()?;
        Ok(())
    }
}

macOS: Seatbelt (sandbox-exec)

macOS 的 Seatbelt 是强制访问控制（MAC）系统，通过 Scheme 语言描述权限。

;; Codex CLI 生成的 Seatbelt Profile（概念性）
(version 1)
(deny default)
(allow read)  ; 允许读
(allow write (subpath "/path/to/project"))  ; 只允许写项目目录
(deny exec)  ; 禁止执行
(allow process-fork)  ; 允许创建子进程（用于工具执行）

// macOS 实现（简化）
#[cfg(target_os = "macos")]
mod sandbox_macos {
    pub fn apply_sandbox(profile: &str) -> Result<()> {
        // 1. 将 profile 写入临时文件
        let profile_path = write_temp_profile(profile)?;
        
        // 2. 通过 sandbox-exec 启动子进程
        let status = Command::new("sandbox-exec")
            .arg("-f")
            .arg(profile_path)
            .arg("--")
            .arg(std::env::args().next().unwrap())
            .status()?;
        
        // 3. 子进程受到沙箱限制
        Ok(())
    }
}

3.3 四种权限审批策略

除了沙箱，--ask-for-approval 参数控制"何时询问用户"：

# 策略 1：不信任任何操作（最安全）
codex --ask-for-approval=untrusted
# 每次工具调用都问用户

# 策略 2：失败时询问（推荐）
codex --ask-for-approval=on-failure
# 只有工具执行失败时才问

# 策略 3：请求时询问
codex --ask-for-approval=on-request
# AI "请求权限"时才问

# 策略 4：永远不询问（危险！）
codex --ask-for-approval=never
# 完全自动执行，不询问用户

实战建议：

• 生产环境 → read-only + untrusted
• 日常开发 → workspace-write + on-failure
• 调试模式 → danger-full-access + never（但只在隔离环境）

4. 安装与配置完全指南：跨平台实战

4.1 前置条件

4.2 macOS 安装（推荐方式）

# 方式 1：Homebrew（推荐）
brew install --cask codex

# 方式 2：npm 全局安装
npm install -g @openai/codex

# 验证安装
codex --version
# 应输出: 0.134.0 或更高

Homebrew 安装的优势：

• 自动处理依赖（Node.js、OpenSSL）
• 系统集成（/Applications/Codex.app）
• 自动更新（brew upgrade --cask codex）

4.3 Linux 安装（Ubuntu/Debian）

# 方式 1：npm 全局安装
npm install -g @openai/codex

# 方式 2：直接下载二进制（无需 Node.js）
curl -fsSL https://codex.openai.com/install.sh | sh

# 验证 Landlock 支持（重要！）
uname -r
# 需要 Linux 5.13+ 才能用 Landlock 沙箱
# 如果版本不够，用 --sandbox=read-only（不依赖 Landlock）

Linux 沙箱注意事项：

• Linux ≥ 5.13：--sandbox=workspace-write 可用（Landlock）
• Linux < 5.13：只能用 --sandbox=read-only 或 danger-full-access
• Docker 容器内运行：需要 --privileged 或明确禁用沙箱

4.4 Windows 安装（WSL2 推荐）

# 在 WSL2 中（推荐）
curl -fsSL https://codex.openai.com/install.sh | sh

# 原生 Windows (PowerShell)
# 注意：Windows 原生沙箱支持有限，建议用 WSL2
npm install -g @openai/codex

Windows 原生限制：

• 无 Landlock / Seatbelt，沙箱依赖 Windows Defender Application Control（WDAC）
• 建议：开发用 WSL2，生产用 Linux 服务器

4.5 认证配置（三种方式）

方式 1：交互式登录（推荐）

codex login
# 会打开浏览器，完成 OAuth  flow
# 凭据保存到 ~/.codex/auth.json

方式 2：API Key（适合 CI/CD）

export OPENAI_API_KEY="sk-..."
codex --api-key-mode

方式 3：配置文件

# ~/.codex/config.toml
[auth]
api_key = "sk-..."  # 不推荐明文，用 login 更安全
model = "gpt-5"
base_url = "https://api.openai.com/v1"  # 或中转服务

[sandbox]
mode = "workspace-write"
ask_for_approval = "on-failure"

[logging]
level = "info"
file = "~/.codex/logs/codex.log"

4.6 网络代理配置（企业环境）

# 方式 1：环境变量
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# 方式 2：config.toml
[proxy]
https = "http://proxy.company.com:8080"
http = "http://proxy.company.com:8080"

5. AGENTS.md 与项目指令系统：让 AI 理解你的项目

5.1 为什么需要 AGENTS.md？

Claude Code 用 CLAUDE.md，Codex CLI 用 AGENTS.md——本质是一样的：

让 AI 在动手之前，先读懂你的项目约定。

没有 AGENTS.md 时：

用户：帮我加一个用户注册接口
AI：[生成了 Express + MongoDB 的代码]
用户：……我们项目用的是 Gin + PostgreSQL，你这完全不对

有 AGENTS.md 后：

用户：帮我加一个用户注册接口
AI：[读取 AGENTS.md]
    "哦，这个项目用 Gin 框架，PostgreSQL，遵循 RESTful 风格"
AI：[生成符合项目约定的代码]
用户：完美！

5.2 AGENTS.md 最佳实践

# AGENTS.md（放在项目根目录）

## 项目概述
这是一个 Go + Gin 的微服务模板，使用 PostgreSQL 作为数据库。

## 技术栈
- 语言：Go 1.22+
- 框架：Gin（HTTP 路由）
- ORM：GORM
- 数据库：PostgreSQL 16
- 缓存：Redis
- 日志：log/slog（标准库）
- 测试：testing + testify

## 代码规范
- 使用 gofmt 格式化（CI 检查）
- 错误处理：返回 error 而非 panic
- 日志：用 slog 而非 fmt.Println
- API 风格：RESTful，复数资源名（/users, /orders）
- 提交信息：Conventional Commits（feat/fix/chore/docs）

## 项目结构

cmd/
api/ # 主服务入口
worker/ # 后台任务入口
internal/
handler/ # HTTP handlers
service/ # 业务逻辑
repository/ # 数据访问层
model/ # 数据模型
middleware/ # Gin 中间件
configs/ # 配置文件
scripts/ # 构建/部署脚本

## 常用命令
- `make dev`：启动开发服务器（热重载）
- `make test`：运行测试
- `make migrate-up`：数据库迁移（向上）
- `make migrate-down`：数据库回滚
- `make lint`：代码检查

## AI 协作提示
- 生成新接口时，参考 internal/handler/user.go 的风格
- 数据库模型变更时，必须创建新的 migration 文件
- 不要直接在 main.go 中添加业务逻辑
- 测试文件命名：*_test.go，与被测试文件同包

5.3 AGENTS.md 的加载优先级

Codex CLI 按以下顺序加载指令：

1. ~/.codex/AGENTS.md（全局指令，所有项目共享）
2. ./AGENTS.md（项目根目录）
3. ./.codex/AGENTS.md（项目局部配置，优先级最高）
4. 命令行参数 --instructions "额外指令"

实战技巧：

• 把"个人偏好"放全局 AGENTS.md（如："用中文回复"、"代码注释用中文"）
• 把"项目特定约定"放项目 AGENTS.md
• 敏感信息（API Key、密码）不要放 AGENTS.md，用环境变量

6. MCP 工具集成：扩展 AI 的能力边界

6.1 什么是 MCP？

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，用于 让 AI 连接外部数据源和工具。

类比：MCP = AI 世界的 USB 接口标准。

• 没有 MCP 时：每个 AI 工具都要自己实现 GitHub API、数据库查询、文件读取……
• 有 MCP 后：工具提供 MCP Server，AI 通过标准协议调用

6.2 Codex CLI 中的 MCP 配置

// ~/.codex/mcp_servers.json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
    }
  },
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
    }
  },
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/safe/directory"]
  }
}

配置完成后，Codex CLI 启动时会自动连接这些 MCP Server，AI 就能：

• 直接查询 GitHub Issues
• 执行 SQL 查询
• 读写指定目录的文件

6.3 实战：让 Codex 帮你管理 GitHub Issues

用户：看看我们这个 repo 有哪些 P1 的 bug

AI：[调用 github MCP]
    我找到了 3 个 P1 bug：
    1. #142 "内存泄漏 in user service" (open, assigned to @alice)
    2. #138 "数据库连接池耗尽" (open, unassigned)
    3. #135 "Redis 缓存穿透" (open, assigned to @bob)
    
    需要我帮你创建一个 PR 修复 #138 吗？

用户：好，先帮我本地复现一下

AI：[执行] go test -run TestConnectionPoolExhaustion
    [发现] 确实能复现，连接池最大 10 个连接，但代码里有泄漏
    [修复] 我找到了问题，在 internal/repository/user.go:42，
            defer stmt.Close() 没被调用
    [生成修复代码]
    [运行测试] go test -run TestConnectionPoolExhaustion
    [通过] 已修复，需要我创建 PR 吗？

7. Codex SDK 与多前端架构：一个引擎多种场景

7.1 "一个引擎、多种前端"设计

OpenAI 在 2026 年的 Codex 产品线，采用了 核心引擎 + 多前端 的架构：

┌─────────────────────────────────────────────────┐
│           Codex Engine (Rust Core)              │
│  - Agent Loop                                   │
│  - Tool System                                  │
│  - Sandbox Management                           │
│  - Context Compression                          │
└──────────┬─────────────────────────────────────┘
           │
    ┌──────┴──────┬──────────┬──────────┐
    ▼             ▼          ▼          ▼
 Codex CLI    Codex       Codex      Codex
 (终端)       Desktop     Mobile     Web
             (桌面App)   (iOS/Android) (浏览器)

优势：

• 核心逻辑复用：Agent Loop、工具系统、沙箱……只需写一次
• 前端专注体验：CLI 追求极客效率，Desktop 追求图形化，Mobile 追求随时随地
• 统一能力：CLI 能做的，Desktop/Mobile 也能做

7.2 Codex SDK（@openai/codex-sdk）

OpenAI 将核心引擎打包成了 SDK，供开发者集成：

// TypeScript 示例（概念性）
import { Codex } from '@openai/codex-sdk';

const codex = new Codex({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-5',
  sandbox: 'workspace-write',
});

// 执行一个任务
const result = await codex.runTask({
  instruction: '帮我重构 user service，把数据库访问层抽成 interface',
  workdir: '/path/to/project',
  onToolCall: (toolCall) => {
    console.log(`AI 正在执行: ${toolCall.name}`);
  },
  onApprovalNeeded: (toolCall) => {
    return promptUser(`允许执行 ${toolCall.name}? [y/n]`);
  },
});

console.log(result.summary);

使用场景：

• 集成到 CI/CD（自动代码审查、自动修复）
• 构建自定义 AI 编程工具
• 在企业内部平台中嵌入 Codex 能力

8. 上下文压缩与 Token 优化：让长会话成为可能

8.1 问题：Context Window 不够用

即使 GPT-5 有 128K tokens 的上下文窗口，长时间对话仍会爆：

假设：
- 每次工具调用平均消耗 500 tokens（请求 + 响应）
- 一个复杂任务可能需要 50 次工具调用
- 总消耗：50 × 500 = 25,000 tokens
- 加上系统提示词、AGENTS.md、用户指令……
- 轻松突破 128K

8.2 Codex CLI 的两种压缩策略

策略 1：调用 compact() API（codex 模型）

// 仅当使用 OpenAI 的 codex 模型时可用
async fn compact_with_api(session: &mut Session) -> Result<()> {
    let response = llm_client
        .post("https://api.openai.com/v1/compact")
        .json(&json!({
            "messages": session.messages,
            "model": "codex-compact-1",
        }))
        .send()
        .await?;
    
    let compressed = response.json::<CompressedContext>().await?;
    // compressed.blob 是加密的压缩后的上下文
    session.compressed_blob = Some(compressed.blob);
    session.messages.clear();  // 清空原始消息，节省空间
    
    Ok(())
}

优势：

• 压缩率高（能压缩 90%+ 的上下文）
• 加密 blob（OpenAI 保证不会泄露原始内容）

劣势：

• 仅限 codex 模型（GPT-5 不能用）
• 需要额外 API 调用（消耗额度）

策略 2：本地 LLM 压缩（非 codex 模型）

// 使用本地运行的小模型（如 GPT-4o-mini）做压缩
async fn compact_locally(session: &mut Session) -> Result<()> {
    let summary_prompt = r#"
    以下是之前的对话记录，请提取关键信息：
    - 已完成的任务
    - 当前进行中的任务
    - 重要的决策和上下文
    "#;
    
    let response = llm_client
        .chat("gpt-4o-mini")  // 用便宜的模型做压缩
        .message(summary_prompt)
        .message(session.messages_to_string())
        .send()
        .await?;
    
    let summary = response.text();
    session.messages = vec![Message::system(summary)];
    
    Ok(())
}

8.3 实战：避免不必要的上下文膨胀

技巧 1：用 .codexignore 排除无关文件

# .codexignore（类似 .gitignore）
*.log
*.tmp
node_modules/
dist/
build/
*.min.js

技巧 2：明确指令范围

❌ 不好：帮我优化这个项目
✅ 很好：帮我优化 internal/service/user.go 中的 GetUserByID 函数，
          主要是 N+1 查询问题

技巧 3：定期用 /compact 手动压缩

(codex) >>> /compact
[Codex 正在压缩上下文……]
[完成！原始 45000 tokens → 压缩后 3200 tokens]

9. 实战案例：用 Codex CLI 重构一个 Go 微服务

9.1 场景设定

你接手了一个 Go 微服务项目，发现以下问题：

• 数据库访问层直接写在 handler 里（没有 repository 层）
• 错误处理不一致（有的返回 error，有的 panic）
• 没有测试
• 日志用 fmt.Println（应该用 slog）

9.2 使用 Codex CLI 逐步重构

第 1 步：让 Codex 理解项目

cd /path/to/project
codex

(codex) >>> 先帮我分析一下这个项目的结构，找出主要的技术债务

AI 会：

1. 读取项目文件
2. 分析代码结构
3. 给出技术债务清单

AI 分析结果：

我发现以下技术债务：

1. 【高优先级】数据库访问直接写在 handler 里（user.go:42-67）
2. 【高优先级】没有单元测试（整个项目 0 测试覆盖率）
3. 【中优先级】日志用 fmt.Println 而非 slog（共 23 处）
4. 【中优先级】错误处理不一致（有的返回 error，有的直接 panic）
5. 【低优先级】没有 API 文档（可以用 Swagger 生成）

建议重构顺序：
1. 先抽 repository 层（解决技术债务 1）
2. 加单元测试（解决技术债务 2）
3. 统一日志（解决技术债务 3）
4. 统一错误处理（解决技术债务 4）

需要我开始吗？

第 2 步：重构 repository 层

(codex) >>> 好，先帮我抽 repository 层。
          要求：用 GORM，遵循项目现有的代码风格

AI 会：

1. 创建 internal/repository/user_repository.go
2. 把 handler 里的数据库操作移过去
3. 修改 handler，调用 repository
4. 运行测试，确保没破坏功能

// AI 生成的 user_repository.go
package repository

import (
    "gorm.io/gorm"
    "myproject/internal/model"
)

type UserRepository interface {
    FindByID(id uint) (*model.User, error)
    FindByEmail(email string) (*model.User, error)
    Create(user *model.User) error
    Update(user *model.User) error
    Delete(id uint) error
}

type userRepository struct {
    db *gorm.DB
}

func NewUserRepository(db *gorm.DB) UserRepository {
    return &userRepository{db: db}
}

func (r *userRepository) FindByID(id uint) (*model.User, error) {
    var user model.User
    result := r.db.First(&user, id)
    return &user, result.Error
}

// ... 其他方法

第 3 步：添加单元测试

(codex) >>> 帮我给 user repository 加单元测试，用 testify

AI 会：

1. 创建 internal/repository/user_repository_test.go
2. 用 testcontainers 启动真实 PostgreSQL（或用 mock）
3. 编写测试用例（增删改查 + 边界情况）
4. 运行测试 go test -v ./...

第 4 步：统一日志

(codex) >>> 把项目里所有 fmt.Println 改成 slog，
          日志格式要 JSON，输出到 stdout

AI 会：

1. 找到所有 fmt.Println（23 处）
2. 替换成 slog.Info / slog.Error
3. 在 cmd/api/main.go 里配置 slog（JSON 格式，stdout）

// main.go 里的日志配置
func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    }))
    slog.SetDefault(logger)
    
    // ...
}

9.3 重构结果

(codex) >>> /review

AI 会生成一份重构总结：

重构完成！以下是变更统计：

✅ 技术债务 1（repository 层）：已解决
   - 新增文件：internal/repository/user_repository.go
   - 修改文件：internal/handler/user.go（删除数据库操作代码）

✅ 技术债务 2（单元测试）：已解决
   - 新增文件：internal/repository/user_repository_test.go
   - 测试覆盖率：78%（目标 80%+，建议补充边界测试）

✅ 技术债务 3（日志）：已解决
   - 修改文件：23 个文件里的 fmt.Println → slog

⚠️  技术债务 4（错误处理）：部分解决
   - 已修改：internal/repository/ 里的所有错误都返回 error
   - 未修改：internal/handler/ 里还有 3 处 panic（建议改为返回 error）

❌ 技术债务 5（API 文档）：未解决
   - 建议：用 swag 生成 Swagger 文档

需要我继续处理未完成的吗？

10. Hooks 与自动化流水线：把 Codex 接入 CI/CD

10.1 什么是 Hooks？

Hooks 是 Codex CLI 的 生命周期钩子，让你在 AI 执行特定操作时注入自定义逻辑。

支持的事件：

• pre_tool_call：工具执行前
• post_tool_call：工具执行后
• pre_compact：上下文压缩前
• post_compact：上下文压缩后
• on_error：发生错误时

10.2 配置 Hooks

# ~/.codex/config.toml
[hooks]
pre_tool_call = "~/.codex/hooks/pre_tool_call.sh"
post_tool_call = "~/.codex/hooks/post_tool_call.sh"
on_error = "~/.codex/hooks/on_error.sh"

#!/bin/bash
# ~/.codex/hooks/pre_tool_call.sh

# 记录所有 AI 执行的命令（审计日志）
echo "$(date): AI 执行工具: $TOOL_NAME" >> ~/.codex/logs/audit.log
echo "  参数: $TOOL_ARGS" >> ~/.codex/logs/audit.log

# 如果是危险操作（删除文件），发送 Slack 通知
if [[ "$TOOL_NAME" == "bash" ]] && [[ "$TOOL_ARGS" == *"rm -rf"* ]]; then
    curl -X POST $SLACK_WEBHOOK -d "text=⚠️ AI 正在执行危险操作: $TOOL_ARGS"
fi

10.3 实战：Codex 自动代码审查（GitHub Actions）

# .github/workflows/codex-review.yml
name: Codex AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  codex-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Codex CLI
        run: npm install -g @openai/codex
      
      - name: Run Codex Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex --non-interactive --task "
            审查这个 PR 的代码变更，重点检查：
            1. 有没有明显的 bug
            2. 有没有安全风险（SQL 注入、XSS 等）
            3. 代码风格是否符合项目约定
            
            将审查结果评论到 PR 上。
          "
      
      - name: Post Review Comments
        uses: mshick/add-pr-comment@v2
        with:
          message: |
            ## Codex AI 审查结果
            ${{ env.CODEX_REVIEW_OUTPUT }}

11. 移动端远程操控：手机变开发机终端

11.1 功能介绍

2026 年 5 月 14 日，OpenAI 发布 Codex 移动端（iOS/Android 预览版）。

核心能力：通过 ChatGPT App 远程连接到你的开发机，把手机变成终端控制器。

使用场景：

• 在外面突然需要改 bug
• 在会议上查看代码
• 躺在床上review PR

11.2 配置步骤

第 1 步：开发机启用远程访问

# 在开发机上
codex remote enable
# 会生成一个配对码（如：ABC-DEF-GHI）

第 2 步：手机端配对

1. 打开 ChatGPT App（需更新到 2026 年 5 月版）
2. 进入 Codex 标签页
3. 点击"配对开发机"
4. 输入配对码

第 3 步：开始远程操控

手机端:
> 帮我看看服务器日志，有没有报错

Codex (连接开发机):
[执行] ssh prod-server "tail -n 100 /var/log/app.log"
[返回] 发现 3 个 ERROR：
  1. 2026-06-08 15:23:45 [ERROR] 数据库连接超时
  2. 2026-06-08 15:24:12 [ERROR] Redis 缓存穿透
  3. 2026-06-08 15:25:03 [ERROR] 外部 API 调用失败
  
需要我帮你修复吗？

手机端:
> 先看看第一个错误的详细堆栈

Codex:
[执行] ssh prod-server "grep -A 20 '数据库连接超时' /var/log/app.log"
[返回] 堆栈跟踪：
  ...
  internal/repository/user.go:42
  database/sql.DB.QueryContext(...)
  ...
  
看起来是连接池耗尽导致的问题，需要我创建一个修复 PR 吗？

11.3 安全注意事项

• 配对码是 一次性 的，用完即废
• 远程连接使用 端到端加密（WireGuard 隧道）
• 可以设置 IP 白名单（只允许公司网络访问）
• 建议配合 --sandbox=read-only 使用（防止手机端误操作）

12. 角色专属插件系统：62 款应用、110 个技能的即插即用

12.1 什么是角色插件？

2026 年 6 月 2 日，OpenAI 发布 Codex 重大更新：6 个角色专属插件，每个插件打包了：

• 相关应用（如"前端开发"插件包含 VSCode、Chrome DevTools、Figma）
• 专项技能（如"调试 React 组件"、"优化 webpack 构建"）
• 指令和工作流

本质：把"某个角色的最佳实践"打包成可复用插件。

12.2 6 个角色插件

12.3 安装和使用

# 方式 1：通过 Codex CLI 安装
codex plugin install frontend-developer

# 方式 2：通过 ChatGPT App（图形界面）
# 设置 → Plugins → 浏览插件市场 → 安装

# 使用插件中的技能
(codex) >>> /skill debug-react-component
[AI 加载 frontend-developer 插件中的 debug-react-component 技能]
[执行] 打开 Chrome DevTools...
[执行] 分析 React 组件树...
[输出] 发现 3 个性能瓶颈...

12.4 自定义插件

如果官方插件不满足需求，可以自己写：

# ~/.codex/plugins/my-plugin/plugin.yaml
name: my-plugin
version: 1.0.0
description: 我的自定义插件
apps:
  - name: VSCode
    path: /Applications/Visual Studio Code.app
  - name: iTerm2
    path: /Applications/iTerm.app
skills:
  - name: debug-go-routine-leak
    description: 调试 Go 协程泄漏
    prompt: |
      你是一个 Go 性能调优专家。
      当用户报告"内存占用高"或"协程数暴涨"时：
      1. 用 go tool pprof 抓取 heap profile
      2. 分析 top 10 内存占用函数
      3. 给出优化建议
    tools:
      - bash
      - file_read
      - file_write

13. Sites 建站部署：一句话生成可分享的交互网站

13.1 功能介绍

Codex 的 Sites 功能（2026 年 6 月上线）让 AI 不仅能写代码，还能直接部署。

传统流程：

1. AI 生成 HTML/CSS/JS
2. 你手动创建 GitHub Repo
3. 手动推送到 GitHub Pages / Vercel / Netlify
4. 等待部署完成
5. 复制链接，分享给别人

Codex Sites 流程：

用户：帮我做一个"团队 OKR 看板"，要能拖拽排序，
     做完好直接部署，我要分享给团队

AI：[生成代码……]
    [执行] codex sites deploy --name team-okr-board
    [输出] ✅ 部署成功！
          URL: https://sites.codex.openai.com/team-okr-board
          有效期：30 天（可延长）
    
    需要我帮你生成二维码方便分享吗？

13.2 技术实现

Codex Sites 的背后是 OpenAI 托管的静态网站托管服务：

用户请求
  ↓
Codex CLI 生成静态文件（HTML/CSS/JS）
  ↓
上传到 OpenAI CDN（全球边缘节点）
  ↓
生成唯一 URL（sites.codex.openai.com/xxx）
  ↓
用户访问（低延迟、高可用）

支持的功能：

• 纯静态网站（HTML/CSS/JS）
• 单页应用（React/Vue/Svelte）
• WebAssembly（Rust 编译的 .wasm）
• 表单提交（自动对接 Formspree）
• 自定义域名（需验证所有权）

13.3 实战：做一个"每日技术新闻"网站

(codex) >>> 帮我做一个"每日技术新闻"网站，
          要求：
          1. 自动抓取 Hacker News Top 10
          2. 用卡片式布局展示
          3. 支持暗黑模式
          4. 部署到 Sites

AI：[生成代码……]
    [创建] index.html（主页面）
    [创建] style.css（样式，支持暗黑模式）
    [创建] app.js（抓取 HN API + 渲染逻辑）
    [执行] codex sites deploy --name daily-tech-news
    [输出] ✅ 部署成功！
          URL: https://sites.codex.openai.com/daily-tech-news
    
    已帮你部署。这个网站会自动刷新 HN Top 10，
    暗黑模式按钮在右上角。
    
    需要我帮你加一个"收藏"功能吗？

14. Annotations 精细修改：点选任意内容片段局部迭代

14.1 传统 AI 编程的痛点

用户：把按钮改成蓝色

AI：[重新生成整个文件]
    [输出] 这是修改后的 App.js……
    （但其实你只想要改一行代码，AI 却把整个文件都重写了）

问题：AI 的"修改"往往是"重新生成"，导致：

• 不必要的变更（git diff 一大堆）
• 可能引入新 bug
• 审查困难

14.2 Annotations 解决方案

Codex 的 Annotations 功能（2026 年 6 月上线）让你可以点选任意内容片段，告诉 AI"就改这里"。

使用流程：

第 1 步：AI 生成初稿
AI：[生成] App.js
    [输出] 这是初稿，请review……
    
第 2 步：用户点选要修改的部分
用户：[在终端里用鼠标选中第 42-45 行]
      （这些行的背景变成黄色，表示"已标注"）

第 3 步：用户输入修改指令
用户：>>> 这里的按钮颜色改成蓝色，不要用 inline style，
      用 CSS class

第 4 步：AI 只修改标注的部分
AI：[只修改第 42-45 行]
    [输出] 已修改，这是 diff：
    
    - <button style="color: red">Click me</button>
    + <button className="btn-primary">Click me</button>
    
    [问] 需要我同步修改 CSS 文件吗？

用户：>>> 需要

AI：[修改] style.css
    [添加] .btn-primary { color: blue; }
    [输出] 完成！

14.3 技术实现

Annotations 的背后是 细粒度代码编辑 API：

// 概念性代码
async fn apply_annotation_edit(
    file: &Path,
    annotation: &Annotation,  // 用户标注的范围
    instruction: &str,        // 修改指令
) -> Result<EditDiff> {
    // 1. 读取文件
    let source = fs::read_to_string(file)?;
    
    // 2. 提取标注部分的代码
    let annotated_code = annotation.extract_from(&source);
    
    // 3. 调用 LLM，只修改标注部分
    let modified_code = llm_client
        .chat(&format!(
            "只修改以下代码：\n{}\n修改要求：{}",
            annotated_code, instruction
        ))
        .await?;
    
    // 4. 生成 diff（用 similar 库做三路合并）
    let diff = Diff::compute(annotated_code, &modified_code);
    
    Ok(diff)
}

15. 性能优化与最佳实践：让 Codex 跑得更快更稳

15.1 启动速度优化

问题：每次执行 codex 命令，都要：

1. 启动 Rust 二进制（~50ms）
2. 加载配置（~20ms）
3. 初始化 LLM 客户端（~100ms）
4. 连接 MCP Servers（~200ms）
   总计：~400ms

优化方案：用 daemon 模式

# 启动 Codex daemon（后台常驻）
codex daemon start

# 后续执行会连接到 daemon（跳过初始化）
codex --client "帮我看看这个 bug"
# 现在只需 ~100ms（daemon 已经初始化好了）

15.2 Token 消耗优化

Codex CLI 的 API 调用费用主要取决于 输入 tokens（上下文）。

优化技巧：

1. 用 .codexignore 排除无关文件（见第 8 章）
2. 明确指令范围（不要说"帮我优化这个项目"，要说"帮我优化 internal/service/user.go"）
3. 定期 /compact（手动触发上下文压缩）
4. 用 GPT-4o-mini 做压缩（便宜 20 倍）
5. 避免重复读取大文件

❌ 不好：
(codex) >>> [上传了一个 10MB 的日志文件]
           帮我分析这个日志

✅ 很好：
(codex) >>> 帮我分析 /var/log/app.log 的最后 100 行
           [执行] tail -n 100 /var/log/app.log
           [分析] 只有 100 行被加入上下文（而不是 10MB）

15.3 工具调用并发优化

默认情况下，Codex CLI 串行执行工具调用：

AI: 我需要读取 3 个文件
[执行] 读取 file1.go (耗时 100ms)
[执行] 读取 file2.go (耗时 100ms)
[执行] 读取 file3.go (耗时 100ms)
总计：300ms

优化：启用并发工具调用

# ~/.codex/config.toml
[tools]
max_concurrent_calls = 5  # 最多同时执行 5 个工具

AI: 我需要读取 3 个文件
[并发执行] 读取 file1.go (100ms)
          读取 file2.go (100ms)
          读取 file3.go (100ms)
总计：100ms（3 倍加速）

15.4 网络优化（国内用户）

如果你在国内使用 Codex CLI，直接连接 api.openai.com 可能很慢。

方案 1：用合规的中转服务

# ~/.codex/config.toml
[api]
base_url = "https://your-proxy.com/v1"  # 中转服务地址

方案 2：启用流式输出

codex --stream  # 边生成边输出，感觉更快（实际延迟没变，但体验更好）

16. 与 Claude Code、Cursor 的横向对比：谁更适合你的场景

16.1 功能对比矩阵

16.2 适用场景推荐

选 Codex CLI，如果你：

• 是"终端原教旨主义者"（vim/tmux 重度用户）
• 需要严格的沙箱安全（在生产服务器上运行）
• 想要移动端远程操控
• 需要 Sites 快速部署原型
• 已经是 OpenAI API 用户

选 Claude Code，如果你：

• 更信任 Anthropic 的 AI 安全理念
• 主要写 Python/JavaScript（Claude 擅长这些语言）
• 不需要移动端/MCP

选 Cursor，如果你：

• 想要"开箱即用"的体验（不想折腾 CLI）
• 主要做前端开发（Cursor 的 VSCode 集成很棒）
• 不介意每月 $20

16.3 实战：同一个任务，三个工具的表现

任务：重构一个 Express.js 项目，把回调地狱改成 async/await。

Codex CLI

(codex) >>> 帮我重构 routes/user.js，把回调改成 async/await
AI：[读取文件]
    [分析] 发现 8 处回调函数
    [重构] 已完成，这是 diff：
    [展示 diff]
    [问] 需要我同时修改测试文件吗？
用户：>>> 需要
AI：[修改] test/user.test.js
    [运行] npm test
    [输出] ✅ 所有测试通过

特点：极客风格，全程终端，适合命令行重度用户。

Claude Code

$ claude
> 帮我重构 routes/user.js，把回调改成 async/await

Claude: 我看了你的代码，确实有 8 处回调可以改。
        我帮你改一下……
        [展示 diff]
        
        要我跑一下测试吗？

> 要

Claude: [运行 npm test]
        ✅ 测试通过！
        
        另外，我发现你的 error handler 也可以优化，
        需要我一起改吗？

特点：对话更自然，Claude 会主动提建议。

Cursor

1. 用 VSCode 打开项目
2. 选中 routes/user.js
3. 按 Cmd+K（Cursor 快捷键）
4. 输入："Refactor callbacks to async/await"

Cursor: [直接在编辑器里展示修改]
        [问] Apply these changes?

5. 按 Cmd+Y（接受）

Cursor: ✅ Changes applied!
        [提示] Run tests? (Click here)

6. 点击"Run tests"

特点：图形化，所见即所得，适合不喜欢命令行的开发者。

17. 2026 年 6 月重大更新解读：额度收紧与商业化转向

17.1 额度政策变更（2026.6.1）

OpenAI 自 2026 年 6 月 1 日起调整 Codex 额度政策：

变更前（2026 年 4-5 月）：

• 免费用户：每周重置额度（约 50 次对话）
• 付费用户（Plus/Pro）：双倍额度 + 每周重置
• Go 用户：与企业版同等待遇

变更后（2026 年 6 月起）：

• 免费用户：每月重置额度（不是每周），单月总配额不变 → 实际每周可用额度减少 75%
• Plus/Pro 用户：失去双倍额度权益
• Go 用户：额度重置周期从每周改为每月
• 免费版禁用 gpt-5.4（只能用 gpt-5.2）

17.2 为什么收紧额度？

官方说法（from OpenAI 内部报告）：

1. 注册机批量账号：有人用脚本注册几万个免费账号，刷 API 额度转卖
2. IPO 筹备期：OpenAI 需要在上市前展示"健康的单位经济"
3. 推动付费转化：让重度用户转向 $100/月的 Pro 套餐

社区反应：

• "额度荒"：免费用户反馈"还没到周末额度就用完了"
• "体验断崖式下滑"：从"随便用"到"斤斤计较"
• 有人转向 Claude Code（同等功能，价格更透明）

17.3 应对策略

如果你受影响，可以考虑：

1. 优化 Token 消耗（见第 15 章）
2. 用本地模型（Codex CLI 支持对接 Ollama / LM Studio）

   codex --local-model ollama/llama3.1:8b
   

3. 转向 Claude Code（如果你主要写 Python/JS）
4. 等企业版（如果你是公司用户，等 OpenAI 推出 Team 套餐）

18. 未来展望：AI 编程助手的下一个三年

18.1 短期（2026-2027）：多模态与协作

多模态输入：

• 拍一张纸上的架构图 → AI 自动生成代码
• 录制屏幕操作 → AI 生成自动化测试脚本

团队协作：

• 多个开发者 + 多个 AI Agent 协同工作
• AI 自动分配任务（"这个 issue 适合 Alice 做，那个适合 Bob"）

18.2 中期（2027-2028）：自主测试与部署

自主测试：

• AI 不仅写代码，还写测试
• 发现 bug → 自动修复 → 重新运行测试 → 循环直到通过

自主部署：

• AI 完成代码后，自动创建 PR → 触发 CI/CD → 部署到生产
• 监控生产指标，如果发现异常，自动回滚

18.3 长期（2028+）：AI 同事

不是"工具"，是"同事"：

• AI 有持久记忆（记住你的偏好、项目历史）
• AI 主动提建议（"你这个设计可能导致性能问题，建议……"）
• AI 参与 code review（而且比人类更仔细）

伦理与监管：

• AI 写的代码，版权归谁？
• AI 犯了个严重 bug，谁负责？
• 是否需要"AI 程序员执照"？

19. 总结与行动清单

19.1 核心要点回顾

1. Codex CLI 是 Rust 写的终端 AI Agent，主打安全（Landlock/Seatbelt 沙箱）和性能（~50ms 启动）
2. AGENTS.md 是"让 AI 理解你项目"的关键，类似 Claude Code 的 CLAUDE.md
3. 沙箱三种模式：read-only（最安全）、workspace-write（推荐）、danger-full-access（危险）
4. MCP 工具集成让 AI 能连接 GitHub、数据库、文件系统……
5. 移动端远程操控（2026.5）让你可以随时随地 coding
6. Sites 部署（2026.6）让 AI 不仅能写代码，还能直接上线
7. Annotations 精细修改（2026.6）让 AI 的修改更可控（不用每次都重新生成整个文件）
8. 额度收紧（2026.6）是痛点，建议优化 Token 消耗或转向本地模型

19.2 行动清单（Checklist）

立即行动：

• 安装 Codex CLI：brew install --cask codex 或 npm i -g @openai/codex
• 完成认证：codex login
• 创建你的第一个 AGENTS.md（参考第 5 章模板）

本周内：

• 在你当前项目中试用 Codex CLI（重构一个小模块）
• 配置 MCP Servers（GitHub + 数据库）
• 阅读官方文档：https://developers.openai.com/codex

本月内：

• 把 Codex CLI 接入你的 CI/CD（自动代码审查）
• 尝试移动端远程操控（下载 ChatGPT App）
• 写一个自定义插件（分享到社区）

长期：

• 关注 Codex 更新（每月都有大版本）
• 参与开源社区（github.com/openai/codex-cli）
• 思考：AI 编程助手如何改变你的工作方式？

附录 A：常用命令速查表

# 安装
brew install --cask codex              # macOS (Homebrew)
npm install -g @openai/codex          # 跨平台 (npm)

# 认证
codex login                            # 交互式登录
codex --api-key-mode                   # API Key 模式

# 启动
codex                                  # 交互模式
codex --non-interactive --task "..."   # 非交互模式（适合脚本）

# 沙箱
codex --sandbox=read-only              # 只读模式
codex --sandbox=workspace-write        # 工作区可写（推荐）
codex --sandbox=danger-full-access     # 完全访问（不安全）

# 权限审批
codex --ask-for-approval=untrusted     # 每次都问（最安全）
codex --ask-for-approval=on-failure    # 失败时问（推荐）
codex --ask-for-approval=never         # 永远不问（危险）

# 上下文管理
/compact                               # 手动压缩上下文
/context                               # 查看当前上下文统计

# MCP 工具
codex mcp list                         # 列出已配置的 MCP Servers
codex mcp add <name> <command>         # 添加 MCP Server

# 插件
codex plugin list                      # 列出已安装插件
codex plugin install <name>             # 安装插件
codex plugin create <name>              # 创建自定义插件

# 远程访问（移动端）
codex remote enable                    # 启用远程访问
codex remote disable                   # 禁用远程访问
codex remote status                    # 查看远程访问状态

# Sites 部署
codex sites deploy --name my-site      # 部署当前目录到 Sites
codex sites list                       # 列出已部署的 Sites
codex sites delete <name>              # 删除 Site

# 调试
codex --debug                          # 启用调试日志
codex --version                        # 查看版本
codex doctor                           # 诊断环境问题

附录 B：配置文件模板

~/.codex/config.toml（全局配置）：

# OpenAI API 配置
[api]
base_url = "https://api.openai.com/v1"
model = "gpt-5"
timeout_secs = 120

# 认证
[auth]
# 方式 1：login 后自动生成 auth.json（推荐）
# 方式 2：明文 API Key（不推荐）
# api_key = "sk-..."

# 沙箱配置
[sandbox]
mode = "workspace-write"
ask_for_approval = "on-failure"

# 上下文管理
[context]
max_tokens = 128000
compact_strategy = "auto"  # auto/manual/off

# 工具调用
[tools]
max_concurrent_calls = 3
timeout_secs = 60

# 日志
[logging]
level = "info"  # debug/info/warn/error
file = "~/.codex/logs/codex.log"

# 网络代理
[proxy]
https = "http://proxy.company.com:8080"
http = "http://proxy.company.com:8080"

# Hooks
[hooks]
pre_tool_call = "~/.codex/hooks/pre_tool_call.sh"
post_tool_call = "~/.codex/hooks/post_tool_call.sh"
on_error = "~/.codex/hooks/on_error.sh"

.codexignore（项目根目录，类似 .gitignore）：

# 忽略日志文件
*.log
*.log.*

# 忽略临时文件
*.tmp
*.temp
.env
.env.local

# 忽略依赖
node_modules/
vendor/
venv/

# 忽略构建产物
dist/
build/
*.min.js
*.min.css

# 忽略测试覆盖率报告
coverage/
*.coverage

# 忽略 IDE 配置
.vscode/
.idea/
*.swp
*.swo

附录 C：错误信息速查表

参考文献与延伸阅读

1. OpenAI 官方文档：https://developers.openai.com/codex
2. Codex CLI GitHub 仓库：https://github.com/openai/codex-cli
3. Landlock LSM 文档：https://www.kernel.org/doc/html/latest/userspace-api/landlock.html
4. MCP 协议规范：https://modelcontextprotocol.io
5. Rust async/await book：https://rust-lang.github.io/async-book/
6. Anthropic Claude Code 文档（对比学习）：https://docs.anthropic.com/claude-code
7. OpenAI API 额度政策（2026 年 6 月更新）：https://openai.com/api/pricing

作者信息

作者简介：程序员茄子社区（chenxutan.com）——专注深度技术实战指南，每周更新 AI 编程、系统架构、云原生等领域的前沿实战内容。

版权声明：本文采用 CC BY-NC-SA 4.0 协议授权，转载请注明出处。

更新日期：2026 年 6 月 9 日

全文完。希望这篇 15000+ 字的深度实战指南能帮你全面掌握 OpenAI Codex CLI。如果你有任何问题，欢迎在评论区留言，我会尽量回复。Happy coding! 🚀