Codex CLI 快速入门：OpenAI 开源的终端 AI 编程助手

OpenAI 在 2025 年开源了 Codex CLI——一个运行在本地终端中的轻量级 AI 编程智能体（Coding Agent）。截至今日，这个 GitHub 仓库（openai/codex）已获得 10 万+ Star，成为开发者社区最受关注的 AI 工具之一。

Codex CLI 的核心定位是本地终端中的 AI 编程助手，它可以直接读取你的代码库、执行命令、修改文件，并有完善的安全沙箱机制来保护你的系统。不同于 VS Code / Cursor 中的 AI 补全插件，Codex CLI 是一个独立的终端工具，适合在 CI/CD 流程、远程服务器或者纯终端工作流的场景中使用。

本文将带你从零开始掌握 Codex CLI 的安装、认证和核心功能。

1. 安装 Codex CLI

Codex CLI 支持 macOS、Linux 和 Windows 三大平台，提供了多种安装方式。

macOS / Linux 一键安装

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

Windows 安装

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

包管理器安装

如果你偏好使用包管理器：

# npm 全局安装
npm install -g @openai/codex

# Homebrew（macOS）
brew install --cask codex

从 GitHub Release 下载

你也可以直接访问 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 并放到 $PATH 中。

安装完成后，在终端输入 codex 即可验证是否安装成功：

codex --version

2. 认证登录

运行 codex 后会进入交互式界面，选择 Sign in with ChatGPT 即可通过浏览器完成认证。Codex CLI 支持以下 ChatGPT 订阅计划：

• ChatGPT Plus / Pro
• ChatGPT Business / Edu
• ChatGPT Enterprise

如果你需要使用 API Key，可以通过环境变量配置：

export OPENAI_API_KEY="sk-..."

但推荐使用 ChatGPT 账号登录，因为 API Key 方式需要额外的配额设置。详细认证文档可参考 developers.openai.com/codex/auth。

3. 交互模式基础用法

认证完成后再次运行 codex，你会进入一个 TUI（终端用户界面）交互环境。在这个环境中，你可以直接用自然语言描述编程任务，例如：

帮我给 src/utils.ts 中的 fetchData 函数添加错误处理和超时机制

Codex CLI 会自动：

阅读你的代码上下文

给出修改方案

在你的确认下执行文件操作和命令

交互模式下的核心操作流程是 SEE → THINK → ACT：先读取代码，再思考方案，最后执行操作。每一步你都可以审查和介入。

便捷选项

# 指定工作目录
codex --workdir ./my-project

# 从会话文件恢复
codex --session <session-id>

4. 非交互模式：codex exec

在很多场景下，你不需要打开 TUI 界面，而是希望直接在命令行中一次性运行 Codex。这时 codex exec 就派上用场了。

# 直接让 Codex 执行一个任务
codex exec "为 src/app.py 写单元测试"

# 从 stdin 传入指令
echo "修复 eslint 报错" | codex exec

# 配合管道使用
cat requirements.txt | codex exec "安装这些 Python 依赖并验证"

codex exec 非常适合集成到 CI/CD 流程中：

# GitHub Actions 示例
- name: Code Review
  run: codex exec "审查 PR 中的代码变更，检查安全问题"

在非交互模式下，Codex 会默认进行文件操作，但你可以通过配置文件控制权限级别。

5. AGENTS.md：定制 Codex 的行为

AGENTS.md 是 Codex CLI 最重要的配置文件之一。将 AGENTS.md 文件放在项目根目录中，Codex 就会在运行时自动读取并遵循其中的规则。

# AGENTS.md

## 技术栈
- 后端使用 Python 3.12 + FastAPI
- 数据库使用 PostgreSQL + SQLAlchemy
- 前端使用 React + TypeScript

## 编码规范
- 所有函数必须包含类型注解
- 使用 `black` 格式化代码，行宽 100
- 测试使用 pytest，覆盖率不低于 80%

## 禁止事项
- 不要直接修改 `migrations/` 目录下的文件
- 不要使用 `print()` 调试，请使用 `logging` 模块

你也可以在 AGENTS.md 中定义斜杠命令（Slash Commands）和自定义技能（Skills），让 Codex 在特定场景下自动加载专业能力。

> Codex 自身的仓库中也有一个 300+ 行的 AGENTS.md，详细定义了 Rust 开发规范、TUI 样式约定、测试组织方式等。这个文件本身就是一个很好的学习范例。

6. 安全沙箱机制

Codex CLI 默认在沙箱环境中执行 AI 生成的命令，确保不会对系统造成不可逆的破坏。沙箱的安全级别分为以下几档：

| 模式 | 说明 |
|------|------|
| readonly | 只读模式，AI 可以读取文件但不能修改 |
| workspace | 允许在项目目录内修改文件 |
| danger-full-access | 完全访问权限，不推荐日常使用 |

你可以通过 codex config 查看和修改安全设置：

# 查看当前配置
codex config get sandbox_mode

# 设置为工作区模式
codex config set sandbox_mode workspace

此外，Codex 在执行每个高风险操作（如删除文件、执行脚本、网络请求）前都会请求用户确认，你可以选择批准（approve）、拒绝（deny）或仅本次放行（allow once）。这套审批机制确保你始终对 AI 的行为拥有最终控制权。

7. 自定义技能（Skills）

技能（Skills）是 Codex CLI 的另一个核心扩展能力。你可以为项目创建 .codex/skills/ 目录，在其中定义专项技能文件，让 Codex 在匹配到特定任务时自动加载。

典型的技能文件结构：

.codex/
  skills/
    deploy-to-aws/
      SKILL.md

SKILL.md 的内容通常包括：

• 触发条件：描述什么场景下应该使用这个技能
• 操作步骤：明确的操作指令和约束
• 上下文信息：必要的环境变量、路径等

例如，一个 AWS 部署技能可以是：

# AWS Lambda 部署技能

## 触发条件
当用户提到"部署到 AWS"、"更新 Lambda"、"发布"时使用此技能

## 操作步骤
1. 运行 `pytest` 确保所有测试通过
2. 运行 `sam build` 构建 Lambda 打包
3. 运行 `sam deploy --guided` 执行部署
4. 验证部署结果

## 注意事项
- 部署前必须确认当前 Git 分支是 `main`
- 不要在周五下午 5 点后执行部署

8. 斜杠命令（Slash Commands）

Codex CLI 内置了一套斜杠命令，让你在交互界面中快速执行特定操作：

| 命令 | 功能 |
|------|------|
| /help | 显示帮助信息 |
| /init | 在当前目录初始化 Codex 配置 |
| /clear | 清除当前会话历史 |
| /diff | 显示 AI 建议的代码变更差异 |
| /model | 切换使用的 AI 模型 |
| /memory | 查看和管理持久化记忆 |
| /export | 导出当前会话记录 |

你还可以在 AGENTS.md 或 .codex/skills/ 中自定义斜杠命令，将它们绑定到特定的技能或操作。

9. 代码编辑器集成

虽然 Codex CLI 本身是一个独立的终端工具，但 OpenAI 也提供了 IDE 集成方案。在 VS Code、Cursor 或 Windsurf 中安装 Codex 扩展后，你可以直接从编辑器内调用 Codex CLI 的能力。

如果你想要桌面应用的体验，可以运行：

codex app

这会启动 Codex 的桌面应用模式，提供更丰富的 UI 交互。

10. 配置文件概览

Codex CLI 使用 TOML 格式的配置文件 config.toml，支持多层级覆盖：

• 全局级别：~/.codex/config.toml
• 项目级别：<project>/.codex/config.toml
• 企业管控级别：requirements.toml（管理员设置，用户不可覆盖）

# config.toml 示例
[model]
default = "gpt-4o"

[security]
sandbox_mode = "workspace"
auto_approve = false

[hooks]
pre_exec = ["echo 'Codex 正在执行任务...'"]
post_exec = ["notify-send 'Codex 任务完成'"]

配置文件还支持生命周期钩子（Lifecycle Hooks），你可以在 AI 执行任务前后自动触发自定义脚本，这对 CI/CD 集成尤其有用。

总结

Codex CLI 代表了 AI 编程助手的一个重要方向：本地运行、终端优先、安全可控。它不仅是 GitHub Copilot、Cursor 等 IDE 内 AI 工具的补充，更是一个可以深度集成到命令行工作流、自动化脚本和 CI/CD 管道中的强大编程智能体。

从安装到认证，从交互模式到 codex exec 非交互模式，从 AGENTS.md 配置到安全沙箱和自定义技能——希望通过本文，你已经对 Codex CLI 有了全面的了解，并能够立即在工作中用起来。

如果你想深入学习，推荐阅读：

• Codex 官方文档
• GitHub 仓库 openai/codex
• Codex AGENTS.md 实战示例