OpenAI Codex CLI 完全指南：AI 编程助手的终端革命

前言

2025年，AI 编程工具迎来了爆发式增长。OpenAI 推出的 Codex CLI 将你的终端转变为 AI 驱动的编码助手，可以通过自然语言读取、修改和执行代码。本文将带你全面了解 Codex CLI 的安装、配置和使用方法。

---

一、什么是 Codex CLI？

Codex CLI 是 OpenAI 开发的本地运行的编码代理工具，它结合了 ChatGPT 级别的推理能力和本地代码执行能力。

核心特点

特性	说明
🚀 本地运行	直接在你的电脑上运行，保护代码隐私
🔧 开源免费	Apache 2.0 许可，使用 Rust 构建
🌍 跨平台	支持 macOS、Linux 和 Windows（WSL2）
🔌 MCP 支持	可连接 Model Context Protocol 服务器
💡 多种模式	suggest、auto-edit、full-auto 三种操作模式

---

二、安装要求

系统要求

• 操作系统：macOS、Linux（Windows 需通过 WSL2）
• Node.js：v22 或更高版本
• 网络：需要能够访问 OpenAI API

检查 Node.js 版本

node --version
# 输出应 >= v22.0.0

如果版本过低，请先升级 Node.js：

# 使用 nvm 升级（推荐）
nvm install 22
nvm use 22

---

三、安装方法

方式一：npm 全局安装（推荐）

npm install -g @openai/codex

方式二：Homebrew 安装（macOS/Linux）

brew install --cask codex

方式三：下载二进制文件

访问 GitHub Releases 下载对应平台的二进制文件：

平台	文件名
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

验证安装

codex --version

---

四、认证配置

方式一：ChatGPT 账号登录（推荐）

运行 codex 后选择 Sign in with ChatGPT，支持以下计划：

• ✅ ChatGPT Plus
• ✅ ChatGPT Pro
• ✅ ChatGPT Team
• ✅ ChatGPT Edu
• ✅ ChatGPT Enterprise

💡 福利：Plus 用户可获得 5 美元免费 API 额度，Pro 用户可获得 50 美元免费 API 额度（30天内有效）

方式二：API Key 配置

# Linux/macOS
export OPENAI_API_KEY="sk-your-api-key-here"

# Windows PowerShell
$env:OPENAI_API_KEY="sk-your-api-key-here"

永久配置（添加到 ~/.bashrc 或 ~/.zshrc）：

echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

---

五、基本使用

启动交互模式

codex

直接提问模式

codex "解释这个项目的结构"
codex "找出所有的 TODO 注释"
codex "帮我写一个单元测试"

三种操作模式

模式	说明	自主程度
suggest	建议模式，只提供建议不执行	🔒 最安全
auto-edit	自动编辑，但执行需确认	⚖️ 平衡
full-auto	全自动模式，自动执行所有操作	🚀 最快

# 使用指定模式
codex -a suggest "重构这个函数"
codex -a auto-edit "添加错误处理"
codex -a full-auto "运行测试并修复错误"

---

六、常用命令和参数

命令行参数

codex [options] [prompt]

选项：
  -m, --model <model>        指定使用的模型
  -a, --approval-mode <mode> 设置操作模式 (suggest/auto-edit/full-auto)
  -q, --quiet                安静模式，减少输出
  --profile <name>           使用指定的配置文件

实用示例

# 代码审查
codex "审查最近的代码更改并提供改进建议"

# 生成文档
codex "为这个项目生成 README 文档"

# Debug 帮助
codex "这个函数为什么会返回 null？"

# 重构代码
codex "将这个类重构为更小的模块"

---

七、配置文件

Codex CLI 的配置存储在 ~/.codex/config.toml：

# 默认模型
model = "o4-mini"

# 默认操作模式
approval_mode = "auto-edit"

# 启用 MCP 服务器
[mcp_servers]
github = { command = "npx", args = ["-y", "@modelcontextprotocol/server-github"] }

---

八、MCP 服务器集成

Codex 支持 Model Context Protocol (MCP)，可以连接外部工具：

# ~/.codex/config.toml
[mcp_servers]
# GitHub 集成
github = { command = "npx", args = ["-y", "@modelcontextprotocol/server-github"] }

# 数据库集成
postgres = { command = "npx", args = ["-y", "@modelcontextprotocol/server-postgres"] }

---

九、IDE 集成

除了命令行，Codex 还支持主流 IDE：

• VS Code：安装 Codex 扩展
• Cursor：内置支持
• Windsurf：内置支持

---

十、常见问题

Q1: 安装后运行报错 “command not found”

解决方案：确保 npm 全局安装目录在 PATH 中

npm config get prefix
# 将输出的路径/bin 添加到 PATH

Q2: Node 版本过低

解决方案：升级到 Node.js 22+

nvm install 22
nvm use 22

Q3: API Key 无效

解决方案：检查 API Key 是否正确设置

echo $OPENAI_API_KEY

Q4: Homebrew 升级失败

解决方案：

brew uninstall --cask codex
brew install --cask codex

---

十一、最新动态

OpenAI 于 2025 年 12 月推出了 GPT-5.1-Codex-Max，这是专门为编码任务优化的新模型：

• ✅ 更快的响应速度
• ✅ 更好的代码理解能力
• ✅ 首个支持 Windows 环境训练的模型
• ✅ 支持 CLI、IDE 扩展和云端使用

---

总结

Codex CLI 是一个强大的 AI 编程助手，它让你可以在终端中通过自然语言与代码进行交互。无论是代码审查、重构、调试还是生成文档，Codex CLI 都能大大提高你的开发效率。

快速开始三步走

1. 安装：npm install -g @openai/codex
2. 配置：登录 ChatGPT 账号或设置 API Key
3. 使用：运行 codex 开始对话

---

参考资源

• Codex CLI 官方文档
• GitHub 仓库
• OpenAI Codex 介绍

---

作者简介：一名正在实习的Java开发工程师，热爱技术分享，专注于性能优化和系统架构设计。

觉得有用的话可以点点赞 (/ω＼)，支持一下。

如果愿意的话关注一下。会对你有更多的帮助。

每周都会不定时更新哦 >人< 。

版权声明：本文为原创技术文章，转载请注明出处。