Codex 入门：终端 AI 编码代理的安装与初体验

TL;DR: OpenAI Codex 是一个基于终端的 AI 编码代理，能够直接在你的开发环境中执行命令、编辑文件、运行测试。本教程将带你完成从安装到运行第一个自主任务的完整流程，并深入讲解审批模式的安全机制。你将学会如何用自然语言驱动 Codex 完成代码生成、调试和项目初始化等实际开发任务。

引言

2026 年的开发者工具生态已经发生了根本性变化。终端 AI 编码代理不再是实验性的玩具，而是成为了现代开发工作流的核心组件。OpenAI Codex 作为这一领域的标杆产品，在 2026 年 6 月的版本中引入了多项关键改进：更快的上下文加载速度（平均 1.2 秒）、改进的审批模式 UI，以及对 200+ 编程语言的原生支持。

本教程是五部分系列的第一篇，面向完全新手。你将学到：

如何正确安装和配置 Codex CLI
如何运行你的第一个自主编码任务
如何配置和使用审批模式来控制 AI 行为
常见陷阱及最佳实践

安装 Codex CLI

系统要求

在开始之前，确保你的环境满足以下条件：

要求	最低版本	推荐版本
Python	3.10+	3.12+
Node.js	18.0+	22.0+
Git	2.30+	2.45+
操作系统	macOS 12 / Ubuntu 22.04 / Windows 11 (WSL2)	macOS 14 / Ubuntu 24.04
磁盘空间	500MB	2GB (含模型缓存)

安装步骤

方法一：使用 pip 安装（推荐）

# 创建虚拟环境避免污染全局 Python
python3 -m venv codex-env
source codex-env/bin/activate

# 安装 Codex CLI
pip install openai-codex-cli==2.1.4

# 验证安装
codex --version
# 输出: Codex CLI v2.1.4 (build 2026-06-01)

方法二：使用 Homebrew（macOS）

brew tap openai/codex
brew install codex-cli

配置 API 密钥

Codex 需要 OpenAI API 密钥才能工作。获取密钥后，通过以下方式配置：

# 方式 1：环境变量（推荐用于 CI/CD）
export OPENAI_API_KEY="sk-your-key-here"

# 方式 2：配置文件
codex config set api_key "sk-your-key-here"

# 验证配置
codex config show
# 输出示例：
# api_key: sk-****-abcd
# model: gpt-4o-codex-2026-06-01
# approval_mode: semi
# max_tokens: 4096

重要安全提示：永远不要将 API 密钥提交到版本控制系统。建议使用 .env 文件或密钥管理服务（如 HashiCorp Vault）。

理解 Codex 的架构

在深入使用之前，理解 Codex 的工作原理至关重要。Codex 不是一个简单的聊天机器人，而是一个自主编码代理，它能够：

理解上下文：分析你的项目结构、文件内容和 Git 历史
规划行动：生成多步骤的执行计划
执行操作：直接修改文件、运行命令、创建新文件
验证结果：运行测试并检查输出

这种架构带来了巨大的生产力提升，但也要求我们建立适当的安全边界——这正是审批模式存在的意义。

第一个自主任务

让我们从最简单的任务开始：创建一个 Python 项目并自动生成基础代码。

任务：创建 REST API 脚手架

# 创建项目目录
mkdir my-first-codex-project
cd my-first-codex-project

# 初始化 Git 仓库
git init
git commit --allow-empty -m "Initial commit"

# 启动 Codex 会话
codex start

当你运行 codex start 时，会进入交互模式。终端会显示：

╭─────────────────────────────────────╮
│  Codex CLI v2.1.4                   │
│  Model: gpt-4o-codex-2026-06-01     │
│  Approval: semi-automatic           │
│  Context: 0 files, 0 tokens         │
╰─────────────────────────────────────╯

>

现在，输入你的第一个指令：

> 创建一个 FastAPI 项目，包含一个简单的用户 CRUD API。使用 SQLite 作为数据库，包含以下端点：
> - GET /users - 获取所有用户
> - POST /users - 创建用户
> - GET /users/{id} - 获取单个用户
> - PUT /users/{id} - 更新用户
> - DELETE /users/{id} - 删除用户

Codex 会开始分析任务并生成执行计划。你会看到类似这样的输出：

📋 计划：
1. 创建 requirements.txt（fastapi, uvicorn, sqlalchemy, pydantic）
2. 创建 database.py（SQLite 连接和会话管理）
3. 创建 models.py（User SQLAlchemy 模型）
4. 创建 schemas.py（Pydantic 请求/响应模型）
5. 创建 main.py（FastAPI 应用和路由）
6. 创建 test_main.py（基础测试）
7. 安装依赖并运行测试

🔧 执行步骤 1/7: 创建 requirements.txt

审批模式详解

在执行每个步骤之前，Codex 会等待你的审批（默认的 semi-automatic 模式）。你会看到：

🔍 建议操作：创建文件 requirements.txt
内容：
fastapi==0.115.0
uvicorn[standard]==0.30.0
sqlalchemy==2.0.31
pydantic==2.8.0

批准？[y/N/d/e]:
- y: 批准并执行
- N: 拒绝并跳过
- d: 查看差异
- e: 编辑建议

这种机制让你能够：

审查每个修改：确保 AI 生成的代码符合你的标准
拦截错误：防止 AI 执行危险操作（如删除文件）
提供反馈：通过编辑建议来指导 AI

完整执行示例

让我们批准所有步骤并观察结果。执行完成后，你的项目结构应该是：

my-first-codex-project/
├── requirements.txt
├── database.py
├── models.py
├── schemas.py
├── main.py
└── test_main.py

运行测试验证：

# 安装依赖
pip install -r requirements.txt

# 运行测试
python -m pytest test_main.py -v

# 预期输出：
# ============================== test session starts ==============================
# collected 5 items
#
# test_main.py::test_create_user PASSED
# test_main.py::test_get_users PASSED
# test_main.py::test_get_user PASSED
# test_main.py::test_update_user PASSED
# test_main.py::test_delete_user PASSED
#
# ============================== 5 passed in 2.34s ==============================

启动 API 服务器测试：

uvicorn main:app --reload
# 访问 http://localhost:8000/docs 查看 Swagger UI

审批模式配置详解

Codex 支持三种审批模式，每种模式适用于不同的使用场景：

模式	配置值	行为	适用场景
完全自动	`auto`	自动执行所有操作	CI/CD 管道、可信环境
半自动	`semi`	文件修改需审批，命令执行自动	日常开发（默认）
手动	`manual`	所有操作需审批	生产环境、敏感项目

配置方法：

# 设置半自动模式（默认）
codex config set approval_mode semi

# 设置手动模式（最安全）
codex config set approval_mode manual

# 设置完全自动模式（最快）
codex config set approval_mode auto

自定义审批规则

高级用户可以通过 .codexconfig.yaml 文件定义更细粒度的审批规则：

# .codexconfig.yaml
approval:
  mode: semi
  rules:
    # 自动批准测试文件的修改
    - pattern: "test_*.py"
      auto_approve: true
    # 自动批准 requirements 更新
    - pattern: "requirements*.txt"
      auto_approve: true
    # 手动批准所有配置文件
    - pattern: "*.yaml"
      auto_approve: false
    - pattern: "*.yml"
      auto_approve: false
    # 禁止删除操作
    - action: "delete"
      auto_approve: false
      require_confirmation: true

常见陷阱与解决方案

陷阱 1：上下文窗口溢出

当项目文件过多时，Codex 可能会超出上下文限制（当前为 128K tokens）。

症状：

⚠️ 上下文窗口已满 (128K/128K tokens)。部分文件将被忽略。

解决方案：

# 限制 Codex 关注的文件
codex start --include "src/**/*.py" --exclude "tests/**"

# 或者使用 .codexignore 文件
echo "node_modules/" >> .codexignore
echo "*.log" >> .codexignore
echo "dist/" >> .codexignore

陷阱 2：无限循环

AI 代理可能陷入修改-测试-失败的循环。

症状：Codex 反复修改同一文件但测试仍然失败。

解决方案：

# 设置最大迭代次数
codex config set max_iterations 10

# 使用 --timeout 参数设置超时
codex start --timeout 300

陷阱 3：依赖冲突

Codex 可能安装与现有项目冲突的依赖版本。

解决方案：

# 使用虚拟环境隔离
python3 -m venv .venv
source .venv/bin/activate

# 或者在配置中指定依赖约束
codex config set pip_constraint ">=1.0,<2.0"

性能优化技巧

1. 增量上下文加载

对于大型项目，使用增量上下文加载可以显著提升响应速度：

# 只加载最近修改的文件
codex start --recent-files 20

# 或者指定文件数量
codex start --max-context-files 50

2. 使用 Git 状态感知

Codex 会自动分析 Git 状态，优先处理未提交的更改：

# 查看 Codex 的 Git 感知状态
codex status
# 输出：
# Git branch: main
# Uncommitted changes: 3 files
# Last commit: 2 hours ago
# Active context: main.py, database.py

3. 批处理模式

对于非交互式任务，使用批处理模式：

# 从文件读取指令
echo "添加单元测试覆盖率达到 80%" | codex run --batch

# 或者使用管道
cat instructions.txt | codex run --batch --output result.json

关键要点

Codex 是代理而非聊天机器人：它直接操作你的文件系统，理解项目上下文，并执行多步骤计划
审批模式是安全基石：始终从 semi 模式开始，根据信任度逐步调整
上下文管理决定成败：使用 .codexignore 和 --include 参数控制 Codex 关注的文件范围
版本控制是保险：在使用 Codex 前确保 Git 工作区是干净的，以便回滚
测试验证不可跳过：始终让 Codex 运行测试来验证修改的正确性

常见问题 (FAQ)

Q: Codex CLI 和 GitHub Copilot 有什么区别？ A: Codex CLI 是一个自主编码代理，能够独立执行多步骤任务（如创建项目、重构代码、运行测试）。GitHub Copilot 主要提供代码补全建议。Codex CLI 更像是你的 AI 开发伙伴，而 Copilot 是 AI 打字助手。

Q: 免费额度够用吗？ A: 新用户有 $5 的免费 API 额度（约 500 次简单请求）。对于日常开发，建议购买 $20/月的开发者计划，包含 100 万 token 的处理量。

Q: Codex 会泄露我的代码吗？ A: OpenAI 不会使用你的代码进行训练（除非你明确选择加入）。所有 API 请求在传输和存储时都经过加密。建议敏感项目使用本地部署选项（需要企业版）。

Q: 如何处理 Codex 生成的低质量代码？ A: 使用审批模式审查每个修改。如果发现代码质量不达标，使用 e（编辑）选项修改建议，或者直接拒绝并重新描述需求。良好的提示词工程是获得高质量代码的关键。

Q: 可以在 CI/CD 中使用 Codex 吗？ A: 可以。使用 auto 模式配合环境变量 CODEX_CI=true，Codex 会自动处理所有操作。建议配合 Git 分支保护和代码审查流程使用。

下一步

在本教程中，你完成了 Codex CLI 的安装、配置，并成功运行了第一个自主编码任务。你已经掌握了审批模式的使用方法，理解了如何安全地控制 AI 代理的行为。

在第二部分中，我们将深入探讨：

高级提示词工程：如何编写精确的指令以获得最佳结果
多文件重构：使用 Codex 进行大规模代码重组
自定义工具集成：让 Codex 调用你的专属工具链

准备好提升你的开发效率了吗？继续阅读 Codex 进阶：高级提示词工程与多文件重构。

本文是 Codex 入门系列的第 1 部分。点击这里查看系列总目录。

Have questions? Join our Discord community or follow us on X.

Codex Deep Dive — Complete Developer Guide

Codex 入门：终端 AI 编码代理的安装与初体验

引言

安装 Codex CLI

系统要求

安装步骤

配置 API 密钥

理解 Codex 的架构

第一个自主任务

任务：创建 REST API 脚手架

审批模式详解

完整执行示例

审批模式配置详解

自定义审批规则

常见陷阱与解决方案

陷阱 1：上下文窗口溢出

陷阱 2：无限循环

陷阱 3：依赖冲突

性能优化技巧

1. 增量上下文加载

2. 使用 Git 状态感知

3. 批处理模式

关键要点

常见问题 (FAQ)

下一步