乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > OpenAI Codex CLI 完全使用指南:终端里的 AI 编码 Agent

OpenAI Codex CLI 完全使用指南:终端里的 AI 编码 Agent

当前时间： 2026-08-16 04:02:15 分类：办公文件 评论(0)
OpenAI Codex CLI 完全使用指南:终端里的 AI 编码 Agent

OpenAI Codex CLI 完全使用指南：终端里的 AI 编码 Agent

引言

2025 年，OpenAI 发布了 Codex CLI —— 一款在终端本地运行的轻量级 AI 编码 Agent。这是一个与 Claude Code、Cursor 等工具相竞争的 AI 编码助手。Codex CLI 完全开源（Apache 2.0 协议），托管在 GitHub 上，已收获 91k+ Star，社区极为活跃。

与市面上其他 AI 编码 Agent 不同，Codex CLI 走的是"终端优先"路线。它没有图形界面，但提供了完整的 TUI（终端用户界面），让开发者在自己最熟悉的环境中获得 AI 辅助编程的能力。

如果你正在寻找一个能在终端中直接运行、无需离开命令行就能完成编码任务的 AI 工具，那么 Codex CLI 值得一试。

Codex CLI 的三大产品形态

OpenAI Codex 实际上覆盖了三个不同的产品形态：

  1. Codex CLI — 终端本地运行的开源版本，完全免费，使用自己的 OpenAI API Key 或 ChatGPT 订阅
  2. Codex IDE 插件 — 集成到 VS Code、Cursor、Windsurf 等编辑器的插件
  3. Codex Web — 浏览器端云 Agent，访问 chatgpt.com/codex 即可使用

本文重点介绍 Codex CLI 的安装和使用。

安装 Codex CLI

系统要求

要求 说明
操作系统 macOS 12+、Ubuntu 20.04+/Debian 10+、Windows 11（需 WSL2）
内存 最低 4GB，推荐 8GB
Git 推荐 2.23+（内置 PR 助手功能需要）

一行命令安装（推荐）

macOS / Linux：

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

Windows（PowerShell）：

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

通过包管理器安装

npm 安装（推荐 Node.js 用户）：

npm install -g @openai/codex

Homebrew 安装（macOS 用户）：

brew install --cask codex

从 GitHub Release 手动安装

访问 Codex CLI 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 并放到 PATH 中即可。

认证方式

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

运行 codex 后选择 Sign in with ChatGPT。使用 ChatGPT Plus、Pro、Business、Edu、Enterprise 订阅的用户可以直接使用配额。这是最推荐的方式。

方式二：API Key

也可以通过 OpenAI API Key 认证，但需要额外配置。具体步骤参考 OpenAI 官方文档。

核心功能详解

1. TUI 交互模式

运行 codex 不带任何参数，即可进入 TUI 模式。这是一个终端交互界面，你可以在其中：

  • 输入自然语言指令
  • 查看 AI Agent 的执行过程
  • 实时观察文件修改、命令执行
  • 查看代码 Diff

TUI 模式下，Codex CLI 会：

  1. 理解你的需求 — 用自然语言描述任务
  2. 读取项目上下文 — 自动扫描项目结构、代码文件
  3. 生成修改方案 — 规划如何实现你的需求
  4. 执行修改 — 直接修改文件、运行命令
  5. 展示结果 — 显示代码 Diff 和执行输出

2. 非交互式执行模式

对于自动化脚本和 CI/CD 场景，Codex CLI 支持非交互模式：

codex exec "给所有 API 端点添加错误日志"

codex exec 默认只输出 RUST_LOG=error 级别的日志，适合在自动化流程中使用。

3. 项目上下文管理（.codex 目录）

这是 Codex CLI 最强大的特性之一。在每个项目根目录创建 .codex/ 目录，用于存储与项目相关的 AI 上下文配置。

.codex 目录支持：

  • skills/ — 技能文件夹，可以定义特定任务的执行技能（如 Code Review、PR 管理、测试等）
  • environments/ — 环境配置
  • _instructions.md — 项目级指令文件，告诉 Codex 如何理解这个项目

这个机制让 Codex CLI 在大型项目中表现得极为专业。例如，OpenAI 官方仓库中就有 babysit-pr（PR 巡查）、code-review-breaking-changes（破坏性变更审查）等技能。

4. 内置 Git 和 PR 集成

Codex CLI 内置了 Git 操作支持，可以：

  • 自动创建分支
  • 生成符合规范的 commit message
  • 创建 Pull Request
  • 参与 Code Review

配合 .codex/skills/ 中的 PR 相关技能，可以实现全自动的代码提交流程。

5. 多模型支持

Codex CLI 支持多种 OpenAI 模型，可以根据任务复杂度和成本选择不同的模型。简单任务用快速模型，复杂重构用强模型。

实战：五个典型使用场景

场景一：从零开始创建项目

# 进入项目目录
mkdir my-project && cd my-project

# 启动 Codex CLI
codex

然后输入："创建一个 Python FastAPI 项目，包含用户认证、数据库模型和 RESTful API"

Codex CLI 会自动生成完整的项目骨架，包括目录结构、配置文件、核心代码。

场景二：代码重构

cd existing-project
codex exec "将项目中所有的同步 HTTP 请求替换为异步 aiohttp 请求，保持接口兼容"

非交互模式下，Codex 会扫描所有文件，找到相关的同步代码，生成异步实现，并确保接口签名不变。

场景三：添加新功能

codex "为这个 Web 应用添加用户密码重置功能，包含邮箱验证、Token 生成、过期处理"

Codex CLI 会：

  1. 分析现有用户模型和认证流程
  2. 设计密码重置流程
  3. 创建重置 Token 表
  4. 实现发送邮件、验证 Token、重置密码的 API
  5. 更新前端页面

场景四：自动化 Code Review

配置 .codex/skills/code-review/SKILL.md 技能文件后，每次提 PR 时 Codex CLI 可以自动审查代码变更：

codex exec "审查最新的 Pull Request，检查潜在的安全问题和性能瓶颈"

场景五：Bug 修复

codex "应用在生产环境出现 500 错误，错误日志显示 'IndexError: list index out of range'，请在 data_processor.py 中修复"

Codex 会读取错误日志和相关代码，定位问题根源，生成修复方案并应用。

与其他 AI 编码工具的对比

特性 Codex CLI Claude Code Cursor
运行方式 终端 TUI 终端 TUI GUI 编辑器
开源 ✅ Apache 2.0 ❌ 闭源 部分开源
本地运行 ✅ 完全本地 ✅ 完全本地 部分云端
项目上下文 ✅ .codex 技能系统 ✅ CLAUDE.md ✅ .cursorrules
免费使用 ✅ 自带 ChatGPT 订阅 ✅ 自带 Claude 订阅 ❌ 需付费
IDE 集成 ❌ 纯终端 ❌ 纯终端 ✅ 编辑器原生
Git 集成 ✅ 内置 ✅ 内置 ⚠️ 部分
跨平台 macOS/Linux/WSL2 macOS/Linux/WSL2 macOS/Windows/Linux

高级技巧

1. 自定义技能（Skills）

Skill 是 Codex CLI 最亮眼的功能。你可以创建自己的技能来标准化团队的开发流程。

在项目根目录创建 .codex/skills/<skill-name>/SKILL.md：

# my-custom-skill

当你收到"执行部署"的指令时，按以下步骤操作：

1. 运行 `npm run build` 确认构建成功
2. 运行 `npm test` 确认测试通过
3. 更新 CHANGELOG.md 中的版本号
4. 执行 `git tag v<version>` 打标签
5. 推送到部署环境

之后只需要说 "执行部署"，Codex CLI 就会自动执行这 5 个步骤。

2. 启用详细日志

codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

这会在 .codex-log/ 目录生成详细的操作日志，方便调试和审计。

3. 从源码构建

如果你需要最新的特性或想贡献代码：

git clone https://github.com/openai/codex.git
cd codex/codex-rs
cargo build
cargo run --bin codex -- "解释这个代码库"

4. 使用 DotSlash 锁定版本

GitHub Release 中包含了 DotSlash 文件，可以锁定团队使用的 Codex 版本：

# 将 codex (DotSlash 文件) 提交到版本控制
# 所有团队成员自动使用相同的 Codex 版本

注意事项

  1. 需要网络连接 — Codex CLI 虽然是本地运行，但 AI 推理需要调用 OpenAI API
  2. API Key 安全 — 妥善保管 API Key，不要提交到版本控制
  3. 代码审查不可少 — AI 生成的代码仍需人工审查，尤其是安全相关的修改
  4. Token 消耗 — 复杂任务会消耗大量 Token，注意用量
  5. Windows 用户 — 需要 WSL2，原生 Windows 暂不支持

结语

Codex CLI 代表了 AI 编码 Agent 的一个新方向：让 AI 融入开发者的原生工作流。它不需要你切换编辑器、学习新工具，只需要在终端里用自然语言描述需求，AI 就会自动完成编码任务。

对于已经习惯终端操作的开发者来说，Codex CLI 提供了最自然的人机协作方式。配合 .codex 目录的技能系统和 Git 集成，它可以成为你日常开发的得力助手。

如果你还没有尝试过 AI 编码 Agent，Codex CLI 是一个很好的起点。它轻量、开源、免费（使用已有订阅），而且功能强大。

快去试试吧：

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

本文发布于 2026 年 6 月 16 日。Codex CLI 仍在快速迭代中，功能可能会有所变化，请以官方文档为准。