`exec` 命令入门 —— 沙箱自主编码实战

简介

如果说前文的安装认证是"准备好工具"，那么本篇就是"第一次使用工具"。codex exec（简称 exec 命令）是 Codex CLI 最核心、最高频使用的命令——它让你用一句自然语言指令，驱动 AI 在沙箱环境中自主完成编码任务。

不同于传统编码需要你先创建文件、编写代码、运行测试，exec 命令将整个流程自动化。你只需要告诉 AI "做什么"，它会自己决定 "怎么做"。本文将带你深入了解这个强大的命令，从基础用法到输出解读，助你快速上手。

一、`exec` 命令的基本语法

1.1 命令格式

bash

codex exec [选项] <任务描述>

或者更简短的写法：

bash

codex <任务描述>

当不指定子命令时，默认就是 exec 模式。

1.2 最简单的用法

bash

codex "写一个 Python 脚本，计算并输出前 20 个斐波那契数"

就这么简单。不需要创建文件，不需要编写代码，甚至不需要打开编辑器。Codex CLI 会：

在沙箱环境中创建所需的文件
编写 Python 代码
运行脚本验证结果
将最终文件输出到你的工作目录

1.3 常用选项

bash

# 指定模型
codex --model o3 "编写一个快速排序算法"

# 附加上下文文件
codex --file requirements.txt "分析这个项目的依赖关系"

# 详细输出模式
codex -v "解释这段代码的作用"

# 指定输出文件
codex --output result.py "用 Python 实现冒泡排序"

# 自定义指令
codex --custom-instructions "始终使用 TypeScript" "创建一个用户认证模块"

选项	简写	说明
`--model <model>`	`-m`	指定使用的模型（如 o3、o4-mini）
`--file <path>`	`-f`	附加文件作为上下文
`--verbose`	`-v`	显示详细输出
`--output <path>`	`-o`	指定输出文件路径
`--custom-instructions <text>`	-	添加自定义系统指令
`--sandbox <mode>`	-	指定沙箱模式（ask/full-auto/yolo）
`--max-turns <n>`	-	限制最大对话轮数
`--timeout <seconds>`	-	设置执行超时时间

二、沙箱自主编码：理解背后的机制

2.1 什么是沙箱？

exec 命令最核心的概念就是 沙箱（Sandbox）。沙箱是一个隔离的、安全的执行环境，AI 在这里可以：

✅ 创建、编辑、删除文件
✅ 运行代码和命令
✅ 安装软件包（在沙箱内）
✅ 访问网络（受限）
❌ 访问你的真实文件系统（超出工作目录范围）
❌ 执行危险操作（如格式化磁盘）

2.2 自主编码的完整生命周期

当你执行 codex "创建待办事项 API" 时，后台发生了以下过程：

text

┌─────────────────────────────────────────────────┐
│              exec 命令执行流程                    │
├─────────────────────────────────────────────────┤
│                                                 │
│  1. 解析任务                                      │
│     ↓                                            │
│     AI 分析任务描述，理解需求                        │
│     ↓                                            │
│  2. 规划方案                                      │
│     ↓                                            │
│     决定需要创建哪些文件，使用什么技术栈               │
│     ↓                                            │
│  3. 创建文件                                      │
│     ↓                                            │
│     在沙箱中创建项目结构                            │
│     ↓                                            │
│  4. 编写代码                                      │
│     ↓                                            │
│     生成代码内容并写入文件                           │
│     ↓                                            │
│  5. 执行验证                                      │
│     ↓                                            │
│     运行测试、检查语法错误、验证输出                  │
│     ↓                                            │
│  6. 迭代修复                                      │
│     ↓                                            │
│     如果有错误，自动修复并重新验证                    │
│     ↓                                            │
│  7. 输出结果                                      │
│     ↓                                            │
│     将沙箱中的文件同步到工作目录                     │
│                                                 │
└─────────────────────────────────────────────────┘

2.3 自主编码的能力边界

理解 AI 能做什么、不能做什么非常重要：

能做	不能做
创建和编辑任何文本文件	直接操作你的真实系统（沙箱隔离）
运行代码并查看输出	访问工作目录外的文件
安装 npm/pip 包（沙箱内）	发送未经授权的请求
读取工作目录中的文件	执行特权操作
运行 Git 命令	持久化沙箱内的状态（执行结束后清除）

三、实战案例

3.1 案例一：生成单个脚本文件

任务：创建一个 Python 脚本，读取 CSV 文件并生成数据统计报告。

bash

codex "创建一个 Python 脚本 data_report.py，它能读取 CSV 文件并输出：行数、列数、每列的数据类型、缺失值统计、数值列的基本统计信息（均值、中位数、标准差）。使用 pandas 实现。"

执行输出：

text

🤖 Codex is working...

📝 Step 1/4: 分析任务需求
   需要创建一个数据处理脚本，使用 pandas 库

📝 Step 2/4: 编写代码
   ✓ 创建 data_report.py

📝 Step 3/4: 创建示例数据
   ✓ 创建 sample_data.csv 用于测试

📝 Step 4/4: 验证运行
   ✓ 脚本运行成功

✅ Task completed! Files created:
   - data_report.py (156 lines)
   - sample_data.csv

生成的 data_report.py 内容：

python

#!/usr/bin/env python3
"""CSV 数据统计报告生成器"""

import pandas as pd
import sys

def generate_report(filepath: str) -> None:
    """读取 CSV 文件并生成统计报告"""
    df = pd.read_csv(filepath)

    print(f"{'='*50}")
    print(f"CSV 数据统计报告: {filepath}")
    print(f"{'='*50}")

    print(f"\n📊 基本信息:")
    print(f"   行数: {len(df)}")
    print(f"   列数: {len(df.columns)}")

    print(f"\n📋 列数据类型:")
    for col in df.columns:
        print(f"   {col}: {df[col].dtype}")

    print(f"\n⚠️ 缺失值统计:")
    missing = df.isnull().sum()
    for col, count in missing.items():
        if count > 0:
            print(f"   {col}: {count} ({count/len(df)*100:.1f}%)")

    print(f"\n📈 数值列统计:")
    numeric_cols = df.select_dtypes(include=['number']).columns
    if len(numeric_cols) > 0:
        stats = df[numeric_cols].describe()
        print(stats.to_string())
    else:
        print("   无数值列")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: python data_report.py <csv_file>")
        sys.exit(1)
    generate_report(sys.argv[1])

3.2 案例二：多文件项目生成

任务：创建一个包含模型、服务和测试的 Node.js 项目。

bash

codex "创建一个 Node.js 项目，包含以下结构：
- src/models/User.js（用户模型，含 name、email、age 字段和验证方法）
- src/services/userService.js（用户服务，含 CRUD 操作）
- tests/userService.test.js（使用 Jest 的测试文件）
- package.json（配置 Jest 和 ES modules）
所有代码使用 ES6 语法，包含 JSDoc 注释。"

执行输出：

text

🤖 Codex is working...

📝 Step 1/5: 分析项目结构
   需要创建 4 个文件，构建完整的项目骨架

📝 Step 2/5: 创建 package.json
   ✓ 配置 Jest 和 ES modules

📝 Step 3/5: 编写 User 模型
   ✓ 创建 src/models/User.js

📝 Step 4/5: 编写用户服务
   ✓ 创建 src/services/userService.js

📝 Step 5/5: 编写测试并运行
   ✓ 创建 tests/userService.test.js
   ✓ 测试全部通过 (5/5)

✅ Task completed! Files created:
   - package.json
   - src/models/User.js (42 lines)
   - src/services/userService.js (78 lines)
   - tests/userService.test.js (95 lines)

3.3 案例三：代码重构

任务：重构现有代码。

bash

# 先查看当前目录的文件
ls -la

# 对现有文件进行重构
codex "将 index.js 中的回调函数重构为 async/await 风格，并添加错误处理。保持功能不变。"

执行输出：

text

🤖 Codex is working...

📝 Step 1/3: 读取现有代码
   ✓ 分析 index.js (234 lines)

📝 Step 2/3: 重构代码
   ✓ 将所有回调转换为 async/await
   ✓ 添加 try-catch 错误处理
   ✓ 保持原有功能不变

📝 Step 3/3: 验证功能
   ✓ 代码语法检查通过
   ✓ 功能测试通过

✅ Task completed! Files modified:
   - index.js (refactored: 234 → 189 lines)

3.4 案例四：Bug 修复

任务：让 AI 自动修复 Bug。

bash

codex "运行 npm test，如果有任何测试失败，请分析错误原因并修复代码，直到所有测试通过。"

这个命令体现了 Codex CLI 的强大之处——它不仅是"生成代码"，而是"运行-分析-修复-验证"的完整闭环。

四、单次执行模式详解

4.1 什么是单次执行？

exec 命令默认是单次执行模式：接收一个任务描述，完成后退出。这与交互式模式（直接运行 codex 进入对话）不同。

bash

# 单次执行模式 —— 执行完就退出
codex "创建一个 hello.py 文件"

# 交互式模式 —— 保持对话
codex
>>> 创建一个 hello.py 文件
>>> 现在添加一个 say_hello 函数
>>> 退出

4.2 单次执行的优势

优势	说明
可脚本化	可以写入 shell 脚本、Makefile、CI 流水线
可重复	相同的输入产生相同的结果（确定性模型）
可组合	多个 `codex exec` 可以串联执行
节省资源	不需要维持交互会话

4.3 单次执行的典型场景

bash

# 场景 1：快速生成样板代码
codex "创建一个 Express.js 服务器，监听 3000 端口，返回 'Hello World'"

# 场景 2：数据处理
codex "将 data.json 中的数据转换为 CSV 格式，保存到 output.csv"

# 场景 3：文档生成
codex "读取 src/ 目录下所有 .js 文件，生成 API 文档到 docs/api.md"

# 场景 4：代码检查
codex "检查当前目录下所有 Python 文件的 PEP8 合规性，输出报告"

五、输出解读

理解 Codex CLI 的输出是高效使用它的关键。让我们详细拆解：

5.1 标准输出结构

text

🤖 Codex is working...

这表示 AI 正在处理你的请求。

text

📝 Step 1/N: <步骤描述>
   ✓ <子操作>

每一步代表 AI 的一个决策或操作。N 表示总步骤数。AI 会根据任务复杂度自动决定步骤数量。

text

⚠️ <警告信息>
   尝试修复中...
   ✓ 修复成功

遇到警告或错误时，AI 会尝试自主修复。

text

✅ Task completed!

任务完成的标志。

text

Files created/modified:
   - filename.ext (N lines)

列出所有创建或修改的文件及其行数。

5.2 不同沙箱模式下的输出差异

bash

# ask 模式（默认）—— 会在关键操作前询问
codex --sandbox ask "删除所有 .log 文件"
# 输出: ⚡ Action: Delete files ['app.log', 'error.log', 'debug.log']
# 输入: Approve? [Y/n]

# full-auto 模式 —— 不询问，直接执行
codex --sandbox full-auto "删除所有 .log 文件"
# 直接执行，无询问

# yolo 模式 —— 不仅自动执行，还允许更广泛的操作
codex --sandbox yolo "清理项目"
# 直接执行，权限更宽松

5.3 错误输出解读

bash

# 认证错误
❌ Error: No credentials found. Please run 'codex login' or set OPENAI_API_KEY.

# 沙箱错误
❌ Error: Sandbox execution failed.
   Details: Command 'pip install unknown-package' returned exit code 1.
   Try again with a different approach.

# Git 错误
❌ Error: Not a git repository.
   Run 'git init' in the current directory first.

# 超时错误
❌ Error: Task timed out after 120 seconds.
   Try breaking the task into smaller steps or increase timeout with --timeout.

# 模型错误
❌ Error: Model 'gpt-5' not found.
   Available models: o3, o4-mini, o3-pro

六、进阶技巧

6.1 管道操作

bash

# 将命令输出作为 Codex 的上下文
cat error.log | codex "分析这些错误日志，找出最常见的错误并提供修复建议"

# 与 Git 结合
git diff | codex "分析这个 diff，解释每个改动的意图"

6.2 多步骤流水线

bash

#!/bin/bash
# 自动化编码流水线

# 第一步：生成代码
codex "创建一个 Express REST API，包含 /users 的 CRUD 端点"

# 第二步：生成测试
codex "为 src/ 目录下的所有路由生成 Jest 测试"

# 第三步：运行测试并修复
codex "运行 npm test，修复所有失败的测试"

# 第四步：生成文档
codex "为所有 API 端点生成 OpenAPI/Swagger 文档"

# 第五步：Git 提交
git add .
git commit -m "$(codex "根据最近的改动生成一个 Git 提交信息，遵循 Conventional Commits 规范")"

6.3 使用 `--file` 提供上下文

bash

# 让 AI 参考现有文件来编写新代码
codex --file config.json --file schema.sql \
  "根据配置文件和数据库 schema，生成对应的 TypeScript 接口定义"

# 多个文件
codex -f src/app.js -f src/db.js \
  "添加一个缓存中间件，参考现有的数据库连接方式"

6.4 组合使用 `--model` 和 `--max-turns`

bash

# 简单任务用快速模型
codex --model o4-mini --max-turns 5 \
  "格式化这个 JSON 文件"

# 复杂任务用强模型
codex --model o3 --max-turns 50 \
  "设计并实现一个完整的身份认证系统，包含 JWT、刷新令牌、密码加密"

七、输出文件的管理

7.1 文件同步机制

Codex CLI 在沙箱中完成所有操作后，会将文件同步回你的工作目录：

text

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  工作目录     │ ──→ │   沙箱环境    │ ──→ │  工作目录     │
│  (你的文件)   │     │  (AI 操作)   │     │  (更新后)     │
└──────────────┘     └──────────────┘     └──────────────┘

7.2 避免覆盖的重要提示

Codex CLI 在写入文件时遵循以下规则：

如果文件不存在 → 创建新文件
如果文件已存在 → 覆盖（⚠️ 注意！）
沙箱内的临时文件 → 不自动同步（除非指定）

最佳实践：

bash

# 执行前先提交当前更改
git add . && git commit -m "保存当前状态"

# 再执行 codex
codex "重构用户认证模块"

# 查看改动
git diff

# 不满意可以回滚
git checkout .

总结

本文我们全面学习了 exec 命令的使用：

基本语法：codex exec "任务描述" 或简化为 codex "任务描述"
沙箱机制：AI 在隔离环境中自主编码，安全可控
完整生命周期：解析 → 规划 → 编码 → 验证 → 输出
实战案例：从单文件脚本到多文件项目、从代码生成到 Bug 修复
输出解读：理解每一步的输出含义，有效监控执行过程
进阶技巧：管道操作、多步骤流水线、文件上下文、模型选择

exec 命令是 Codex CLI 的核心武器，掌握了它，你就掌握了 AI 驱动编程的基本功。

下篇预告

下一篇我们将深入 沙箱模式详解。你将学习：

--full-auto 和 --yolo 两种自动模式的深入对比
沙箱的安全边界在哪里？什么操作会被阻止？
文件权限管理和安全策略配置
如何在安全性和便捷性之间找到平衡

敬请期待！