Codex exec 命令实战指南：用非交互模式驱动 AI 编程自动化

引言

在上一篇文章《Codex CLI 快速入门》中，我们介绍了 Codex CLI 的安装、登录和基本交互式使用。但 Codex 的真正威力远不止于此——它还提供了一个强大的非交互模式 codex exec，让你可以在脚本、CI/CD 流水线、以及各种自动化场景中调用 AI 编程能力。

本文将深入探讨 codex exec 命令的使用方法，通过实际案例展示如何将 AI 编程助手集成到你的日常工作流中，实现真正的编程自动化。

什么是 codex exec

codex exec 是 Codex CLI 提供的非交互式执行模式。与默认的 TUI 交互界面不同，exec 模式接收一段提示词（prompt），AI 模型会直接执行相应的操作并将结果输出到终端，整个过程无需人工介入，非常适合自动化场景。

这种模式特别适合以下几种场景：

• CI/CD 集成：在代码提交或 PR 时自动进行代码审查、生成测试用例
• 批量处理：对多个文件执行相同的重构或格式化操作
• 定时任务：定期检查代码质量并自动修复简单问题
• 脚本组合：将 Codex 的分析或生成结果作为下游命令的输入
• 项目脚手架：一键生成符合团队规范的项目结构和基础代码

基本用法

安装与登录

确保你已经安装了 Codex CLI。安装方式有两种：

# macOS / Linux — 官方安装脚本
curl -fsSL https://raw.githubusercontent.com/openai/codex/main/install.sh | bash

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

安装完成后进行认证：

codex login

这会打开浏览器完成 OpenAI 账号的授权流程。如果你在无头服务器上运行，可以使用 API Key 的方式：

codex login --api-key

exec 命令基础语法

codex exec "你的提示词" [选项]

举个最简单的例子——让 Codex 解释一个文件的作用：

codex exec "解释当前目录下 main.go 文件的核心逻辑和架构设计"

Codex 会读取文件内容、分析代码逻辑，然后将解读结果直接输出到终端。

常用选项一览

| 选项 | 说明 |
|------|------|
| --model <name> | 指定使用的模型，如 gpt-4o、gpt-4o-mini、o3-mini |
| --sandbox | 在沙箱模式下运行，隔离文件系统操作，避免影响宿主机 |
| --approval-mode <mode> | 审批模式：auto（默认，危险操作需确认）、always（全部确认）、never（跳过所有确认） |
| --no-truncation | 禁止截断输出内容，适合需要完整结果的场景 |
| --json | 以 JSON 格式输出结构化的结果，方便程序化处理 |
| --max-turns <n> | 限制 AI 的最大交互轮数，控制成本和执行时间 |
| --continue | 继续上一次的对话，适用于多步骤的复杂任务 |

示例——在沙箱中安全地生成项目：

codex exec "创建一个 Express.js REST API 项目骨架，包含用户认证模块" \
  --model gpt-4o \
  --sandbox

实战场景

场景一：Git Pre-commit 自动代码审查

在每次提交前，自动检查暂存区代码的质量问题。创建一个 scripts/review.sh：

#!/bin/bash
# 自动代码审查脚本

FILES=$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null)

if [ -z "$FILES" ]; then
    exit 0
fi

HAS_ISSUES=0

for file in $FILES; do
    echo "=== 审查文件: $file ==="

    codex exec "审查文件 $file 中的代码变更，请重点关注：
1. 潜在的安全漏洞（SQL 注入、XSS、路径遍历等）
2. 明显的逻辑错误或边界条件遗漏
3. 错误处理是否完善
4. 是否有硬编码的敏感信息
请用中文输出审查结果，列出发现的问题和修复建议。" \
    --approval-mode never \
    --model gpt-4o-mini

    if [ $? -ne 0 ]; then
        HAS_ISSUES=1
    fi
    echo ""
done

if [ $HAS_ISSUES -eq 1 ]; then
    echo "⚠️  代码审查发现问题，请检查上述输出。"
    echo "你可以运行 git commit --no-verify 跳过审查。"
    exit 1
fi

echo "✅ 代码审查通过！"

注册到 Git hook：

# 复制脚本到 .git/hooks 目录
cp scripts/review.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

场景二：批量代码重构

当需要将整个项目的回调风格改为 async/await 时，逐一修改太过耗时。配合 find 和 codex exec 可以批量处理：

# 批量将回调模式改为 async/await
find src -name "*.js" -not -path "*/node_modules/*" | while read file; do
    echo "处理: $file"

    codex exec "将文件 $file 中的回调函数模式（callback、.then()）重构为 async/await。
    要求：
    - 保持所有原有功能不变
    - try/catch 包裹可能出错的操作
    - 不改动任何测试文件
    - 不改动第三方库的调用方式" \
    --model gpt-4o \
    --approval-mode auto
done

场景三：GitHub Actions PR 摘要生成

在 CI 流水线中自动生成 PR 变更摘要，帮助 reviewer 快速理解改动内容：

# .github/workflows/pr-summary.yml
name: AI PR Summary

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  summarize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Codex
        run: npm install -g @openai/codex

      - name: Login to Codex
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: echo "$OPENAI_API_KEY" | codex login --api-key

      - name: Generate PR Summary
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > /tmp/pr.diff
          codex exec "分析 /tmp/pr.diff 中的完整代码变更，生成一份中文 PR 摘要，包含：
1. 变更概述：这次 PR 做了什么
2. 主要修改点：按文件或模块列出关键改动
3. 潜在影响区域：哪些功能可能受此次变更影响
4. 测试建议：reviewer 应重点测试的场景" \
          --no-truncation \
          --model gpt-4o > pr_summary.md

      - name: Post Summary
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const summary = fs.readFileSync('pr_summary.md', 'utf8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: summary
            });

场景四：项目脚手架一键生成

不用再手动创建项目目录结构，让 Codex 帮你搞定：

codex exec "在 ./user-service 目录下创建一个 Go 微服务项目，包含：
1. 标准的 Go 项目目录布局（cmd/、internal/、pkg/、migrations/）
2. 一个 gRPC 服务定义文件 proto/user.proto
3. 使用 golang-migrate 的数据库迁移脚本
4. Dockerfile 和 docker-compose.yml（包含 PostgreSQL）
5. Makefile（build、test、lint、migrate-up、migrate-down）
6. README.md 包含本地开发和部署说明
7. .golangci.yml 配置" \
--model gpt-4o \
--approval-mode auto

与 AGENTS.md 深度配合

AGENTS.md 是 Codex 的项目级指令文件，放在项目根目录。exec 模式同样会解析这个文件中的指令，确保 AI 在自动化场景下也遵循你的团队规范。

编写有效的 AGENTS.md

# AGENTS.md

## 技术栈
- 后端：Go 1.22+，使用 net/http 标准库
- 数据库：PostgreSQL 16，驱动 pgx/v5
- 缓存：Redis 7，驱动 go-redis/v9
- 日志：标准库 log/slog

## 代码规范
- 所有导出函数必须有 godoc 注释
- 错误处理：使用 `fmt.Errorf("context: %w", err)` 包装
- 不使用 panic，所有错误向上传播
- HTTP handler 只做参数解析和响应，业务逻辑放 service 层
- 单元测试使用 testing 标准库 + testify/assert

## 数据库规范
- 表名：蛇形命名，复数形式
- 主键：UUID v7，字段名 id
- 时间字段：created_at、updated_at，类型 TIMESTAMPTZ
- 迁移文件命名：{序号}_{描述}.up.sql 和 {序号}_{描述}.down.sql

## API 规范
- RESTful 风格，资源名使用复数
- 请求/响应统一使用 JSON
- 错误响应格式：{"error": {"code": "xxx", "message": "yyy"}}

配置好 AGENTS.md 后，exec 模式会自动遵循这些约定：

# Codex 会按规范创建 handler + service 分层代码
codex exec "添加用户注册接口 POST /api/v1/users/register，
字段包括邮箱、密码、昵称。密码需要 bcrypt 加密存储。"

多项目共享配置

如果多个项目有共同的规范，可以在 ~/.config/codex/AGENTS.md 中定义全局规则，项目级的 AGENTS.md 会自动合并：

# 全局 AGENTS.md
mkdir -p ~/.config/codex
# 将团队的通用规范写入 ~/.config/codex/AGENTS.md

高级技巧

命令管道组合

将 codex exec 的输出与后续命令串联：

# 生成测试代码并直接运行
codex exec "为 internal/handler/user.go 中的所有 HTTP handler 生成表驱动测试" \
  --model gpt-4o \
  | tee internal/handler/user_test.go \
  && go test ./internal/handler/ -v -count=1

条件化自动修复

#!/bin/bash
# auto-fix.sh — 自动修复 lint 问题

LINT_OUTPUT=$(golangci-lint run --out-format json 2>&1)

if [ -n "$LINT_OUTPUT" ]; then
    echo "发现 lint 问题 $(echo "$LINT_OUTPUT" | jq '.Issues | length') 个，正在自动修复..."

    echo "$LINT_OUTPUT" | jq '.Issues' > /tmp/lint.json

    codex exec "分析 /tmp/lint.json 中的 golangci-lint 输出（JSON 格式），
    对每个 issue 给出修复方案并应用到源文件。
    修复完成后运行 'golangci-lint run' 验证结果。" \
    --approval-mode auto

    echo "修复完成，请用 git diff 检查变更。"
else
    echo "✅ 代码检查通过！"
fi

JSON 输出与 jq 配合

# 以结构化方式获取代码分析结果
codex exec "分析 src/ 目录下所有 Go 文件的复杂度，
输出每个文件圈复杂度最高的 3 个函数及对应的复杂度值。" \
--json \
--model gpt-4o-mini > complexity_report.json

# 用 jq 过滤复杂度超过 10 的函数
jq '.[] | select(.complexity > 10)' complexity_report.json

继续上一次对话

对于复杂的多步骤任务，使用 --continue 保持上下文：

# 第一步：设计数据库表结构
codex exec "为电商系统设计以下表结构：users、products、orders、order_items"

# 第二步：基于上一步的表结构，生成迁移文件
codex exec --continue "根据上面设计的表结构，生成 PostgreSQL 迁移脚本"

注意事项与最佳实践

审批模式慎用：生产环境中避免使用 --approval-mode never，尤其是在涉及文件写入或命令执行时。建议在 CI 中先使用 auto 模式，确认安全后再调整。

成本控制：每次 exec 调用都消耗 API credit。建议对简单任务使用 gpt-4o-mini 模型，复杂任务再切换 gpt-4o。通过 --max-turns 限制交互轮数也可以有效控制成本。

沙箱先行：在操作实际项目文件前，先用 --sandbox 模式验证 AI 的输出是否符合预期。

重试机制：在脚本中调用 exec 时，建议添加重试逻辑，应对偶发的网络或 API 错误：

```bash
retry_codex() {
local max_retries=3
local retry_count=0
until codex exec "$@"; do
retry_count=$((retry_count + 1))
if [ $retry_count -ge $max_retries ]; then
echo "重试 $max_retries 次后仍然失败"
return 1
fi
sleep $((2 ** retry_count))
done
}
```

敏感信息保护：确保 .codexignore 文件中排除了 .env、密钥文件等敏感内容，防止被 AI 读取。

```
# .codexignore
.env
.env.*
*.pem
*-key.json
secrets/
```

总结

codex exec 让 Codex 从一款交互式编程助手升级为可编排的自动化工具。它打通了 AI 编程能力与 DevOps 工作流的壁垒——你可以把它放进 Git hook 审代码、放入 CI 流水线生成摘要、嵌入脚本批量重构、甚至用它一键生成项目脚手架。

配合 AGENTS.md 的项目级配置，你能确保 Codex 在任何自动化场景下都严格遵循团队规范，让 codex exec 真正成为开发流程中值得信赖的自动化伙伴。

在下一篇文章中，我们将深入探讨 Codex 的 Sandbox 沙箱模式，了解如何在完全隔离的环境中安全运行 AI 生成的代码，以及如何将沙箱模式与 exec 命令结合，打造零风险的自动化实验环境。