OpenAI Codex CLI：完整安装与配置指南 (2026)

OpenAI Codex CLI：2026 完整设置指南

OpenAI 的 Codex CLI 是一款命令行 AI 编程智能体（Agent），它可以读取你的代码库、编写和编辑文件、运行 Shell 命令，并迭代化地解决编程任务。你可以把它想象成一个生活在终端里的 AI 结对编程伙伴。与基于 IDE 的工具不同，Codex CLI 通过文本界面操作，这使得它速度极快、可脚本化，并且支持通过 SSH 运行。

本指南涵盖了从安装到高级使用模式的所有内容。

什么是 Codex CLI？

Codex CLI 是 OpenAI 推出的开源终端编程智能体。它利用 OpenAI 的模型（主要是 o4-mini 和 GPT-4o）来理解你的代码库并执行多步骤任务。核心功能包括：

• 文件读写 —— 它可以浏览你的项目并修改文件。
• Shell 命令执行 —— 它可以运行测试、安装包以及执行构建命令。
• 多步推理 —— 它可以跨多个文件规划并执行复杂的任务。
• 沙盒执行 —— 为了安全起见，命令会在沙盒环境中运行。
• 对话上下文 —— 它在整个会话期间保持上下文连贯。

前置条件

在安装 Codex CLI 之前，请确保你已具备：

要求	最低版本	检查命令
Node.js	22+	node --version
npm	9+	npm --version
Git	2.0+	git --version
OpenAI API key	--	platform.openai.com/api-keys

安装

通过 npm 安装

npm install -g @openai/codex

验证安装

codex --version

设置 API Key

Codex CLI 需要 OpenAI API key。请将其设置为环境变量：

# 添加到你的 shell 配置文件 (~/.bashrc, ~/.zshrc 等)
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"

重新加载你的 shell：

source ~/.zshrc  # 或 ~/.bashrc

验证 Key 是否设置成功：

echo $OPENAI_API_KEY

基础用法

交互模式

在你的项目目录中启动 Codex CLI 交互模式：

cd /path/to/your/project
codex

你会看到一个提示符，可以在其中输入自然语言指令：

> Fix the failing tests in the auth module

Codex 将分析测试失败的原因，读取相关文件并提出修复方案。

单次执行模式

无需进入交互模式即可运行单条指令：

codex "add input validation to the signup endpoint"

管道输入

将内容通过管道传输给 Codex 进行分析：

cat error.log | codex "explain these errors and suggest fixes"
git diff HEAD~3 | codex "write a changelog entry for these changes"

配置

配置文件

在 ~/.codex/config.json 创建配置文件：

{
  "model": "o4-mini",
  "approval_mode": "suggest",
  "sandbox": "docker"
}

项目级配置

在项目根目录创建一个 codex.md 文件，为 Codex 提供项目上下文：

# Project: MyApp

## Tech Stack
- TypeScript, React, Next.js
- PostgreSQL with Prisma ORM
- Tailwind CSS

## Conventions
- Use functional components with hooks
- Use `pnpm` as the package manager
- Tests go in `__tests__/` directories next to source files
- Use kebab-case for file names

## Important
- Never modify files in the `migrations/` directory directly
- Always run `pnpm test` after making changes
- Environment variables are in `.env.local` (do not commit)

Codex 会自动读取此文件，并将其作为每次交互的上下文。

审批模式 (Approval Modes)

Codex CLI 拥有三种审批模式，用于控制智能体的自主权：

模式	文件编辑	Shell 命令	适用场景
suggest	需要审批	需要审批	学习、代码审查
auto-edit	自动执行	需要审批	信任的文件修改
full-auto	自动执行	自动执行	脚本编写、CI 流水线

在启动时设置模式：

# Suggest 模式（最安全，默认值）
codex --approval-mode suggest "refactor the auth module"

# Auto-edit 模式（自动批准文件修改，命令执行需询问）
codex --approval-mode auto-edit "add unit tests for the User model"

# Full-auto 模式（全自动批准）
codex --approval-mode full-auto "fix all ESLint errors"

实践用例

示例 1：修复失败的测试

codex "run the tests, identify failures, and fix them"

Codex 将会：

1. 运行你的测试套件以识别失败项。
2. 读取失败的测试文件和源文件。
3. 分析根本原因。
4. 进行针对性修复。
5. 重新运行测试以验证。

示例 2：添加新功能

codex "add a rate limiting middleware to the Express API using express-rate-limit. \
Limit to 100 requests per 15 minutes per IP. Add tests."

示例 3：重构代码

codex "refactor the database queries in src/services/ to use the repository pattern. \
Keep the existing tests passing."

示例 4：代码审查

git diff main | codex "review this diff for bugs, security issues, and style problems"

示例 5：文档编写

codex "generate JSDoc comments for all exported functions in src/utils/"

示例 6：调试

codex "the /api/users endpoint returns 500 when the email contains a plus sign. \
Find and fix the bug."

高级用法

在 CI/CD 中使用

Codex CLI 可以以非交互模式在 CI/CD 流水线中运行：

# .github/workflows/codex-fix.yml
name: Auto-fix lint errors
on:
  push:
    branches: [main]

jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm install -g @openai/codex
      - run: codex --approval-mode full-auto "fix all ESLint errors and format with Prettier"
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      - run: git diff
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "fix: auto-fix lint errors via Codex CLI"

自定义系统提示词

为特定任务覆盖默认系统提示词：

codex --system-prompt "You are a security auditor. Review code for vulnerabilities only." \
  "audit the authentication flow"

模型选择

根据任务复杂度选择模型：

# 快速、低成本任务
codex --model o4-mini "fix the typo in the README"

# 复杂推理任务
codex --model o3 "redesign the caching layer to handle cache stampedes"

沙盒选项

Codex 支持不同的沙盒策略：

# Docker 沙盒（推荐用于 full-auto 模式）
codex --sandbox docker "install dependencies and run the test suite"

# 禁用网络的沙盒
codex --sandbox network-disabled "refactor the parser module"

# 无沙盒（请谨慎使用）
codex --sandbox none "run the deployment script"

Codex CLI 与其他 CLI 工具对比

功能	Codex CLI	Claude Code	Aider
提供商	OpenAI	Anthropic	多供应商支持
默认模型	o4-mini	Claude Sonnet	可配置
文件编辑	是	是	是
Shell 命令	是 (沙盒化)	是	受限
审批模式	3 种模式	逐工具审批	自动/手动
开源	是	否	是
MCP 支持	否	是	否
Git 集成	基础	高级	高级
价格	API 使用费	API 使用费	免费 (自带 Key)

成本管理

Codex CLI 根据 OpenAI API token 使用量计费。以下是粗略的成本指南：

任务类型	估计成本	模型
简单修复 (1-2 文件)	$0.01-0.05	o4-mini
功能添加 (3-5 文件)	$0.05-0.20	o4-mini
复杂重构 (10+ 文件)	$0.20-1.00	o4-mini
架构重新设计	$1.00-5.00	o3

降低成本的建议

1. Prompt 描述要具体。 模糊的指令会导致更多的往返沟通。
2. 大多数任务使用 o4-mini。 它能很好地处理 90% 的编程任务。
3. 将大任务拆分为小任务。 每个任务都会以新鲜的上下文开始。
4. 使用 codex.md 文件。 良好的项目上下文可以减少探索性的文件读取。

故障排除

"Command not found: codex"

# 检查是否已安装
npm list -g @openai/codex

# 重新安装
npm install -g @openai/codex

# 检查你的 PATH 环境变量
echo $PATH

"Invalid API key"

# 验证你的 Key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | head -c 200

Codex 进行了错误的修改

• 使用 suggest 模式，以便在应用修改前进行审查。
• 在你的 codex.md 项目文件中添加更多上下文。
• 描述指令时更加具体。
• 将复杂的任务拆分为更小、更集中的步骤。

Docker 沙盒问题

# 确保 Docker 正在运行
docker ps

# 拉取 Codex 沙盒镜像
docker pull openai/codex-sandbox:latest

构建 AI 驱动的应用

Codex CLI 在编写代码方面表现卓越，但如果你的应用需要生成图像、视频、音频或数字人，你会在代码之外需要媒体生成 API。Hypereal AI 提供了一个统一的 AI 媒体生成 API，你可以将其集成到由 Codex CLI 构建的项目中，从而在同一个工作流中实现智能代码生成和 AI 驱动的媒体创作。

总结

OpenAI Codex CLI 是一款强大的终端编程智能体。通过 npm install -g @openai/codex 安装，设置你的 OPENAI_API_KEY，并在项目中创建一个 codex.md 文件来提供上下文。学习时使用 suggest 模式，受信任的修改使用 auto-edit，而脚本和 CI 流水线则使用 full-auto。对于大多数任务，o4-mini 在速度、质量和成本之间提供了最佳平衡。