OpenAI Codex 安装与使用指南

Codex CLI 是 OpenAI 的终端编程智能体，在本地 Shell 中理解代码库、生成补丁、执行命令。适合 ChatGPT 订阅用户、Node/monorepo 维护者与无 IDE 的自动化场景。

产品概览

安装步骤

方式一：独立安装脚本（推荐，无需 Node.js）

macOS / Linux：

# 官方独立安装器（自动加入 PATH）
curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell：

irm https://chatgpt.com/codex/install.ps1 | iex

方式二：npm

# 需 Node.js 18+（推荐 22）
# 注意：包名是 @openai/codex，不是 codex
npm install -g @openai/codex

勿安装无 scope 的 codex 包，那是无关的旧项目。

方式三：Homebrew（macOS）

brew install --cask codex

方式四：GitHub Releases 二进制

从 Releases 下载对应平台包：

解压后将二进制重命名为 codex 并加入 PATH。

验证与登录

# 检查版本
codex --version

# 启动并登录
codex

首次启动选择 Sign in with ChatGPT（推荐，含于 Plus/Pro 等计划），或配置 OPENAI_API_KEY 使用 API 计费模式。

# API Key 方式（可选）
export OPENAI_API_KEY="your-key-here"
codex

快速冒烟测试

cd your-project
codex "列出这个项目的主要目录和文件"

若正确列出文件，说明认证与沙箱均正常。

核心用法

交互模式

# 进入项目目录启动 Agent
cd ~/my-monorepo
codex

用自然语言描述任务，Codex 会：

1. 阅读相关文件
2. 通过 apply_patch 等工具生成修改
3. 在沙箱中执行命令（如跑测试）
4. 展示 diff 供你确认

常用参数与命令

示例：自动修测试

codex --full-auto "运行测试并修复所有失败用例"

MCP 并行调用

Codex 作为 MCP 客户端，可连接文档服务、测试 Runner 等 Server，并支持并行工具调用，缩短多步任务耗时。

IDE 集成

若需在 VS Code / Cursor / Windsurf 中使用，可安装对应 IDE 扩展；本专栏侧重 CLI 终端场景。

沙箱与安全

• 默认在受限沙箱中执行，限制随意写盘与网络
• 改动前 Review diff，避免误删配置
• Windows 沙箱基于 AppContainer，官方标注仍为实验特性
• 推荐在 WSL2 中运行以获得更完整 Linux 体验

实战示例

Monorepo 跨包重构

将 packages/shared/src/logger.ts 中的 logInfo 重命名为 logDebug，
更新 monorepo 内所有 import，并运行各包的单元测试。

生成带注释的工具函数

在 src/utils/geo.ts 添加函数 haversineDistance：
- 参数为两点的经纬度（度）
- 返回球面距离（米）
- 添加完整 JSDoc 与边界情况处理

CI 集成思路

# 非交互模式用于流水线（需评估安全策略）
codex exec "根据 PR diff 生成 changelog 条目"

优缺点分析

优点

缺点

Codex vs Claude Code

常见问题

延伸阅读

• 编程工具专栏总索引
• Claude Code 指南
• Cursor 指南
• 官方仓库

本文由 xueyise 创作，AI 编程工具专栏。