Codex: Codex 基础入门
最后更新：2026-08-31
安装完成后，让我们开始实际使用 Codex。本节带你完成第一次任务提交，掌握基本操作流程。
📋 前置知识：已完成 Codex 安装与登录（见上一课）
1. 你将学到
- 第一次运行 Codex
- 提交任务的基本流程
- 查看与审查结果
- 常用交互操作
2. 第一次运行
(1) 准备项目
BASH
# 创建测试项目
mkdir my-first-codex && cd my-first-codex
# 初始化一个简单的 Python 项目
echo 'def greet(name):\n return f"Hello, {name}!"' > app.py
(2) 启动 Codex
BASH
codex
首次启动会看到欢迎界面，选择 Yes, continue 开始。
(3) 提交第一个任务
在输入框中输入：
TEXT
📖 仅展示
为 app.py 添加单元测试，使用 pytest 框架
Codex 的执行过程：
TEXT
📖 仅展示
1. Reading app.py...
2. Creating test_app.py with pytest test cases
3. Running: pytest test_app.py
4. All tests passed ✓
▶ 示例 1: Bob 的第一次使用
Bob 是一名后端开发者，他第一次使用 Codex：
BASH
cd bob-flask-api
codex
# Bob 输入：
# "为所有 API 端点添加输入验证，使用 marshmallow 库"
# Codex 输出：
# → Scanning 15 API endpoint files...
# → Installing marshmallow...
# → Creating schemas/ directory...
# → Adding validation to 15 endpoints...
# → Running tests: 34/34 passed ✓
3. 基本操作流程
(1) 完整工作流
graph TB
A[进入项目目录] --> B[启动 codex]
B --> C[输入任务描述]
C --> D[Codex 分析理解]
D --> E[执行操作]
E --> F[查看结果]
F --> G{满意?}
G -->|否| H[追加指令]
H --> D
G -->|是| I[结束会话]
(2) 任务提交格式
TEXT
📖 仅展示
# 好的任务描述
codex "修复 user.py 中的登录 bug，确保测试通过"
codex "将 utils.js 重构为 TypeScript，保持功能一致"
codex "为 orders API 添加分页功能，每页 20 条"
# 不好的任务描述
codex "帮我写代码"
codex "修复 bug"
codex "优化一下"
(3) 有效 Prompt 原则
| 原则 | 说明 | 示例 |
|---|---|---|
| 明确目标 | 说清楚要做什么 | "添加 JWT 认证"而非"改下认证" |
| 提供上下文 | 引用相关文件 | "参考 auth.py 的风格" |
| 包含验证 | 说明如何验证结果 | "确保所有测试通过" |
| 分步执行 | 复杂任务拆步骤 | "第一步：创建模型；完成后告诉我" |
4. 交互操作
(1) 常用操作
| 操作 | 说明 |
|---|---|
| 输入文字 | 提交新任务或追加指令 |
Y / N |
确认或拒绝 Codex 的操作 |
Ctrl+C |
中断当前操作 |
/help |
查看帮助信息 |
/clear |
清空对话历史 |
/new |
开始新会话 |
(2) 追加指令
Codex 完成任务后，可以继续追加：
TEXT
📖 仅展示
# 第一次任务
> 为 app.py 添加日志功能
# 追加
> 把日志级别改为 DEBUG
# 继续追加
> 把日志输出到文件而非控制台
▶ 示例 2: Alice 的迭代式开发
TEXT
📖 仅展示
# Alice 逐步完善功能
> 创建一个 FastAPI 项目骨架
✓ Created main.py, routers/, models/
> 添加用户注册 API
✓ Created /api/register endpoint
> 为注册 API 添加邮箱验证
✓ Added email verification flow
> 写集成测试
✓ Created test_register.py, 5 tests passed
5. 查看与审查结果
(1) 审查代码变更
Codex 修改文件后，会显示 diff 视图：
DIFF
- def greet(name):
- return f"Hello, {name}!"
+ def greet(name: str) -> str:
+ """Greet a person by name."""
+ if not name:
+ raise ValueError("Name cannot be empty")
+ return f"Hello, {name}!"
(2) 检查测试结果
BASH
# Codex 自动运行测试后显示结果
Running pytest test_app.py...
✓ test_greet_normal - PASSED
✓ test_greet_empty - PASSED
✓ test_greet_type_hint - PASSED
3 passed, 0 failed
(3) 确认或回滚
- 确认：接受 Codex 的修改，继续下一步
- 回滚：
git checkout -- .撤销所有未提交的修改
6. 多文件操作
▶ 示例 3: 项目级重构
TEXT
📖 仅展示
> 将 Express 项目迁移到 Fastify，替换所有路由定义，确保测试通过
# Codex 执行过程：
# → Scanning 45 files for Express patterns
# → Converting route definitions (32 routes)
# → Updating middleware (8 files)
# → Running test suite: 89/89 passed ✓
# → Updating package.json
# → Final test run: 89/89 passed ✓
7. 实用技巧
| 技巧 | 说明 |
|---|---|
用 git init 初始化项目 |
方便回滚 Codex 的修改 |
| 先跑测试再提交任务 | 确保基线正常 |
| 小步提交 | 一次只做一个任务 |
| 审查每一处修改 | 不要盲目接受 |
| 善用追加指令 | 迭代比一次到位更可靠 |
❓ 常见问题
Q Codex 修改了错误的文件怎么办？
A 使用
git checkout -- <file> 撤销特定文件，或 git checkout -- . 撤销所有修改。这就是为什么建议先用 git init 初始化项目。Q 任务执行时间太长怎么办？
A 按
Ctrl+C 中断当前操作，然后用更具体的指令重新提交，或把大任务拆分为小步骤。Q Codex 理解错了我的意图怎么办？
A 直接追加澄清指令，比如"我指的是 X 而不是 Y"，Codex 会根据上下文修正。
Q 可以用中文和 Codex 交流吗？
A 可以，Codex 支持多语言。但英文通常效果更好，复杂任务建议用英文描述。
Q 每次都要从零开始解释项目吗？
A 不用。Codex 会自动读取项目文件作为上下文。同一会话内的历史对话也会保留。
📖 小节
- 基本流程：进入项目 → 启动 codex → 输入任务 → 审查结果
- 有效 Prompt：明确目标 + 提供上下文 + 包含验证
- 善用追加指令进行迭代式开发
- 用 git 管理项目，方便回滚错误修改
- 小步提交，审查每一处变更
📝 作业
- 基础题（难度⭐）：创建一个简单项目，用 Codex 为其添加单元测试。
- 进阶题（难度⭐⭐）：用迭代式方式完成一个功能：先创建骨架 → 添加功能 → 完善错误处理。
- 挑战题（难度⭐⭐⭐）：故意给 Codex 一个模糊的指令，观察它如何理解，然后用追加指令修正结果，记录整个过程。
