Codex CLI 实战教程：从安装到第一个 PR 跑通

📅 2026-06-10 · 📄 约 5100 字

前言

Codex CLI 是 OpenAI 推出的一款轻量级编程代理工具，能够在终端环境中直接运行，帮助开发者完成代码编写、问题诊断、自动化任务等工作。作为开源项目 openai/codex 的核心产品，它于 2026-06-09 发布了最新版本 rust-v0.139.0，目前已在 GitHub 获得超过 90,000 颗星标，采用 Apache-2.0 开源许可证，主要使用 Rust 语言开发。

Codex CLI 工作流

与传统的 IDE 插件不同，Codex CLI 完全运行在本地终端，支持 VS Code、Cursor、Windsurf 等主流编辑器的集成，同时也提供独立的 Desktop 应用。它不仅能够理解代码上下文，还能通过 Code mode 在嵌套的 JavaScript 工具调用中直接调用网络搜索功能，极大提升了开发效率。本教程将从环境准备开始，手把手带领读者完成 Codex CLI 的安装、配置，并演示如何利用它完成一个完整的 Pull Request 工作流程。

环境准备

在开始使用 Codex CLI 之前，需要确保本地开发环境满足基本要求。Codex CLI 本身由 Rust 编写，但对终端环境有明确的依赖。

终端兼容性

Codex CLI 支持主流的 Unix/Linux 终端以及 Windows PowerShell。推荐使用以下终端环境：

  • macOS/Linux：iTerm2、Terminal.app、gnome-terminal 等标准终端
  • Windows：PowerShell 5.0 及以上版本，或 Windows Terminal

网络与 API 密钥

Codex CLI 需要连接 OpenAI API 服务，因此需要准备有效的 API Key。目前支持两种认证方式：

export OPENAI_API_KEY=sk-your-api-key-here
codex

这种方式将 API Key 临时注入当前终端会话。更持久的方式是将环境变量写入 shell 配置文件（如 ~/.bashrc 或 ~/.zshrc）。

Git 环境

由于 Codex CLI 经常需要与 Git 仓库交互，建议确保本地已安装 Git 并完成基本配置：

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

代码编辑器集成

Codex CLI 支持与 VS Code、Cursor、Windsurf 等编辑器无缝集成。集成后，开发者可以在编辑器侧边栏直接与 Codex CLI 对话，享受实时代码补全、错误诊断等功能。集成方式通常通过各编辑器的插件市场安装对应扩展即可完成。

基础使用

Codex CLI 提供了多种安装方式，涵盖不同的操作系统和用户习惯。以下是官方推荐的五种安装方法：

方式一：Shell 脚本安装（Linux/macOS）

这是最快速的安装方式，适用于大多数 Unix 系统：

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

该脚本会自动检测系统环境，下载对应的二进制文件并将其添加到系统 PATH 中。安装完成后，可以在终端直接输入 codex 启动程序。

方式二：PowerShell 安装（Windows）

Windows 用户可以使用 PowerShell 一行命令完成安装：

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

该命令会下载并执行官方安装脚本，自动配置 Codex CLI 的运行环境。

方式三：npm 全局安装

对于已安装 Node.js 的开发者，可以通过 npm 包管理器安装：

npm install -g @openai/codex

这种方式安装的 Codex CLI 会作为全局 npm 命令可用，便于在项目中快速调用。

方式四：Homebrew 安装（macOS）

macOS 用户如果已配置 Homebrew，可以使用官方的 Cask 安装：

brew install --cask codex

Homebrew 会自动处理依赖关系，并提供便捷的版本管理功能。

方式五：手动下载安装

从 GitHub 仓库的 Releases 页面下载对应平台的压缩包，解压后将可执行文件移动到系统 PATH 中的任意目录即可。这种方式适合需要特定版本或离线安装的场景。

首次启动与认证

完成安装后，首次运行需要配置 API Key。按照前文提到的环境变量方式设置后，启动 Codex CLI：

codex

如果认证成功，CLI 会显示欢迎信息并进入交互模式。此时可以开始输入指令，Codex CLI 会根据上下文理解开发者的意图并提供相应的帮助。

核心功能详解

Codex CLI 的核心功能围绕提升开发者效率展开，结合了 AI 理解和本地终端执行能力。以下是几个最重要的功能模块：

Code Mode（代码模式）

Code mode 是 Codex CLI 最强大的特性之一。它允许在嵌套的 JavaScript 工具调用中直接调用网络搜索功能，这意味着开发者在编写代码时可以实时获取外部文档、API 规范或技术解决方案的帮助。例如，当遇到不熟悉的库函数时，只需在 Code mode 中描述问题，Codex 会自动搜索相关资料并提供代码示例。

MCP 工具与 Connector 支持

在最新版本 v0.139.0 中，Codex CLI 增强了对 MCP（Model Context Protocol）工具的支持。现在可以处理 oneOf 和 allOf 模式的 schema，这意味着它能够更好地与各种外部工具和服务集成。开发者可以轻松配置自定义的 Connector，将 Codex 与自己的内部工具链连接起来。

codex doctor：环境诊断

codex doctor 命令是排查问题的利器。它会检查本地开发环境的关键组件，包括编辑器配置、分页器（pager）设置、Git 集成状态等，并给出详细的诊断报告：

codex doctor

如果需要将诊断结果用于自动化脚本或脱敏处理，可以加上 --json 参数：

codex doctor --json

JSON 输出会隐藏敏感的路径信息，便于安全分享或记录。

codex plugin marketplace：插件市场

v0.139.0 引入了插件市场的管理功能。通过 codex plugin marketplace list --json 可以查看当前可用的插件列表：

codex plugin marketplace list --json

该命令会返回插件的详细信息，包括名称、版本、描述和 marketplace 来源。开发者可以根据需要安装或更新插件，扩展 Codex CLI 的功能。

会话管理：resume 与 fork

长时间的开发过程中，会话管理至关重要。Codex CLI 提供了两个实用的会话命令：

  • codex resume：恢复之前的会话，继续未完成的工作
  • codex fork：创建当前会话的分支，适合尝试不同方案而不影响原会话

这两个功能对于大型重构或实验性开发非常有用，可以有效避免工作进度丢失。

线程重置：/new、/clear、/fork

在交互式会话中，开发者可以使用以下命令重置当前线程：

  • /new：创建新会话
  • /clear：清除当前会话历史
  • /fork：分叉当前会话

值得注意的是，这些线程重置操作不会丢失云端配置，确保开发者可以在不同设备间无缝切换工作环境。

沙箱执行与安全

Codex CLI 的沙箱（Sandbox）执行环境可以安全地运行代码，同时保留经过批准的权限提升（escalation）决策。这意味着开发者可以在受控环境中测试危险操作，而不必担心意外的系统修改。MCP 启动警告现在会被归入子线程处理，保持主线程的响应速度。

图片处理与链接识别

在处理图像相关任务时，Codex CLI 能够精确锁定引用图片的路径，避免误操作。对于包含波浪号（~）的裸 URL，TUI（终端用户界面）会完整地将其转换为可点击链接，提升阅读体验。

实际案例：从零开始完成一个 Pull Request

下面通过一个完整案例，展示如何使用 Codex CLI 完成一个真实的 Pull Request 工作流程。

案例背景

假设我们需要为开源项目贡献一个功能：添加一个日志格式化工具函数。项目使用 Git 管理，代码托管在 GitHub 上。

步骤一：环境诊断

首先使用 codex doctor 检查本地环境是否就绪：

codex doctor

诊断报告会列出编辑器配置、Git 状态、分页器设置等信息。如果发现问题，根据报告中的建议进行调整。

步骤二：克隆仓库并创建分支

git clone https://github.com/example/project.git
cd project
git checkout -b feature/log-formatter

在分支上开始新功能的开发。

步骤三：与 Codex 交互编写代码

启动 Codex CLI 并描述需求：

codex

在交互界面中输入：

请帮我实现一个日志格式化函数，接受日志级别和消息内容，返回格式化的字符串。要求支持 DEBUG、INFO、WARN、ERROR 四种级别，使用不同的颜色前缀。

Codex 会根据 Code mode 搜索相关最佳实践，生成符合项目代码风格的实现。

步骤四：添加单元测试

继续在 Codex 会话中请求生成测试代码：

请为上述日志格式化函数生成单元测试，覆盖所有四种日志级别。

Codex 会创建对应的测试文件。

步骤五：运行测试验证

codex

在 Codex 中运行测试：

请运行项目的测试套件验证代码正确性。

如果测试失败，Codex 会分析错误原因并提供修复建议。

步骤六：提交代码并创建 PR

git add .
git commit -m "feat: 添加日志格式化工具函数"
git push origin feature/log-formatter

最后在 GitHub 上创建 Pull Request，描述所做的更改和测试结果。

会话保存与恢复

如果在开发过程中需要中断，可以使用 codex fork 创建会话备份：

codex fork

下次继续时，使用 codex resume 恢复工作进度：

codex resume

常见问题

问题一：API Key 认证失败

如果启动 Codex CLI 时提示认证错误，首先检查环境变量是否正确设置：

echo $OPENAI_API_KEY

确保 Key 有效且未过期。如果使用临时会话，需要重新导出环境变量。

问题二：终端显示乱码

Codex CLI 支持彩色输出，但部分终端可能因编码设置导致乱码。解决方案是在终端配置中设置 UTF-8 编码：

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

问题三：插件安装失败

如果 codex plugin marketplace list --json 无法获取插件列表，可能是网络问题或插件市场服务异常。可以检查网络连接后重试，或查看官方 GitHub 仓库的 Issues 页面获取最新状态。

问题四：会话意外中断

长时间运行可能会话可能因网络波动或终端关闭而中断。使用 codex fork 定期保存会话快照，或在重新连接后使用 codex resume 恢复工作状态。

问题五：编辑器集成无响应

如果 VS Code 或其他编辑器的 Codex 插件无响应，首先检查插件是否正确安装，然后尝试重启编辑器。如果问题持续，使用 codex doctor 检查编辑器配置是否正确。

优缺点总结

优点

  • 轻量高效：完全运行在终端，不占用额外桌面资源，启动速度快
  • AI 增强：Code mode 支持在代码编写过程中实时搜索外部资料，大幅提升开发效率
  • 强大的工具链集成：支持 MCP 协议、多种编辑器插件、插件市场扩展
  • 会话管理完善：resume、fork、线程重置等功能保证工作连续性
  • 开源透明：Apache-2.0 许可证，社区活跃度高

缺点

  • 依赖 API Key：需要 OpenAI 账号和有效 API Key，部分高级功能需要付费订阅
  • 网络依赖：核心功能需要联网使用，离线场景受限
  • 学习曲线：虽然交互友好，但充分发挥全部功能需要一定时间熟悉
  • 终端环境要求：部分高级特性（如图片处理）需要特定终端支持

结语

Codex CLI 作为 OpenAI 推出的轻量级编程代理工具，凭借其终端优先的设计理念和强大的 AI 能力，正在改变开发者的日常工作方式。从环境诊断到代码编写，从插件管理到 Pull Request 流程，Codex 提供了一套完整且高效的解决方案。

本教程详细介绍了 Codex CLI 的五种安装方式、核心功能的使用方法，并通过一个完整的 Pull Request 案例展示了实际开发场景中的工作流程。随着 v0.139.0 版本的发布，Codex 在 MCP 工具支持、插件市场、会话管理等方面又有了显著进步。

对于希望提升开发效率、简化重复性工作的开发者而言，Codex CLI 值得一试。建议读者按照本教程的步骤完成安装和基础使用后，进一步探索其丰富的功能，逐步将其融入自己的开发工作流中。