Codex CLI 终端教程 2026：命令行AI编程助手安装与实战
最新更新：2026年5月30日 — Codex CLI v0.36.0 版本发布，支持 GPT-5-Codex 模型，新增 Skills 自定义功能。本文全面更新了安装配置指南与最新功能解析。
Codex CLI 是 OpenAI 官方推出的终端版编程助手，让您可以在命令行环境中直接与 AI 交互，完成代码生成、Bug 修复、自动化任务等工作。对于习惯使用终端的开发者来说，Codex CLI 是提升效率的利器。本文详细介绍 Codex CLI 教程，涵盖从安装配置到实战应用的完整指南。
国内快速访问 ChatGPT，可选择以下精选镜像站：
- ChatGPT 中文版入口：https://lazymanchat.com
- ChatGPT 镜像站直达：https://chat.huoyachat.com
一、Codex CLI 是什么？终端编程助手简介
1.1 Codex CLI 的定位与特点
Codex CLI（Command Line Interface）是 OpenAI Codex 的命令行版本，它将强大的 AI 编程能力带入终端环境。与图形界面版本不同，Codex CLI 完全基于文本交互，适合习惯命令行操作或需要自动化工作流的开发者。
Codex CLI 核心特点：
| 特点 | 说明 | 优势 |
|---|---|---|
| 轻量级 | 无需图形界面，纯终端运行 | 资源占用低，适合远程服务器 |
| 跨平台 | 支持 macOS、Linux、Windows WSL | 统一开发体验 |
| 可脚本化 | 支持管道和重定向 | 易于集成到自动化流程 |
| 快速响应 | 直接命令行交互 | 无需切换窗口，效率更高 |
| 全功能 | 与 IDE 扩展功能一致 | 不因界面简化而牺牲能力 |
1.2 Codex CLI 与 IDE 扩展的区别
| 对比项 | Codex CLI | Codex IDE 扩展 |
|---|---|---|
| 交互方式 | 纯命令行文本交互 | 图形界面 + 对话气泡 |
| 代码可视化 | 无，需想象代码结构 | 直接高亮显示修改 |
| 文件操作 | 需明确指定文件路径 | 自动识别当前编辑文件 |
| 学习曲线 | 需熟悉命令行操作 | 更直观，适合新手 |
| 自动化能力 | 强，易于脚本集成 | 较弱 |
| 资源占用 | 低（仅 CLI 工具） | 中（需运行 IDE） |
选择建议：
- 选择 CLI：习惯终端操作、需要自动化、远程开发、多设备同步
- 选择 IDE 扩展：喜欢图形界面、需要实时看到代码变化、新手入门
实际上，您完全可以同时使用两者，IDE 扩展用于日常开发，CLI 用于自动化脚本和特殊任务。
1.3 Codex CLI 能做什么？
Codex CLI 的典型使用场景：
| 场景 | 示例命令 | 说明 |
|---|---|---|
| 代码生成 | codex "创建一个用户登录 API" | 根据自然语言生成代码 |
| 代码解释 | codex "解释这个文件的逻辑" | 理解陌生代码 |
| Bug 修复 | codex "修复这个错误" | 定位并修复问题 |
| 代码重构 | codex "重构为 TypeScript" | 批量转换代码 |
| 测试生成 | codex "生成单元测试" | 批量生成测试用例 |
| 文档生成 | codex "生成 API 文档" | 自动生成注释和文档 |
| 批量操作 | 在脚本中调用 Codex | 自动化工作流 |
二、Codex CLI 安装详解（支持 macOS/Linux/Windows）
2.1 安装前准备工作
在安装 Codex CLI 之前，请确保您的环境满足以下要求：
2.1.1 系统要求
| 操作系统 | 支持情况 | 推荐配置 |
|---|---|---|
| macOS | ✅ 完全支持 | macOS 12 (Monterey) 及以上 |
| Linux | ✅ 完全支持 | Ubuntu 20.04+、Debian 11+ 等主流发行版 |
| Windows | ⚠️ 推荐 WSL | 直接安装可能存在兼容问题 |
| Windows WSL | ✅ 完全支持 | Ubuntu on Windows (WSL2) |
2.1.2 Node.js 环境
Codex CLI 基于 Node.js 开发，需要提前安装 Node.js 环境：
| 要求 | 最低版本 | 推荐版本 | 检查命令 |
|---|---|---|---|
| Node.js | v18+ | v22+ | node -v |
| npm | 内置于 Node | 最新版 | npm -v |
安装 Node.js 的方法：
| 操作系统 | 推荐安装方式 |
|---|---|
| macOS | Node.js 官网下载 或 brew install node |
| Linux | curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs |
| Windows | 通过 WSL 使用 Linux 版 Node.js |
2.1.3 网络要求
Codex CLI 需要访问 OpenAI API，请确保：
- 能够稳定访问
api.openai.com - 网络延迟不要过高（否则响应慢）
- 如在中国大陆，需要配置代理
配置代理（可选）：
# 设置 HTTP 代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
# 或者在命令中指定
codex --proxy http://127.0.0.1:78902.2 macOS / Linux 安装方法
方法一：npm 全局安装（推荐）
# 使用 npm 全局安装
npm install -g @openai/codex
# 验证安装成功
codex --version如果安装成功，会显示类似 codex version 0.36.0 的版本信息。
方法二：Homebrew 安装
# 首次安装需要添加仓库
brew tap openai/codex
# 安装 Codex
brew install --cask codex
# 验证安装
codex --version方法三：直接下载二进制文件
如果您不想使用 npm 或 Homebrew，可以直接从 GitHub 下载预编译的二进制文件：
-
下载适合您系统的版本：
codex-macos-arm64（Apple Silicon Mac）codex-macos-x64（Intel Mac）codex-linux-x64（Linux x86_64）codex-linux-arm64（Linux ARM64）
-
解压并添加执行权限：
# 假设下载到 ~/Downloads
chmod +x ~/Downloads/codex-*
# 移动到 PATH 目录
sudo mv ~/Downloads/codex-* /usr/local/bin/codex
# 验证安装
codex --version2.3 Windows 安装方法
推荐方式：WSL（Windows Subsystem for Linux）
Windows 用户强烈推荐使用 WSL，因为在 Linux 环境下 Codex CLI 运行更稳定：
第一步：安装 WSL
以管理员身份打开 PowerShell，运行：
wsl --install此命令会安装 WSL2 和 Ubuntu Linux 发行版。
第二步：重启电脑
安装完成后需要重启系统。
第三步：设置 Ubuntu 用户
重启后会自动打开 Ubuntu 终端，设置您的用户名和密码。
第四步：在 WSL 中安装 Node.js
# 更新包索引
sudo apt update && sudo apt upgrade -y
# 安装 Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
# 验证 Node.js
node -v
npm -v第五步：安装 Codex CLI
# 安装 Codex CLI
npm install -g @openai/codex
# 验证安装
codex --version使用提示：以后每次使用 Codex，需要先在 PowerShell 或 Windows Terminal 中输入
wsl进入 Linux 环境，然后运行codex命令。
备选方式：Windows 原生安装
如果不方便使用 WSL，可以尝试原生安装（不保证完全兼容）：
# 使用 npm 全局安装（强制跳过 OS 检查）
npm install -g @openai/codex --force --no-os-check
# 验证安装
codex --version可能遇到的问题：
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 安装失败 | 权限不足 | 以管理员身份运行 PowerShell |
| 找不到命令 | PATH 未配置 | 重启终端或手动添加 PATH |
| 功能异常 | 路径格式不兼容 | 建议改用 WSL |
2.4 国内用户安装特别说明
由于网络原因，国内用户在安装 npm 包或访问 OpenAI API 时可能遇到困难。以下是解决方案：
解决方案一：配置 npm 镜像
# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com
# 再次尝试安装
npm install -g @openai/codex解决方案二：使用代理
# 设置代理
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
# 安装 Codex
npm install -g @openai/codex解决方案三：离线安装
如果您有海外服务器，可以通过海外服务器下载 npm 包后本地安装：
# 在海外服务器上
npm pack @openai/codex
# 下载到本地后安装
npm install /path/to/codex-*.tgz三、Codex CLI 首次配置与登录
3.1 登录 ChatGPT 账号
安装完成后，首次运行 codex 命令会引导您完成登录：
codexCodex CLI 会显示以下选项：
Welcome to Codex CLI!
How would you like to sign in?
1. Sign in with ChatGPT (Recommended for ChatGPT Plus/Pro users)
2. Sign in with API Key (For API users)
Enter your choice:推荐选择选项 1：ChatGPT Plus、Pro、Team、Edu、Enterprise 用户均可使用，无需额外付费。
使用 ChatGPT 账号登录
- 输入
1并按回车 - Codex 会自动打开浏览器，跳转到登录页面
- 完成 ChatGPT 账号登录
- 回到终端，按任意键继续
- 登录成功后会显示欢迎信息
使用 API Key 登录
如果您使用 API Key 登录，需要提前获取 OpenAI API Key：
- 访问 OpenAI API Keys 页面
- 创建新的 API Key
- 输入
2选择 API Key 登录 - 粘贴您的 API Key
- 设置用量预算（避免超额）
安全提示：API Key 相当于您的账号密码，请勿泄露给他人。
3.2 基本配置
Codex CLI 的配置文件位于 ~/.codex/config.toml。您可以通过编辑此文件来自定义 Codex 的行为。
3.2.1 配置文件结构
# ~/.codex/config.toml
# 默认模型设置
[models]
default = "gpt-5-codex"
# 推理努力程度 (low/medium/high)
reasoning_effort = "medium"
# 网络搜索设置
[features.web_search]
enabled = true
mode = "cache" # 或 "live"
# 沙箱模式 (read-only/workspace-write/agent)
sandbox_mode = "workspace-write"
# 审批策略
[approval]
policy = "on-request" # on-request/always/never
# MCP 服务器配置
[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]3.2.2 常用配置项说明
| 配置项 | 可选值 | 说明 | 推荐值 |
|---|---|---|---|
models.default | gpt-5-codex 等 | 默认使用的模型 | gpt-5-codex |
reasoning_effort | low/medium/high | 推理深度，影响回答质量和速度 | medium |
sandbox_mode | read-only/workspace-write/agent | Codex 的操作权限范围 | workspace-write |
approval.policy | on-request/always/never | 执行操作前是否需要确认 | on-request |
features.web_search | true/false | 是否启用网络搜索 | true |
3.3 验证安装成功
配置完成后，运行以下命令验证 Codex CLI 正常工作：
# 检查版本
codex --version
# 测试基本对话
codex "你好，Codex"
# 指定模型
codex --model gpt-5-codex "测试模型响应"
# 查看帮助
codex --help如果一切正常，Codex CLI 会返回响应信息。
四、Codex CLI 常用命令详解
4.1 启动与对话命令
启动交互式会话
# 启动 Codex 对话
codex
# 指定项目目录启动
codex --dir /path/to/project
# 使用特定配置文件
codex --profile my-config单次命令执行
# 直接在命令行中提问
codex "解释这行代码的作用：const arr = [1, 2, 3].map(x => x * 2)"
# 读取文件内容后提问
cat file.js | codex "这个文件用了什么设计模式"
# 多行输入
codex "\
创建以下功能的代码：\
1. 用户注册 API\
2. 用户登录 API\
3. JWT 认证中间件"4.2 文件操作命令
读取和分析文件
# 分析单个文件
codex --file src/utils.js "分析这个文件的导出函数"
# 分析多个文件
codex --file a.py --file b.py "这两个文件的依赖关系是什么"
# 指定项目目录
codex --dir ./my-project "这个项目的技术栈是什么"编辑文件
# 编辑指定文件
codex --edit "在 src/utils.js 中添加一个格式化日期的函数"
# 重构文件
codex --file src/utils.js --edit "将这个文件从 JavaScript 转换为 TypeScript"创建新文件
# 创建新文件
codex --create src/api/user.ts "创建一个用户相关的 TypeScript 模块"4.3 Git 操作命令
# 提交代码
codex --git commit "添加用户认证功能"
# 创建分支
codex --git "基于 main 分支创建一个叫 feature/login 的分支"
# 代码审查
codex --git "审查最近的提交"
# 解决冲突
codex --git "解决当前的 Git 冲突"4.4 测试生成命令
# 为文件生成测试
codex --test "为 src/calculator.js 生成 Jest 测试"
# 为整个目录生成测试
codex --dir src --test "为 src 目录下的所有模块生成测试"
# 指定测试框架
codex --file src/api/user.js --test --framework vitest "使用 Vitest 生成测试"4.5 自动化与脚本集成
在脚本中使用 Codex
#!/bin/bash
# 自动代码审查脚本
for file in $(git diff --name-only HEAD~1); do
codex --file "$file" --review "审查这个文件的潜在问题"
done管道操作
# 读取 git diff 并发送给 Codex
git diff | codex "审查这些代码变更"
# 分析日志文件
cat error.log | codex "分析这个错误日志，定位根本原因"批量处理
# 批量重命名文件
ls *.js | xargs -I {} codex --file {} --edit "将文件重命名为 kebab-case"
# 批量添加注释
for f in src/*.py; do
codex --file "$f" --edit "为所有函数添加 docstring"
done4.6 配置与调试命令
# 查看当前配置
codex config show
# 设置配置项
codex config set models.default gpt-5-codex
codex config set reasoning_effort high
# 清除配置（恢复默认值）
codex config clear
# 启用调试模式
codex --debug "执行的操作会显示详细日志"
# 查看版本
codex --version
# 查看帮助
codex --help五、Codex CLI 实战教程
5.1 实战一：快速创建新项目
使用 Codex CLI 从零开始创建一个项目：
# 1. 创建项目目录
mkdir my-new-project && cd my-new-project
# 2. 初始化项目
codex "初始化一个 React + TypeScript 项目，使用 Vite"
# 3. 创建组件
codex "创建一个叫 UserCard 的组件"
# 4. 创建 API 模块
codex "创建用户相关的 API 模块，包含增删改查"
# 5. 添加测试
codex --test "为所有组件和 API 添加测试"5.2 实战二：代码重构迁移
将旧项目重构为新技术栈：
# 1. 分析现有代码
codex --dir ./old-project "分析这个项目的结构和依赖"
# 2. 制定迁移计划
codex "制定从 JavaScript 迁移到 TypeScript 的计划"
# 3. 开始迁移
codex --file src/user.js --edit "将这个文件迁移为 TypeScript"
# 4. 验证迁移
codex --test "验证迁移后的代码功能正常"5.3 实战三：自动化代码审查
创建自动化审查工作流：
# 创建审查脚本
cat > review.sh << 'EOF'
#!/bin/bash
echo "=== 开始代码审查 ==="
echo ""
# 获取最近提交的文件
FILES=$(git diff --name-only HEAD~1)
for file in $FILES; do
echo "--- 审查文件: $file ---"
codex --file "$file" --review "检查安全性、性能和最佳实践"
echo ""
done
echo "=== 代码审查完成 ==="
EOF
chmod +x review.sh
./review.sh5.4 实战四：Bug 定位与修复
使用 Codex 快速定位和修复 Bug：
# 1. 描述问题
codex "我的登录功能一直返回 401 错误，请帮我排查"
# 2. 分析错误日志
cat error.log | codex "分析这个错误日志，找出根本原因"
# 3. 定位问题代码
codex --file src/auth/login.ts "检查这个登录模块的可能问题"
# 4. 获取修复方案
codex --file src/auth/login.ts --edit "修复登录模块的问题"5.5 实战五：生成项目文档
自动生成项目文档：
# 生成 README
codex --dir . --create README.md "生成项目 README，包含使用说明和贡献指南"
# 生成 API 文档
codex --dir src/api --create docs/api.md "为 API 模块生成详细的接口文档"
# 生成代码注释
codex --dir src --edit "为所有公开的函数添加 JSDoc 注释"六、Codex CLI 高级配置
6.1 项目级配置文件
除了全局配置，Codex 还支持项目级的配置文件。在项目根目录创建 .codex/config.toml：
# .codex/config.toml (项目级配置)
# 继承全局配置的设置
# 在此覆盖需要的配置
[models]
# 使用项目指定的模型版本
default = "gpt-5-codex"
[approval]
# 项目采用更严格的审批策略
policy = "always"项目级配置的加载顺序：
- 系统配置：
/etc/codex/config.toml - 全局配置：
~/.codex/config.toml - 配置文件：
~/.codex/profile-name.config.toml - 项目配置：
.codex/config.toml（最近目录优先）
6.2 AGENTS.md 配置
在项目根目录创建 AGENTS.md，为 Codex 提供项目上下文：
# AGENTS.md
## 项目概述
这是一个 Node.js + Express 的 RESTful API 项目。
## 技术栈
- 运行时：Node.js 22
- 框架：Express 5
- 数据库：PostgreSQL 16
- ORM：Prisma
- 认证：JWT
## 代码规范
- 使用 ESLint + Prettier
- 所有 API 返回统一格式：`{ success, data, error }`
- 错误码规范：1000-1999 用户错误，2000-2999 服务器错误
## 常用命令
- 开发：`npm run dev`
- 测试：`npm test`
- 构建：`npm run build`
- 迁移：`npx prisma migrate dev`
## 注意事项
- 所有敏感配置通过环境变量管理
- 不要提交 `.env` 文件
- 生产环境必须使用 HTTPS6.3 MCP 服务器配置
MCP（Model Context Protocol）允许 Codex 连接外部工具和服务：
6.3.1 GitHub MCP 配置
# ~/.codex/config.toml
[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_xxxx" }6.3.2 文件系统 MCP 配置
[[mcp.servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem"]
env = { ALLOWED_DIRECTORIES = "/home/user/projects" }6.3.3 Slack MCP 配置
[[mcp.servers]]
name = "slack"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-slack"]
env = { SLACK_BOT_TOKEN = "xoxb-xxxx", SLACK_TEAM_ID = "T123456" }6.4 自动化脚本配置
6.4.1 CI/CD 集成示例
# .github/workflows/code-review.yml
name: AI Code Review
on:
pull_request:
branches: [main, develop]
jobs:
code-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
- name: Install Codex CLI
run: npm install -g @openai/codex
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
- name: Run AI Code Review
run: |
codex --git "审查这个 PR 的代码质量"6.4.2 Git Hooks 集成
# .git/hooks/pre-commit
#!/bin/bash
echo "运行 AI 代码检查..."
# 检查暂存的代码
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
for file in $STAGED_FILES; do
if [[ "$file" == *.js || "$file" == *.ts" ]]; then
echo "检查文件: $file"
codex --file "$file" --check "检查代码规范和潜在问题"
fi
done
echo "AI 检查完成"七、Codex CLI 常见问题 FAQ
Q1：Codex CLI 如何设置中文界面？
A1：Codex CLI 本身不提供界面语言设置，但您可以通过以下方式使用中文：
- 直接使用中文提问，Codex 会用中文回答
- 在 AGENTS.md 中指定：
assistant_language = "Chinese" - 设置环境变量：
export CODEX_LANGUAGE=zh
Q2：Codex CLI 和 Claude CLI 哪个更好？
A2：两者都是优秀的命令行 AI 编程助手，选择取决于您的需求：
| 对比项 | Codex CLI | Claude CLI |
|---|---|---|
| 母公司 | OpenAI | Anthropic |
| 模型 | GPT-5-Codex | Claude |
| 与 ChatGPT 集成 | ✅ 深度集成 | ❌ 独立生态 |
| GitHub 集成 | ✅ MCP 原生支持 | ✅ 内置支持 |
| 视频生成 | ✅ 支持 | ❌ 不支持 |
| 使用成本 | ChatGPT Plus 含 | Claude Pro 含 |
如果您已经是 ChatGPT Plus/Pro 用户，Codex CLI 是零成本的选择；如果您需要更长的上下文窗口，Claude CLI 可能更适合。
Q3：Codex CLI 如何处理敏感信息？
A3：保护敏感信息的安全建议：
| 建议 | 说明 |
|---|---|
| 使用环境变量 | 不要在对话中直接输入 API Key、密码等 |
| 配置沙箱模式 | 设置 sandbox_mode = "read-only" 防止文件写入 |
| 开启审批模式 | 设置 approval.policy = "always" 确认每个操作 |
| 定期审查 | 使用 codex --history 查看对话记录 |
Q4：Codex CLI 响应很慢怎么办？
A4：提高响应速度的方法：
| 方法 | 操作 | 效果 |
|---|---|---|
| 降低推理努力 | reasoning_effort = "low" | 响应更快，质量略降 |
| 使用缓存 | 确保 --no-cache 未启用 | 减少重复计算 |
| 检查网络 | 测试到 OpenAI 的延迟 | 必要时配置代理 |
| 选择近的服务器 | 使用 API Key 指定美国区域 | 减少网络延迟 |
Q5：Codex CLI 支持离线使用吗？
A5：不支持。Codex CLI 需要连接到 OpenAI 服务器才能工作：
- 所有 AI 处理都在云端完成
- 本地只保存配置和对话缓存
- 无网络连接时无法使用
如果您需要离线编程能力，可以考虑使用本地部署的开源模型，如 Code Llama、DeepSeek Coder 等。
Q6：Codex CLI 的用量如何计算？
A6：Codex CLI 的用量取决于您的账号类型：
| 账号类型 | Codex 用量 | 说明 |
|---|---|---|
| Free | ❌ 不可用 | 需要升级到 Plus |
| Plus | ✅ 包含 | 有使用上限 |
| Pro | ✅ 包含，更高上限 | 更适合重度使用 |
| API | 按量计费 | 输入/输出分别计费 |
Q7：如何升级 Codex CLI？
A7：升级方法取决于安装方式：
# npm 安装
npm update -g @openai/codex
# Homebrew 安装
brew upgrade codex
# 检查版本
codex --version八、总结与延伸阅读
通过本文的 Codex CLI 教程，您已经全面掌握了终端版 OpenAI 编程助手的安装配置、常用命令和实战技巧。Codex CLI 是提升开发效率的强大工具，无论是日常编码辅助还是自动化工作流，都能发挥重要作用。
核心要点回顾：
| 技能 | 掌握程度 | 说明 |
|---|---|---|
| 安装配置 | ✅ 必会 | npm/Homebrew/二进制文件三种方式 |
| 登录认证 | ✅ 必会 | ChatGPT 账号或 API Key |
| 基本命令 | ✅ 熟练 | codex 单次命令和交互式会话 |
| 文件操作 | ✅ 熟练 | —file、—dir、—edit 参数 |
| Git 集成 | ⭐ 进阶 | —git 参数实现代码审查 |
| 自动化 | ⭐ 进阶 | 脚本集成和 CI/CD 部署 |
| 高级配置 | ⭐ 精通 | MCP、AGENTS.md、自定义工作流 |
延伸阅读推荐：
- Codex 完整使用指南 — IDE 扩展和网页版详解
- ChatGPT 新手指南 — 从零开始使用 ChatGPT
- ChatGPT 注册教程 — 如何注册 ChatGPT 账号
立即行动：
- 今天就安装 Codex CLI：
npm install -g @openai/codex - 完成首次登录配置
- 尝试一个简单的代码任务
- 探索更高级的自动化功能
AI 辅助编程的时代已经到来，掌握 Codex CLI 将让您在命令行环境中如虎添翼！