第七课：核心命令 codex 与 codex exec

交互模式非交互模式参数详解

1. 概述

OpenAI Codex CLI 提供了两种核心运行模式：交互模式（codex） 和 非交互模式（codex exec）。这两种模式分别适用于不同的使用场景——交互模式适合日常开发中的对话式编程，非交互模式则专为 CI/CD 流水线和脚本自动化设计。

本课将深入讲解两种模式的所有启动参数、常用组合示例，以及 stdin 读取 prompt 等高级用法。

2. 交互模式：`codex`

2.1 基本用法

交互模式是最常用的模式，启动后进入一个 REPL（Read-Eval-Print Loop）环境，你可以与 Codex 进行多轮对话：

# 最简单的启动方式
codex

# 直接传入初始 prompt
codex "帮我写一个 Python 脚本读取 CSV 文件"

# 在指定目录启动
cd /path/to/project
codex

启动后，Codex 会加载当前目录的上下文（包括文件结构、git 状态等），你可以像聊天一样与它交互。每次输入 prompt 后，Codex 会分析需求、调用工具（如读写文件、执行命令）、返回结果。

2.2 核心启动参数详解

`--model` / `-m`：指定模型

# 使用 GPT-4.1
codex --model gpt-4.1

# 使用 o3 推理模型
codex --model o3

# 使用 o4-mini（轻量推理模型）
codex --model o4-mini

# 使用 GPT-4.1-mini（性价比之选）
codex --model gpt-4.1-mini

可选的模型列表取决于你的 API 权限。常用模型推荐：

模型	特点	适用场景
`o3`	强推理能力，较慢	复杂架构设计、算法题
`o4-mini`	推理能力好，速度快	日常开发、代码生成
`gpt-4.1`	综合能力强	通用编程任务
`gpt-4.1-mini`	快速、低成本	简单任务、快速迭代
`gpt-4.1-nano`	最快、最便宜	简单查询、格式转换

`--sandbox` / `-s`：沙箱模式

沙箱模式控制 Codex 执行命令时的权限级别：

# 仅允许只读操作（安全模式）
codex --sandbox read-only

# 允许写入当前目录（默认模式）
codex --sandbox workspace-write

# 完全禁用沙箱（危险，不推荐）
codex --sandbox danger-full-access

三种沙箱模式的权限对比：

模式	文件读取	文件写入	网络访问	系统命令	适用场景
`read-only`	✅	❌	❌	受限	代码审查、学习
`workspace-write`	✅	✅	❌	受限	日常开发
`danger-full-access`	✅	✅	✅	✅	需要网络或系统操作

`--ask-for-approval` / `-a`：审批策略

控制 Codex 在执行可能有副作用的操作前是否需要用户确认：

# 始终询问（最安全）
codex --ask-for-approval always

# 仅在执行失败时询问
codex --ask-for-approval on-failure

# 永不询问（自动执行，YOLO 模式）
codex --ask-for-approval never

审批策略详解：

always（默认）：每次执行文件修改、运行命令等操作前都会弹出确认提示。适合初次使用或处理重要项目。
on-failure：仅在命令执行失败时询问下一步操作。适合熟悉 Codex 行为后的半自动模式。
never：完全自动执行，不询问任何确认。适合你完全信任 Codex 的场景，或在 CI/CD 中使用。

`--image` / `-i`：附加图片

将图片作为上下文的一部分传给 Codex，支持截图、设计稿、错误信息等：

# 附加单张图片
codex --image screenshot.png "根据这个截图实现 UI"

# 附加多张图片
codex --image design.png --image error.png "参考设计稿，修复这个错误"

# 从剪贴板粘贴（macOS）
pngpaste /tmp/clipboard.png && codex --image /tmp/clipboard.png

图片会通过多模态能力传递给模型，Codex 可以理解图片内容并据此生成代码。常见用法：

传入 UI 设计稿，让 Codex 生成对应的前端代码
传入错误截图，让 Codex 分析并修复 bug
传入架构图，让 Codex 理解系统设计

`--add-dir` / `-d`：添加额外目录

默认情况下，Codex 只能访问当前工作目录。使用 --add-dir 可以让它访问其他目录：

# 添加一个额外目录
codex --add-dir /path/to/shared-library

# 添加多个目录
codex --add-dir /path/to/lib1 --add-dir /path/to/lib2

# 结合当前目录使用
codex --add-dir ../common-utils "使用 common-utils 中的工具函数重构当前项目"

这在以下场景中非常有用：

项目依赖了本地的共享库
需要参考其他项目的代码
多仓库开发时需要跨仓库操作

`--profile` / `-p`：配置 Profile

Profile 允许你为不同场景维护独立的 Codex 配置：

# 使用工作 Profile
codex --profile work

# 使用个人项目 Profile
codex --profile personal

# 使用简写
codex -p work

每个 Profile 拥有独立的：

默认模型设置
审批策略
沙箱配置
自定义指令（instructions.md）

Profile 配置存储在 ~/.codex/profiles/<profile-name>/ 目录下。

`--search` / `-S`：启用网页搜索

让 Codex 在回答时可以搜索网络获取最新信息：

# 启用搜索
codex --search "帮我查找最新的 React 19 新特性并迁移当前项目"

启用后，Codex 可以：

搜索最新的 API 文档
查找库的最新版本和用法
获取 Stack Overflow 上的解决方案
查询框架的最佳实践

`--oss`：使用开源模型

通过本地推理引擎运行开源模型：

# 使用本地运行的开源模型
codex --oss

使用 --oss 前需要确保本地推理引擎（如 Ollama、vLLM 等）已启动并配置好。

2.3 交互模式内置命令

进入交互模式后，可以使用以下斜杠命令：

命令	说明
`/help`	显示帮助信息
`/clear`	清除当前会话上下文
`/compact`	压缩当前会话历史
`/diff`	显示当前工作目录的 git diff
`/quit` 或 `Ctrl+C`	退出 Codex
`Ctrl+D`	发送 EOF，退出

3. 非交互模式：`codex exec`

3.1 基本用法

codex exec 是非交互模式，适合在脚本、CI/CD 流水线中使用。它接收一个 prompt，执行完毕后直接退出：

# 基本用法
codex exec "给当前项目添加单元测试"

# 在脚本中使用
codex exec "运行所有测试并生成覆盖率报告"
echo "Exit code: $?"

与交互模式的关键区别：

无 REPL 循环：执行一次后退出
无用户交互：不会弹出确认提示
可获取输出：支持 JSON 输出和结构化结果
适合自动化：可直接在 shell 脚本中调用

3.2 核心参数详解

`--json`：JSON 格式输出

将执行结果以 JSON 格式输出，方便程序解析：

# 获取 JSON 格式的完整结果
codex exec --json "分析当前项目的依赖关系"

# 结合 jq 解析
codex exec --json "列出所有 TODO" | jq '.output'

JSON 输出结构：

{
  "status": "success",
  "output": "执行结果的文本输出...",
  "files_changed": ["src/app.py", "tests/test_app.py"],
  "commands_run": ["pytest tests/"],
  "duration_seconds": 45.2,
  "tokens_used": {
    "input": 15000,
    "output": 3200
  }
}

`--output-last-message` / `-o`：输出最后一条消息

只输出 Codex 的最后一条回复消息，忽略中间过程：

# 只获取最终结果
codex exec -o "写一个 Python 函数实现快速排序"

# 重定向到文件
codex exec -o "生成 README.md 内容" > README.md

这在以下场景中特别有用：

生成文件内容并重定向
提取 Codex 的最终回答用于后续处理
减少输出噪音，只关注结果

`--output-schema`：结构化输出

指定 JSON Schema，让 Codex 按照特定结构输出结果：

# 要求按特定 schema 输出
codex exec --output-schema '{"type":"object","properties":{"summary":{"type":"string"},"files":{"type":"array","items":{"type":"string"}}}}' "分析当前项目并输出摘要"

这在以下场景中非常有用：

需要将 Codex 的输出集成到自动化流程
需要程序化处理 Codex 的回答
构建 Codex 驱动的工具链

`--full-auto` / `-f`：全自动模式

等价于 --sandbox workspace-write --ask-for-approval never，启用全自动执行：

# 全自动模式：不询问确认，允许写入
codex exec --full-auto "重构所有 Python 文件，添加类型注解"

# 在 CI 中使用
codex exec --full-auto "修复 lint 错误"

⚠️ 注意：--full-auto 会禁用所有确认提示并允许文件写入，请确保在安全的环境中使用（如 Docker 容器或 CI 沙箱）。

3.3 exec 模式的其他参数

codex exec 也支持交互模式的大部分参数：

# 指定模型
codex exec --model o4-mini "简单任务"

# 添加额外目录
codex exec --add-dir ../lib "使用 lib 中的工具"

# 启用搜索
codex exec --search "使用最新的 API"

4. 两种模式对比

4.1 功能对比表

特性	`codex`（交互模式）	`codex exec`（非交互模式）
交互方式	REPL 多轮对话	单次执行后退出
用户输入	支持中途输入和确认	不支持，一次性传入 prompt
适用场景	日常开发、探索式编程	CI/CD、脚本自动化
输出格式	终端富文本	终端文本 / JSON
审批控制	支持所有策略	默认 `on-failure`，可用 `--full-auto`
会话保持	支持（可 resume）	不支持
stdin 输入	不支持	支持（通过管道）
退出方式	`/quit` 或 `Ctrl+C`	自动退出
返回值	无	退出码（0=成功，非0=失败）

4.2 参数对比表

参数	交互模式	exec 模式	说明
`--model`	✅	✅	指定模型
`--sandbox`	✅	✅	沙箱模式
`--ask-for-approval`	✅	✅	审批策略
`--image`	✅	✅	附加图片
`--add-dir`	✅	✅	添加目录
`--profile`	✅	✅	使用 Profile
`--search`	✅	✅	网页搜索
`--oss`	✅	✅	开源模型
`--json`	❌	✅	JSON 输出
`--output-last-message`	❌	✅	仅输出最后消息
`--output-schema`	❌	✅	结构化输出
`--full-auto`	❌	✅	全自动模式

5. 常用组合示例

5.1 日常开发场景

# 场景 1：在项目中启动，使用轻量模型
cd ~/my-project
codex --model gpt-4.1-mini

# 场景 2：带着设计稿开始开发
codex --image design.png "根据这个设计稿实现登录页面"

# 场景 3：需要参考其他仓库的代码
codex --add-dir ../shared-components "使用共享组件库重构当前页面"

# 场景 4：使用推理模型解决复杂问题
codex --model o3 "分析当前架构的性能瓶颈并提出优化方案"

# 场景 5：安全审查模式（只读）
codex --sandbox read-only --model o3 "审查当前代码的安全漏洞"

5.2 CI/CD 场景

# 场景 1：自动修复 lint 错误
codex exec --full-auto "运行 eslint --fix 并修复所有可自动修复的错误"

# 场景 2：生成 changelog
codex exec --output-last-message "根据 git log 生成 CHANGELOG.md" > CHANGELOG.md

# 场景 3：代码审查（JSON 输出供后续处理）
codex exec --json --sandbox read-only "审查最近一次 commit 的代码质量" > review.json

# 场景 4：自动生成测试
codex exec --full-auto "为 src/ 目录下所有函数生成单元测试"

# 场景 5：结构化输出用于管道
codex exec --output-schema '{"type":"object","properties":{"issues":{"type":"array"},"summary":{"type":"string"}}}'   "分析代码质量问题" | jq '.issues[]'

5.3 脚本自动化场景

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

set -e

echo "开始代码审查..."

# 1. 生成审查报告
codex exec --json --sandbox read-only   "审查当前分支相对于 main 的所有变更" > /tmp/review.json

# 2. 提取摘要
summary=$(cat /tmp/review.json | jq -r '.output')
echo "审查摘要：$summary"

# 3. 如果有问题，自动修复
issues=$(cat /tmp/review.json | jq '.files_changed | length')
if [ "$issues" -gt 0 ]; then
  echo "发现 $issues 个文件需要修改"
  codex exec --full-auto "根据审查结果修复所有问题"
fi

echo "审查完成！"

6. stdin 读取 Prompt

6.1 管道输入

codex exec 支持从 stdin 读取 prompt，这在处理长文本或动态生成 prompt 时非常有用：

# 从文件读取 prompt
cat prompt.txt | codex exec

# 从命令输出生成 prompt
echo "分析以下错误日志并给出修复建议：" > /tmp/prompt.txt
cat error.log >> /tmp/prompt.txt
cat /tmp/prompt.txt | codex exec

# 使用 heredoc
codex exec << 'EOF'
请帮我完成以下任务：
1. 阅读 src/main.py
2. 添加错误处理
3. 生成对应的单元测试
EOF

6.2 结合其他工具

# 结合 git：将 diff 作为上下文
git diff | sed 's/^/    /' | {
  echo "审查以下代码变更并给出建议："
  cat
} | codex exec

# 结合 find：处理多个文件
find . -name "*.py" -newer .git/HEAD | {
  echo "以下文件在最近一次 commit 后被修改，请检查它们的代码质量："
  cat
} | codex exec

# 结合 curl：处理 API 响应
curl -s https://api.example.com/data | {
  echo "分析以下 JSON 数据并生成 TypeScript 类型定义："
  cat
} | codex exec --output-last-message > types.ts

6.3 stdin 与参数的结合

当同时使用 stdin 和命令行参数时，stdin 内容会作为 prompt 的补充上下文：

# stdin 提供上下文，参数指定任务
cat architecture.md | codex exec "基于上述架构文档生成代码"

# stdin 提供代码，参数指定操作
cat old_code.py | codex exec "将这段代码从 Python 2 迁移到 Python 3" > new_code.py

7. 环境变量配置

7.1 核心环境变量

变量	说明	示例
`OPENAI_API_KEY`	OpenAI API 密钥	`sk-...`
`OPENAI_MODEL`	默认模型	`o4-mini`
`CODEX_HOME`	Codex 配置目录	`~/.codex`
`CODEX_SANDBOX_MODE`	默认沙箱模式	`workspace-write`
`CODEX_APPROVAL_POLICY`	默认审批策略	`always`

7.2 在 .env 文件中配置

在项目根目录创建 .env 文件：

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=o4-mini
CODEX_SANDBOX_MODE=workspace-write

⚠️ 安全提示：永远不要将 .env 文件提交到版本控制。确保 .gitignore 中包含 .env。

8. 最佳实践

8.1 交互模式最佳实践

始终在项目根目录启动：这样 Codex 可以完整理解项目结构
使用合适的沙箱模式：日常开发用 workspace-write，审查代码用 read-only
善用 --image：设计稿、错误截图、架构图都能帮助 Codex 更好理解需求
及时 /compact：长对话中定期压缩上下文，保持响应质量

8.2 exec 模式最佳实践

在 CI 中使用 --full-auto：确保在安全的沙箱环境中运行
使用 --json 获取结构化输出：方便后续脚本处理
使用 --output-last-message：当你只需要最终结果时
检查退出码：在脚本中使用 set -e 和 $? 判断执行结果

8.3 安全注意事项

不要在 --full-auto 模式下处理不受信任的输入
在 CI/CD 中使用 Docker 容器隔离
定期审查 Codex 的操作日志
使用 read-only 沙箱进行代码审查
将 API Key 存储在安全的密钥管理系统中

思考题

交互模式和 exec 模式的核心区别是什么？在什么场景下应该选择哪种模式？
如果你要在 GitHub Actions 中使用 Codex 自动审查 PR，应该如何配置 codex exec 的参数？需要考虑哪些安全问题？
--sandbox 的三种模式各适用于什么场景？如果一个项目包含敏感的配置文件（如 .env），应该使用哪种沙箱模式？
如何利用 stdin 管道将多个工具的输出组合成一个复杂的 prompt？请设计一个将 git diff + pytest 输出结合的自动化脚本。
--full-auto 模式等价于哪些参数的组合？为什么在 CI/CD 环境中推荐使用它？