# Codex CLI — 原始搜索结果

> 本文档为原始资料提取，未做任何精炼或总结。
> 提取来源: `/media/zhengjie/WORKSPACE/003/ant-backups/knowledge-base/工具篇/OPENAI-CODEX-COMPLETE-REFERENCE.md`
> 该来源资料组成: OpenAI官方文档 + freeCodeCamp Handbook + 技术博客
> 抓取日期: 2026-06-06

---

## 1. 版本与基本信息

- **产品名称**: OpenAI Codex
- **类型**: AI编程agent（终端原生AI编程助手）
- **核心语言**: Rust (95.7%)，从TypeScript完全重写
- **开源许可证**: Apache 2.0
- **GitHub Stars**: 67,000+ (2026年)
- **每周活跃用户**: 300万+ (2026-04数据)
- **版本**: Codex CLI v0.133.0 (GA)
- **最新模型**: GPT-5.5 (2026-04-23发布)

### 与传统工具的区别

| | Codex | GitHub Copilot | ChatGPT |
|:--|:------|:---------------|:--------|
| 类型 | AI编程Agent | 代码补全 | 通用助手 |
| 能力 | 读全库/改多文件/跑命令 | 行级补全/内联建议 | 对话/分析 |
| 执行 | 自主执行+审批 | 建议为主 | 不执行 |
| 范围 | 终端/IDE/云/桌面 | VS Code | 浏览器 |

---

## 2. 架构概览

```
用户交互层
├── Codex CLI (终端原生, Rust)
├── Codex IDE扩展 (VS Code / Cursor / Windsurf)
├── Codex 桌面应用 (macOS / Windows)
├── Codex Cloud (云端沙箱, 后台运行)
└── Codex Review (GitHub PR审查)

核心引擎
├── 代码理解 (完整repo上下文)
│   ├── 目录树分析
│   ├── 跨文件关系追踪
│   └── 依赖图理解
├── 执行引擎
│   ├── 沙箱隔离 (macOS Seatbelt / Linux Landlock)
│   ├── 文件修改 (多文件协调)
│   ├── Shell命令执行
│   └── 测试自动运行
├── 安全层
│   ├── 三种审批模式
│   ├── 沙箱隔离
│   └── 网络控制
└── 扩展层
    ├── MCP服务器
    ├── 90+插件
    ├── AGENTS.md
    └── Skills

模型层
├── GPT-5.5 (旗舰, 2026-04)
├── GPT-5.4 (性价比)
├── GPT-5.3-Codex (编码优化)
└── o4-mini / o3 (推理)

基础设施
├── ChatGPT账号 (Plus/Pro)
├── GitHub集成
└── OpenAI API (可选)
```

---

## 3. 安装指南

### 环境要求

| 要求 | 说明 |
|:-----|:------|
| Node.js 22+ | npm安装需要 |
| OS | macOS / Linux (一等支持), Windows需WSL2 |
| RAM | 4GB最小, 8GB推荐 |
| 磁盘 | ~50MB (npm包) |

### 安装方式A: npm (推荐)

```bash
CODEX_VERSION=$(npm view @openai/codex version)
echo "Installing @openai/codex@${CODEX_VERSION}"
npm install -g "@openai/codex@${CODEX_VERSION}"
codex --version
```

### 安装方式B: 二进制下载

```bash
# Linux x86_64
curl -LO https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz
tar xzf codex-x86_64-unknown-linux-musl.tar.gz
sudo mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
```

| 平台 | 文件 |
|:-----|:-----|
| macOS Apple Silicon | `codex-aarch64-apple-darwin.tar.gz` |
| macOS Intel | `codex-x86_64-apple-darwin.tar.gz` |
| Linux x86_64 | `codex-x86_64-unknown-linux-musl.tar.gz` |
| Linux arm64 | `codex-aarch64-unknown-linux-musl.tar.gz` |

### 安装方式C: Homebrew (macOS)

```bash
brew install --cask codex
```

### 首次启动

```bash
cd /你的/项目目录
codex
```
首次运行自动弹出浏览器窗口，要求登录ChatGPT账号。

---

## 4. 登录与认证

### 方式A: ChatGPT账号登录 (推荐, 不需API Key)

Codex 包含在以下套餐中:
- **ChatGPT Plus** ($20/月) — 入门
- **ChatGPT Pro** ($100/$200/月) — 更高用量
- **Business / Edu / Enterprise** — 团队版

首次运行会自动触发OAuth登录流程。

### 方式B: OpenAI API Key

```bash
export OPENAI_API_KEY="sk-你的key"
```

**安全提示**: 不要把API Key写进shell配置文件中。推荐用 `read -rs` 交互式输入:

```bash
read -rs OPENAI_API_KEY && export OPENAI_API_KEY
echo "Key set (length: ${#OPENAI_API_KEY})"
```

---

## 5. 支持模型

### 当前可用模型列表

| 模型 | 用途 | 说明 |
|:-----|:------|:------|
| **GPT-5.5** (最新旗舰) | 通用编码 | 2026-04-23发布, MRCR v2@1M达74.0% |
| **GPT-5.5 Pro** | 高要求任务 | 更高精度, 2x成本 |
| **GPT-5.4** | 性价比之选 | Computer Use标准配备 |
| **GPT-5.3-Codex** | 编码优化 | 长时间编码任务专用 |
| **GPT-5.3-Codex-Spark** | 快速编辑 | Research Preview，15倍速度 |
| **o4-mini** (默认) | 日常编码 | 速度快、成本低 |
| **o3** | 复杂重构 | 深度推理 |

### 运行时切换

```
# Codex CLI 中
/model gpt-5.5
/model o3
/model o4-mini
```

### 已退役模型

| 模型 | 状态 |
|:-----|:------|
| GPT-5-Codex | 不再默认 |
| GPT-5.1-Codex | 不再默认 |
| GPT-5.2-Codex | 不再默认 |

---

## 6. 安全模式与权限

### 三种模式

| 模式 | 命令 | 行为 | 适用场景 |
|:-----|:------|:------|:---------|
| **Suggest** (默认) | `codex` | 所有操作先提议, 等你确认 | 生产代码/新手 |
| **Auto-Edit** | `codex --approval-policy on-failure` | 自动编辑文件, Shell命令需要确认 | 日常开发 |
| **Full Access** | `codex -y` | 全部自动执行, 仅拒绝时干预 | 可信任务/CI |

### 沙箱隔离

- **macOS**: Seatbelt 沙箱
- **Linux**: Landlock LSM
- 隔离文件访问、网络访问、进程创建

### 审批策略配置

```bash
codex --approval-policy on-failure    # 仅在失败时审批
codex -y                              # 全自动模式 (yolo)
codex --no-sandbox                    # 关闭沙箱 (危险!)
```

---

## 7. 核心功能

### 多文件编辑

Codex 理解项目结构，能一次性协调多个文件的修改：
- 重命名函数 → 更新所有调用处 → 调整测试
- 架构重构 → 迁移代码 → 删除旧文件

### Shell 命令执行

```bash
codex "运行测试并修复失败用例"
```
Codex 会自动运行 `pytest` / `npm test` 等命令，读取输出，迭代修复。

### 图片输入

```bash
codex "根据这张UI设计图实现组件" --image mockup.png
```
支持截图、线框图、图表等图片输入。

### Pipe 友好

```bash
git diff | codex "审查这些改动"
cat error.log | codex "分析错误原因"
```

### 会话持久化

```bash
codex resume --last          # 恢复上次会话
codex resume <SESSION_ID>    # 恢复指定会话
```

### Headless模式 (CI/CD)

```bash
codex exec "修复所有lint错误" --cwd /path/to/repo
```

### 后台任务

```bash
codex --background "运行测试套件并在完成时通知"
```

### 快捷键 (TUI)

| 按键 | 功能 |
|:-----|:------|
| `Enter` | 发送消息 |
| `Meta+Enter` | 换行 |
| `Ctrl+C` | 中断运行 |
| `Tab` | 自动补全 |
| `↑/↓` | 浏览历史 |
| `Ctrl+L` | 清屏 |
| `/model` | 切换模型 |
| `/review` | 代码审查 |
| `/clear` | 清除上下文 |

---

## 8. Codex Cloud

### 概述

Codex Cloud 是后台执行模式，每个任务在**隔离沙箱容器**中运行，有完整的仓库和环境。

### 使用场景

- **长时间任务**: 提交后关电脑, 醒来查看结果
- **大重构**: 跨多文件的架构变更
- **自动化流水线**: GitHub PR触发自动修复

### 命令

```bash
# 从CLI提交云任务
codex cloud submit "为所有API端点添加错误处理"

# 查看云任务状态
codex cloud status

# 查看结果
codex cloud view <task-id>
```

### 套餐限额

| 套餐 | 云端任务/5h |
|:-----|:-----------|
| Plus | 10-60 |
| Pro $100 | 50-200 |
| Pro $200 | 50-400 |

---

## 9. Codex IDE 扩展

### 安装

```bash
# VS Code
code --install-extension openai.chatgpt
```

支持编辑器: **VS Code**, **Cursor**, **Windsurf**

### 功能

- 编辑器内直接对话
- 选中代码 → Codex解释/修改
- 内联建议
- 与CLI共享同一会话

---

## 10. Codex 桌面应用

### 平台

- **macOS**: 完整功能, 含Computer Use
- **Windows**: 2026-03-04发布, 含Git Worktree并行任务

### 特色功能

| 功能 | 说明 |
|:-----|:------|
| **并行Agent** | 多个Codex同时工作 |
| **Git Worktree** | 每个任务独立工作区 |
| **Computer Use** | macOS上直接操作其他App |
| **图像生成** | gpt-image-1.5 生成UI mockup |
| **内存** | 记住个人偏好和修正习惯 |
| **应用内浏览器** | 直接加载页面分析 |

### Computer Use

Codex 能直接操作桌面应用——点击按钮、输入文字、截屏分析。适用于:
- GUI自动化测试
- 只有界面的工具配置
- 设计稿→代码的端到端流程

---

## 11. 代码审查

### CLI审查

```bash
# 审查未提交的改动
codex exec "审查当前改动"

# 审查特定分支
codex exec "审查 main..feature-x 的diff"

# 审查指定commit
codex exec "审查 commit abc123"
```

### 内置 `/review` 命令

```
/review                 # 审查当前diff
/review --base main     # 对比main分支
```

### GitHub PR自动审查 (Cloud)

GitHub上配置后，每次PR自动触发Codex审查：

1. 安装 GitHub Codex App
2. 配置审查规则
3. Codex 自动在PR上评论审查意见

---

## 12. AGENTS.md 项目适配

### 使用方式

在项目根目录创建 `AGENTS.md`，Codex会自动读取并遵循其中的规则。

```markdown
# My Project — Codex Instructions

## 编码规范
- 使用 TypeScript strict 模式
- 使用 pnpm, 不用 npm 或 yarn
- 测试覆盖率不低于 80%

## 项目结构
- src/ — TypeScript 源码
- tests/ — Jest 测试
- infra/ — Terraform 部署

## 部署
- PR 合入 main 自动部署 staging
- 打好 tag 才部署 production
```

### 搜索顺序

Codex 会**从当前目录向上递归搜索**，找到的 AGENTS.md 全部注入上下文。

### 与Memory的区别

| | AGENTS.md | Memory |
|:--|:----------|:-------|
| 范围 | 项目级别 | 个人/会话级别 |
| 内容 | 显式规则 | 隐式学习 |
| 分享 | 可提交到Git | 本地私有 |

---

## 13. MCP 集成

### 协议支持

- **STDIO**: 本地子进程
- **HTTP**: 远程MCP服务器

### 配置示例

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}
```

### 可连接的MCP工具

| 服务器 | 功能 |
|:-------|:------|
| Filesystem | 文件读写 |
| GitHub | Issues/PR管理 |
| Postgres | 数据库查询 |
| Brave Search | Web搜索 |
| Puppeteer | 浏览器自动化 |
| Slack | 工作区操作 |

---

## 14. 插件系统 (90+)

### 插件分类

| 类别 | 示例 |
|:-----|:------|
| **监控** | Sentry, Datadog, New Relic |
| **项目管理** | Linear, Jira, Asana, Notion |
| **通信** | Slack, Discord |
| **云服务** | AWS, GCP, Azure |
| **代码质量** | SonarQube, CodeClimate |
| **安全** | Snyk, Dependabot |

### 自动触发

GitHub Issue/PR 事件可自动触发 Codex:

```yaml
# .github/workflows/codex.yml
on:
  pull_request:
    types: [opened]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: openai/codex-review@v1
```

### 安全Agent

插件体系中包含安全agent，可自动扫描：
- 依赖漏洞
- 密钥泄露
- 代码注入风险

---

## 15. 定价与套餐

### 套餐总览 (2026-04更新)

| 套餐 | 月费 | Codex访问 | 本地消息/5h | 云端任务/5h | 代码审查/周 |
|:-----|:-----|:----------|:-----------|:-----------|:-----------|
| **Free** | $0 | 有限(Promo) | 有限 | — | — |
| **Go** | ~$8 | 有限 | 有限 | — | — |
| **Plus** | **$20** | ✅ 完整 | 45-225 | 10-60 | 10-25 |
| **Pro $100** | $100 | ✅ +优先 | 225-750 | 50-200 | 50-125 |
| **Pro $200** | $200 | ✅ +优先 | 300-1500 | 50-400 | 100-250 |
| **Business** | $25/人 | ✅ +管理 | 同Plus | 同Plus | 同Plus |
| **Enterprise** | 定制 | ✅ 无限 | 积分池 | 积分池 | 协商 |

### 5小时滚动窗口

关键机制：**不是按月重置，而是5小时滚动窗口**。
- 窗口从第一条消息开始计时
- 5小时后重置
- 用完额度后需等重置或购买额外积分
- 本地和云端任务**分别计费**

### 2x 速率提升 (截止2026-03)

Plus和Pro用户享有2x速率提升Promo，上表的"上限"已包含此优惠。

### API按量计费 (替代方案)

| 模型 | 输入价格 | 输出价格 |
|:-----|:---------|:---------|
| GPT-5.5 | ~$15/M tokens | ~$60/M tokens |
| GPT-5.4 | ~$10/M tokens | ~$40/M tokens |
| GPT-5.3-Codex | ~$12/M tokens | ~$50/M tokens |
| o4-mini | ~$1.10/M tokens | ~$4.40/M tokens |

---

## 16. 模型规格与基准

### GPT-5.5 (最新旗舰)

| 指标 | 分数 |
|:-----|:-----|
| Terminal-Bench 2.0 | 82.7% |
| MRCR v2 @ 1M tokens | 74.0% |
| 相比GPT-5.4提升 | 幻觉率下降60% |
| 成本 | 约GPT-5.4的2倍 |

### GPT-5.3-Codex (编码专用)

| 特性 | 说明 |
|:-----|:------|
| 优化目标 | 长时间编码任务 |
| 适用场景 | 复杂重构/多文件修改 |
| 可用性 | Plus及以上套餐 |

### 选型建议

| 任务类型 | 推荐模型 |
|:---------|:---------|
| 日常编码/小修改 | o4-mini (默认) |
| 普通功能开发 | GPT-5.4 |
| 复杂重构/架构变更 | GPT-5.3-Codex |
| 最高质量要求 | GPT-5.5 |

---

## 17. 安全与企业设置

### 数据安全

| 设置 | 说明 |
|:-----|:------|
| 沙箱隔离 | macOS Seatbelt / Linux Landlock |
| 本地执行 | 代码不离开本机 |
| 网络控制 | 可限制网络访问 |
| 日志 | 脱敏处理 |

### 企业功能

| 功能 | Business | Enterprise |
|:-----|:---------|:-----------|
| SAML SSO | ✅ | ✅ |
| MFA | ✅ | ✅ |
| RBAC | — | ✅ |
| SCIM | — | ✅ |
| EKM (加密密钥管理) | — | ✅ |
| 审计日志 | — | ✅ |
| 数据不用于训练 | ✅ | ✅ |

### 用户白名单

| 环境 | 配置 |
|:-----|:------|
| CLI | 本机, 无白名单概念 |
| 团队 | Business/Enterprise Workspace 控制 |

### 最佳实践

1. **个人开发**: Plus套餐 + Suggest模式
2. **团队开发**: Business套餐 + Auto-Edit模式
3. **CI/CD**: API Key + Full Access模式 (沙箱内)

---

## 18. 故障排查

### 常见问题

| 症状 | 原因 | 解决 |
|:-----|:------|:------|
| 安装失败 | Node.js版本低 | `node --version` 确认≥22 |
| 认证失败 | Token过期 | 重新登录: `codex logout && codex` |
| 额度用完 | 5h窗口耗尽 | 等窗口重置, 或升级套餐 |
| 沙箱拒绝 | 文件不在项目目录 | 将文件移入项目目录 |
| 模型不可用 | 套餐不支持 | 检查Plus/Pro模型列表 |
| AGENTS.md无效 | 文件名错误 | 必须是 `AGENTS.md` |

### 检查链

```bash
# 1. 版本
codex --version

# 2. 认证状态
codex whoami

# 3. 检查配置
codex config show

# 4. 查看日志
tail -f ~/.codex/logs/*.log

# 5. 恢复上次会话
codex resume --last
```

### Windows用户注意事项

- **必须使用 WSL2**
- Node.js 22+ 装在 WSL2 内，不是 Windows 宿主机
- 原生 Windows 不支持（实验性）

---

## 19. 竞品对比

| 对比项 | Codex (OpenAI) | Claude Code (Anthropic) | Cursor | GitHub Copilot |
|:-------|:---------------|:-----------------------|:-------|:--------------|
| **月费** | Plus $20起 | Pro $20起 | Pro $20起 | Pro $10起 |
| **使用形态** | CLI/IDE/Cloud/桌面 | CLI/Web/IDE | 独立IDE | IDE插件 |
| **模型** | GPT-5.x/o4-mini/o3 | Claude Sonnet/Opus | 多模型可选 | GPT-4o/Claude |
| **开源** | ✅ (Rust) | ❌ | ❌ | ❌ |
| **沙箱** | ✅ Seatbelt/Landlock | ❌ | ❌ | ❌ |
| **云任务** | ✅ Codex Cloud | ❌ | ❌ | ❌ |
| **代码审查** | ✅ 内置 | ✅ 手动 | ❌ | ❌ |
| **多Agent** | ✅ 实验性 | ✅ Task工具 | ❌ | ❌ |
| **AGENTS.md** | ✅ | ✅ (CLAUDE.md) | ✅ .cursorrules | ❌ |
| **MCP** | ✅ | ✅ | ❌ | ❌ |
| **会话恢复** | ✅ | ✅ | ❌ | ❌ |
| **基准(Term-Bench)** | 77.3-82.7% | ~75% | — | — |

---

## 20. Ant Empire 5号服务器部署方案

### 为什么选5号

| 优势 | 说明 |
|:-----|:------|
| **海外直连** | 不受GFW限制, API延迟最低 |
| **24小时在线** | VPS持续运行, 可跑Codex Cloud任务 |
| **已有AI图书馆** | `/data/ai-library/` 可直接作为Codex工作区 |
| **Node.js环境** | 5号可直接npm安装 |

### 推荐套餐

**ChatGPT Plus ($20/月)** — 够用:
- 45-225消息/5h (本地编码)
- 10-60云端任务/5h (后台重构)
- 10-25代码审查/周

### 安装脚本

```bash
# SSH 到5号
ssh 5hao

# 安装 Codex CLI
npm install -g @openai/codex

# 验证
codex --version

# 首次登录 (需要交互式)
codex
# 会打印登录链接, 在浏览器打开完成OAuth
```

### 三种工作模式

#### 模式A: 交互式CLI (人工使用)

```bash
ssh 5hao
cd /data/ai-library/code-backup
codex "分析这个目录的代码结构"
```

#### 模式B: Headless CI (脚本触发)

```bash
# 在2号/4号触发5号的Codex任务
ssh 5hao 'cd /data/ai-library && codex exec "审查最近的代码变更"'
```

#### 模式C: Webhook接收 (蚂蚁投递)

```
5号服务器:
└── Webhook端口 (:18792) ← 接收2号/4号投递的编码任务
    └── codex exec "任务描述"
        └── 结果 → 回传到飞书
```

### 使用场景优先级

| 优先级 | 场景 | 频率 | 价值 |
|:-------|:------|:------|:------|
| ⭐⭐⭐⭐⭐ | AI图书馆代码分析与维护 | 每日 | 高 |
| ⭐⭐⭐⭐ | 蚂蚁军团代码审查 | 每次部署 | 高 |
| ⭐⭐⭐⭐ | 商城bug修复 (4号) | 按需 | 高 |
| ⭐⭐⭐ | 股票数据分析脚本生成 | 每周 | 中 |
| ⭐⭐⭐ | 自动化测试编写 | 持续 | 中 |

### 与Hermes的分工

| 工具 | 最适合 |
|:-----|:--------|
| **Hermes (小七/糖糖/蚁后)** | 服务器管理、金融数据、消息网关、日常对话 |
| **Codex (5号)** | 编程任务、代码审查、重构、测试编写 |

```
蚂蚁军团 + Codex 协作流程:

           ┌─────────────────┐
           │  郑杰 (你)       │
           └──────┬──────────┘
                  │
     ┌────────────┼────────────┐
     ▼            ▼            ▼
  ┌──────┐   ┌──────┐   ┌──────────┐
  │ 小七  │   │ 糖糖  │   │ 蚁后     │
  │(本机) │   │(2号)  │   │(4号)     │
  └──┬───┘   └──┬───┘   └────┬─────┘
     │          │             │
     └──────────┼─────────────┘
                │ 投递编码任务 (SSH/Webhook)
                ▼
          ┌──────────┐
          │ Codex     │ ← 5号服务器, ChatGPT Plus
          │ (编程工厂) │     npm install -g @openai/codex
          └──────────┘
                │
                ▼
          ┌──────────┐
          │ AI图书馆   │
          │ /data/ai-  │
          │ library/   │
          └──────────┘
```

---

## 数据来源标注

本文档所有原始信息提取自:

1. **OPENAI-CODEX-COMPLETE-REFERENCE.md** (位于 `/media/zhengjie/WORKSPACE/003/ant-backups/knowledge-base/工具篇/`)
   - 该文档的资料来源:
     - OpenAI Codex 官方文档
     - freeCodeCamp "The Codex Handbook" (v1.3, 2026-04-30)
     - 多家技术媒体评测
   - 抓取日期: 2026-06-06
   - 版本: Codex CLI v0.133.0 (GA)
   - 最新模型: GPT-5.5 (2026-04-23发布)

2. 本文档是上述原始资料的**完全提取**，不包含任何额外的总结、精炼或外部信息补充。