官方原文索引： Scripting Codex / exec command / Headless mode
1. 核心架构与原理解析
codex exec 命令提供非交互式执行能力，使 Codex 可嵌入 CI/CD 流水线：
| 特性 | 交互式 TUI | codex exec |
|---|---|---|
| 用户输入 | 实时对话 | 仅初始 Prompt |
| 审批处理 | 人工确认 | 预先配置策略 |
| 输出格式 | 富文本 TUI | 纯文本 / JSONL |
| 适用场景 | 日常开发 | CI/CD、自动化 |
2. 工程落地与代码示例
GitHub Actions 完整集成
# .github/workflows/codex-review.yml
name: Codex Auto Review
on:
pull_request:
types: [opened, synchronize]
jobs:
codex-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # 需要完整历史用于 diff
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: 22
- name: Install Codex
run: npm install -g @openai/codex
- name: Run Codex Security Review
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
codex exec \
--sandbox read-only \
--approval-mode never \
--model gpt-5.3-codex-spark \
"审查本次 PR 的安全风险，输出 Markdown 格式的报告"
- name: Comment PR
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const report = fs.readFileSync('codex-report.md', 'utf8');
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: report
});自动化测试修复
# 当 CI 失败时自动诊断
codex exec --full-auto -c max_budget_usd=10 \
"CI is failing with the error in logs/. Analyze root cause, fix the code, and run tests until they pass."预算控制
# 防止 Token 爆炸
codex exec --full-auto -c max_budget_usd=5 "update dependencies"
# 超时控制
codex exec --full-auto --timeout 300 "run test suite"预提交钩子集成
#!/bin/bash
# .git/hooks/pre-commit
# 使用 Codex 做代码风格检查
codex exec \
--sandbox read-only \
--approval-mode never \
--model gpt-5.3-codex-spark \
"检查暂存区的代码风格问题，只报告不修改"
if [ $? -ne 0 ]; then
echo "Codex 发现代码风格问题，请修复后再提交"
exit 1
fi3. 场景深入：CI/CD 中的 Codex 实践
场景：夜间回归测试
# .github/workflows/nightly-codex.yml
name: Nightly Codex Regression
on:
schedule:
- cron: '0 2 * * *' # 每天凌晨 2 点
jobs:
regression:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup
run: npm install -g @openai/codex
- name: Run Regression
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
codex exec --full-auto \
"运行完整测试套件，如果失败则诊断修复并重试，生成回归报告"
- name: Upload Report
uses: actions/upload-artifact@v4
with:
name: regression-report
path: codex-report.md场景：依赖安全扫描
# 每周扫描依赖漏洞
codex exec --sandbox read-only \
"扫描 package.json 中的依赖，检查是否有已知 CVE：
1. 对比 npm audit 输出
2. 评估每个漏洞的可利用性
3. 给出升级建议和兼容性风险"4. 💡 核心避坑与最佳实践 (Takeaways)
- CI 中必须使用 API Key：OAuth 不适合自动化场景
- 设置预算上限：
max_budget_usd防止意外高额消费 - Read Only 审查最安全：CI 中避免自动写入，防止恶意 PR 被自动批准
- 输出结构化便于解析：使用
-z获取纯净输出，配合jq解析 - 缓存安装结果：Codex CLI 安装慢，CI 中考虑缓存
npm -g目录 - 失败时生成报告：Codex 失败不要直接退出，先生成诊断报告便于排查