🚀 Codex CLI 2026中文入门：Mac/Windows安装配置全攻略

📅 更新于 2026年5月 | ✍️ 原创文章，转载请注明出处

本系列共12篇，本文是第1篇

---

---

1. 什么是Codex CLI

Codex CLI 是 OpenAI 于2025年推出的 终端原生AI编程助手，2026年5月最新版本为 v0.133.0。

与传统的IDE插件不同，它直接运行在命令行中，能够：

• 🔍 理解整个代码库 — 自动扫描项目文件，理解项目结构
• ✏️ 自主编辑文件 — 跨文件重构、批量修改、代码生成
• 🖥️ 执行终端命令 — 运行测试、安装依赖、Git操作
• 🤖 代理式编程 — 独立完成复杂任务，遇到问题会自己调试修复
• ⚡ Rust 编写 — 开源、高效、跨平台

简单说：它不是一个代码补全工具，而是一个能独立干活的AI程序员。

💡 Codex 的三个版本

版本	说明	使用方式
Codex CLI	终端版本，本地运行	本文重点介绍
Codex App	桌面应用版本	codex app 启动
Codex Web	网页版本	chatgpt.com/codex
Codex IDE	VS Code/JetBrains 扩展	IDE 内使用

---

2. 核心特性与优势

🎯 核心能力

特性	说明
终端原生	直接在CLI运行，不依赖特定IDE
全项目理解	通过 AGENTS.md 和文件扫描理解项目结构
自主执行	可独立完成多步骤任务（写代码→运行测试→修复bug）
Git集成	对话式Git操作，自动提交、创建PR
多平台支持	CLI、VS Code、JetBrains、桌面应用、Web界面
MCP协议	支持Model Context Protocol扩展能力
Skills系统	可复用的技能模块，扩展AI能力
权限控制	修改文件前会请求确认，安全可控
开源免费	Apache-2.0 许可证，代码完全开源

💪 相比传统工具的优势

传统AI补全工具：
  你写一行 → AI补全一行 → 你确认

Codex CLI：
  你说需求 → AI理解项目 → AI写完整功能 → AI跑测试 → AI修bug → 你review

🔥 与 Claude Code 的核心差异

维度	Codex CLI	Claude Code
开发商	OpenAI	Anthropic
开源	✅ 完全开源	❌ 闭源
编写语言	Rust	TypeScript
订阅方式	ChatGPT 订阅	Claude 订阅
默认模型	GPT-5-Codex	Claude Opus 4
项目配置文件	AGENTS.md	CLAUDE.md
扩展协议	MCP + Skills + Plugins	MCP + Skills

---

3. 与其他AI编程工具对比

📊 2026年主流AI编程工具对比表

工具	类型	主要模型	价格（月）	最佳场景
Codex CLI	终端CLI代理	GPT-5-Codex	ChatGPT订阅	开源项目、自主任务
Claude Code	终端CLI代理	Claude Opus 4/Sonnet 4	$20-200	复杂重构、企业项目
Cursor	AI原生IDE	多模型（Claude/GPT等）	$20	日常编码、快速迭代
GitHub Copilot	IDE插件	GPT-4o/Claude Sonnet	$10-19	代码补全、团队协作
Windsurf	AI原生IDE	多模型	$15	全栈开发
Hermes Agent	终端CLI代理	多模型可配	开源免费	个人助手、多平台
OpenClaw	CLI/Web多代理	多模型可配	开源免费	多代理协作

🤔 如何选择？

你的需求	推荐工具
开源优先、喜欢折腾	Codex CLI
复杂项目重构、跨文件修改	Claude Code
日常写代码、快速迭代	Cursor
代码补全、团队协作	GitHub Copilot
多模型切换、个人助手	Hermes Agent

---

4. 系统要求

💻 操作系统

系统	最低版本	推荐版本
macOS	11 (Big Sur)	14 (Sonoma) 或更高
Windows	Windows 10	Windows 11
Linux	Ubuntu 20.04 / Debian 10	Ubuntu 22.04 或更高

🔧 依赖环境

依赖	必需	说明
Node.js	✅	18.x 或更高版本
npm	✅	随 Node.js 安装
Git	✅	2.x 或更高版本
Rust	❌	仅从源码编译时需要

💰 订阅要求

使用 Codex CLI 需要以下任一方式：

1. ChatGPT 订阅（推荐）

   • Plus: $20/月
   • Pro: $200/月
   • Business: $25/用户/月
   • Enterprise: 联系销售

2. OpenAI API Key

   • 按量付费
   • 需要额外配置

---

5. Mac安装配置

🍎 方式一：一键安装脚本（推荐）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

这个脚本会自动：

• 检测系统架构（Intel/Apple Silicon）
• 下载对应版本
• 安装到 /usr/local/bin/
• 配置环境变量

🍺 方式二：Homebrew 安装

brew install --cask codex

📦 方式三：npm 安装

npm install -g @openai/codex

🔧 方式四：手动安装

1. 访问 GitHub Releases
2. 下载对应版本：
   • Apple Silicon (M1/M2/M3): codex-aarch64-apple-darwin.tar.gz
   • Intel Mac: codex-x86_64-apple-darwin.tar.gz
3. 解压并移动到 PATH 目录：

# 解压
tar -xzf codex-aarch64-apple-darwin.tar.gz

# 重命名
mv codex-aarch64-apple-darwin codex

# 移动到 /usr/local/bin/
sudo mv codex /usr/local/bin/

# 验证安装
codex --version

✅ 验证安装

# 查看版本
codex --version

# 查看帮助
codex --help

# 启动 Codex
codex

⚠️ Mac 常见问题

问题1：提示"无法打开，因为无法验证开发者"

# 解决方法：移除隔离属性
xattr -d com.apple.quarantine /usr/local/bin/codex

问题2：权限被拒绝

# 解决方法：添加执行权限
chmod +x /usr/local/bin/codex

问题3：Homebrew 安装后找不到命令

# 解决方法：添加到 PATH
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

---

6. Windows安装配置

🪟 方式一：PowerShell 安装脚本（推荐）

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

注意：需要以管理员身份运行 PowerShell

📦 方式二：npm 安装

npm install -g @openai/codex

🔧 方式三：手动安装

1. 访问 GitHub Releases
2. 下载 codex-x86_64-pc-windows-msvc.zip
3. 解压到目录，如 C:\Program Files\Codex\
4. 添加到系统 PATH：
   • 右键"此电脑" → 属性 → 高级系统设置
   • 环境变量 → 系统变量 → Path → 编辑
   • 添加 C:\Program Files\Codex\
5. 重启命令行

✅ 验证安装

# 查看版本
codex --version

# 查看帮助
codex --help

# 启动 Codex
codex

⚠️ Windows 常见问题

问题1：PowerShell 执行策略限制

# 解决方法：临时绕过执行策略
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

问题2：Windows Defender 拦截

• 打开 Windows 安全中心
• 病毒和威胁防护 → 管理设置 → 排除项
• 添加 Codex 安装目录

问题3：找不到 npm 命令

• 下载安装 Node.js（LTS 版本）
• 安装时勾选"Add to PATH"

问题4：Git 未安装

• 下载安装 Git for Windows
• 安装时选择"Use Git from the Windows Command Prompt"

---

7. Linux安装配置

🐧 方式一：一键安装脚本（推荐）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

📦 方式二：npm 安装

npm install -g @openai/codex

🔧 方式三：手动安装

1. 访问 GitHub Releases
2. 下载对应版本：
   • x86_64: codex-x86_64-unknown-linux-musl.tar.gz
   • ARM64: codex-aarch64-unknown-linux-musl.tar.gz
3. 安装：

# 解压
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz

# 重命名
mv codex-x86_64-unknown-linux-musl codex

# 移动到 /usr/local/bin/
sudo mv codex /usr/local/bin/

# 验证
codex --version

✅ 验证安装

codex --version
codex --help
codex

⚠️ Linux 常见问题

问题1：缺少依赖库

# Ubuntu/Debian
sudo apt update
sudo apt install -y libssl-dev pkg-config

# CentOS/RHEL
sudo yum install -y openssl-devel

问题2：权限问题

sudo chmod +x /usr/local/bin/codex

---

8. 首次使用与登录

🚀 启动 Codex

codex

首次启动会显示登录界面：

Welcome to Codex CLI!

? How would you like to authenticate?
  ❯ Sign in with ChatGPT (recommended)
    Enter API Key

🔐 方式一：ChatGPT 订阅登录（推荐）

1. 选择 “Sign in with ChatGPT”
2. 浏览器会自动打开 OpenAI 登录页面
3. 登录你的 ChatGPT 账号（Plus/Pro/Business/Enterprise）
4. 授权 Codex CLI 访问
5. 返回终端，登录成功

优势：

• 使用 ChatGPT 订阅额度
• 无需管理 API Key
• 自动享受模型更新

🔑 方式二：API Key 登录

1. 选择 “Enter API Key”
2. 输入你的 OpenAI API Key
3. 回车确认

获取 API Key：

1. 访问 platform.openai.com/api-keys
2. 点击 “Create new secret key”
3. 复制保存（只显示一次）

设置环境变量（可选）：

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

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

# 永久设置（添加到配置文件）
echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.bashrc
source ~/.bashrc

✅ 验证登录

# 进入项目目录
cd your-project

# 启动 Codex
codex

# 输入简单测试
> 你好，请介绍下这个项目

---

9. 定价方案详解

💰 ChatGPT 订阅方案

方案	价格	Codex 额度	适合人群
Plus	$20/月	有限额度	个人开发者
Pro	$200/月	无限额度	重度用户
Business	$25/用户/月	团队额度	小团队
Enterprise	联系销售	定制额度	大企业

📊 API 按量计费

如果不使用 ChatGPT 订阅，可以使用 API Key 按量付费：

模型	输入价格	输出价格
GPT-5-Codex	$2.50/1M tokens	$10.00/1M tokens
GPT-4o	$2.50/1M tokens	$10.00/1M tokens
GPT-4o-mini	$0.15/1M tokens	$0.60/1M tokens

💡 如何选择？

使用场景	推荐方案	月费用预估
偶尔使用、轻量任务	Plus	$20
日常开发、中等使用	Plus	$20
重度使用、全职开发	Pro	$200
团队协作	Business	$25/人
企业部署	Enterprise	定制

⚡ 省钱技巧

1. 合理使用模型：简单任务用 mini 模型
2. 控制上下文：避免发送大量无关代码
3. 使用 AGENTS.md：让 AI 快速理解项目，减少探索消耗
4. 批量处理：一次性处理多个相关任务

---

10. 基本配置优化

📁 配置文件位置

系统	路径
Mac/Linux	~/.codex/config.json
Windows	%USERPROFILE%\.codex\config.json

⚙️ 推荐配置

创建或编辑 ~/.codex/config.json：

{
  "model": "gpt-5-codex",
  "theme": "dark",
  "auto_approve": false,
  "verbose": false,
  "max_tokens": 4096,
  "temperature": 0.7
}

🎨 主题设置

# 查看当前配置
codex config list

# 设置主题
codex config set theme dark

# 可选主题：dark, light, auto

🔧 常用配置项

配置项	默认值	说明
model	gpt-5-codex	使用的模型
theme	dark	界面主题
auto_approve	false	自动批准文件修改
verbose	false	详细输出
max_tokens	4096	最大输出长度
temperature	0.7	创造性程度

📝 创建 AGENTS.md

在项目根目录创建 AGENTS.md，帮助 Codex 理解你的项目：

# Project: My Awesome App

## Overview
这是一个基于 Spring Boot 的后端服务项目。

## Tech Stack
- Java 21
- Spring Boot 3.3
- MyBatis-Plus
- MySQL
- Redis

## Commands
- Build: `mvn clean package -DskipTests`
- Test: `mvn test`
- Run: `mvn spring-boot:run`

## Conventions
- 使用中文注释
- 遵循阿里巴巴 Java 开发规范
- Controller 返回统一 ApiResponse

---

11. 常见问题解答

❓ Q1：Codex CLI 是免费的吗？

A：Codex CLI 本身是开源免费的（Apache-2.0），但使用需要：

• ChatGPT 订阅（Plus $20/月起），或
• OpenAI API Key（按量付费）

❓ Q2：支持哪些编程语言？

A：理论上支持所有编程语言，因为它底层使用的是 GPT 模型。实际效果：

• 优秀：Python, JavaScript/TypeScript, Java, Go, Rust, C/C++
• 良好：Ruby, PHP, Swift, Kotlin, C#
• 一般：小众语言、领域特定语言

❓ Q3：和 Claude Code 比，哪个更好？

A：各有优势：

维度	Codex CLI	Claude Code
开源	✅ 完全开源	❌ 闭源
速度	⚡ Rust 编写，更快	较慢
能力	强	更强（复杂任务）
价格	ChatGPT 订阅	Claude 订阅
生态	OpenAI 生态	Anthropic 生态

建议：两个都试试，看哪个更符合你的工作流。

❓ Q4：如何更新到最新版本？

# npm 安装的
npm update -g @openai/codex

# Homebrew 安装的
brew upgrade codex

# 脚本安装的，重新运行安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh

❓ Q5：为什么登录后提示"quota exceeded"？

A：ChatGPT 订阅有使用额度限制：

• Plus 用户有每日/每月限制
• 等待额度重置，或升级到 Pro（无限额度）

❓ Q6：如何在公司网络使用？

A：可能需要配置代理：

# 设置代理
export HTTPS_PROXY=http://proxy.company.com:8080

# 或在配置文件中设置
codex config set proxy http://proxy.company.com:8080

❓ Q7：支持离线使用吗？

A：不支持。Codex CLI 需要连接 OpenAI 服务器才能工作。

❓ Q8：代码会被上传到 OpenAI 吗？

A：是的，为了理解你的代码，Codex 会将相关代码片段发送到 OpenAI 服务器。

安全建议：

• 不要在包含敏感信息的项目使用
• 使用 .gitignore 类似的机制排除敏感文件
• 企业用户考虑使用 Enterprise 版本

❓ Q9：如何查看使用量？

# 查看当前会话使用量
codex usage

# 或登录 OpenAI 平台查看
# https://platform.openai.com/usage

❓ Q10：遇到 bug 怎么办？

1. 查看 GitHub Issues
2. 搜索是否已有类似问题
3. 提交新 issue，附上：
   • 操作系统版本
   • Codex 版本（codex --version）
   • 错误信息
   • 复现步骤

---

12. 总结

🎯 核心要点

1. Codex CLI 是什么：OpenAI 的开源终端 AI 编程助手
2. 如何安装：curl/brew/npm 三种方式，推荐一键脚本
3. 如何登录：ChatGPT 订阅或 API Key
4. 价格多少：Plus $20/月起，或 API 按量付费
5. 基本配置：AGENTS.md + config.json

📚 下一步

• 📖 第2篇：Codex CLI 命令大全：CLI指令与斜杠命令速查手册
• 🔧 实践：安装后尝试让 Codex 帮你写一个小功能
• 💬 社区：加入 Codex 社区交流使用经验

🔗 有用链接

• 官方文档
• GitHub 仓库
• 问题反馈
• Changelog

---

📝 系列文章导航

• 上一篇：系列开篇
• 下一篇：第2篇 - Codex CLI 命令大全：CLI指令与斜杠命令速查手册
• 系列目录：Codex CLI 中文官方手册与使用指南（12篇）

---

💡 遇到问题？ 欢迎在评论区留言，我会及时回复！

👍 觉得有用？ 点赞收藏，帮助更多开发者！