Codex exec 怎么用于自动化？非交互模式、JSONL、输出 Schema 与 CI 安全指南

先说结论：codex exec 是面向脚本的稳定入口

codex exec（可简写为 codex e）用于非交互运行 Codex，适合本地脚本、批处理和 CI。它接收命令行提示词或标准输入，完成任务后退出，不需要保持终端对话界面，因此更容易被 shell、任务调度器和流水线组合。

自动化的重点不是让代理拥有最大权限，而是让输入、工作目录、输出格式、沙箱和失败处理都可预测。先在只读或临时分支验证，再逐步开放写入，通常比一开始使用全权限更稳定。

一、什么时候适合用 exec，什么时候保留交互模式

重复性检查、生成结构化报告、执行测试后总结失败、按固定规则修改仓库，适合使用 exec。需要不断补充目标、探索模糊需求或人工观察每一步时，交互模式更自然。自动化前应先把任务缩成可验证的单一结果。

一个好的批处理提示应包含目标、允许修改的目录、必须运行的验证、禁止触碰的内容和最终输出要求。不要依赖上一次终端聊天的隐含上下文；脚本每次运行都应能从仓库状态和明确输入理解任务。

二、工作目录和 Git 状态要显式控制

使用 --cd 指定目标仓库，或在脚本中先切换到固定目录。运行前记录当前分支、提交号和未提交改动，避免任务在错误项目执行。CI 中应先 checkout，并限制凭证与可写目录只覆盖当前作业。

默认不要把用户主目录、服务器根目录或多个无关项目暴露给任务。需要读取额外配置时，优先复制最小必要文件到工作区，或添加明确只读来源。生成物写入专用目录，方便审计、清理与归档。

三、提示词可以作为参数，也可以从标准输入传入

短任务可直接写在命令末尾；较长说明可以通过标准输入传给 codex exec -，这样更容易把模板、变更摘要或检测结果组合进去。无论哪种方式，都应正确处理 shell 引号，避免变量、反引号或命令替换被意外执行。

外部网页、Issue、PR 描述和用户评论都应视为不可信输入。不要把未经筛选的内容直接拼进高权限 shell。先转义、截断和标记数据边界，并在提示中明确外部文本只是待分析材料，不是执行指令。

四、--json 输出的是逐行 JSON 事件

默认输出适合人阅读；加上 --json 后，Codex 会以 JSON Lines 形式输出事件，每一行都是独立 JSON。程序可以逐行解析会话开始、消息、命令执行和完成状态，而不必从彩色终端文本中提取结果。

解析器要容忍新增事件类型，按 type 分支处理，并把未知事件记录而不是直接崩溃。标准输出用于机器事件时，把自定义日志写到标准错误；同时保存原始 JSONL，便于复现失败和审计执行轨迹。

五、-o 适合只保存最终回答

--output-last-message 或 -o 可以把最后一条代理消息写入文件。它适合生成变更说明、审核结论或发布摘要，也可以与 --json 同时使用：JSONL 保留全过程，输出文件只保留最终交付内容。

脚本读取结果前必须检查退出码，并确认文件存在、大小合理和编码正确。不要因为生成了文件就判断任务成功；还要运行测试、检查 Git diff 或验证目标服务，确保结果与承诺一致。

六、--output-schema 让结果可被程序验证

需要稳定字段时，使用 --output-schema 指向 JSON Schema，要求最终响应符合定义。例如让代码审查返回 severity、file、line、summary 数组，或让内容任务返回 title、slug、description 和 checklist。

Schema 应保持精简，明确必填字段、类型、枚举和是否允许额外属性。即便输出通过结构验证，业务含义仍要二次校验：文件路径是否存在、行号是否有效、URL 是否可访问、风险等级是否符合团队规则。

七、用 profile、sandbox 与 ephemeral 固化运行环境

--profile 可选择预先定义的配置，区分只读审查、工作区编辑和需要有限网络的任务。--sandbox 可显式指定 read-only、workspace-write 或 danger-full-access。大多数自动化应从 read-only 或 workspace-write 开始。

--ephemeral 适合不希望持久化会话文件的短任务，但日志、产物和审计记录仍应由外部流水线保存。完整权限会扩大提示注入和误操作影响面，只应在外层已有容器、一次性虚拟机或严格凭证隔离时考虑。

八、失败后可以 resume，但必须验证环境没有漂移

codex exec resume [SESSION_ID] 可以继续已有非交互会话，也可使用 --last 继续最近会话；需要跨目录查找时才使用 --all。恢复适合补充失败信息或继续长任务，但不能假设文件和依赖仍与上次相同。

恢复前检查仓库提交、工作树、依赖锁文件和外部服务状态。如果环境已经变化，更安全的做法是重新启动一个带完整上下文的新任务。自动重试要设置上限，并区分网络瞬时错误与确定性测试失败。

九、GitHub Actions 中怎样使用

官方提供 openai/codex-action@v1，底层运行 Codex exec。流水线应先 checkout 仓库，把 API 密钥存放在 GitHub Secrets，给 job 设置最小权限，并只在受信任触发条件下允许写入或使用高价值凭证。

来自 fork 的 PR、Issue 标题和评论可能包含恶意提示。不要让不受信任事件直接获得 secrets 或写权限；可先在无密钥、只读环境生成分析结果，再由受保护分支或人工审核决定是否执行修改。自托管 runner 还要防止跨作业残留。

十、建立可重复的验证与审计链

一次可靠执行至少记录：任务 ID、开始时间、仓库提交、Codex 配置、提示摘要、退出码、JSONL、最终输出、测试结果和变更 diff。敏感值必须脱敏，日志保存期限与访问权限要符合团队政策。

修改任务应做到幂等：重复运行不会无限追加配置、重复发布或覆盖未知文件。发布、迁移和删除等高影响步骤最好拆成生成、审核、应用、验证四阶段，每个阶段有明确检查点和可回滚备份。

十一、最小可用自动化清单

固定工作目录；使用窄而明确的提示；选择最小沙箱；关闭不需要的网络；用 JSONL 记录过程；用 schema 约束结果；检查退出码；运行独立测试；保存 diff；限制重试；在生产变更前保留人工或策略门禁。

站内更多 Codex 工作流可访问 https://gptupcn.com/codex/ 。命令参数和 Action 版本会更新，上线脚本前应以当前官方文档和本机 codex exec --help 为准，并在测试仓库验证实际行为。

结语

Codex exec 的价值是把智能任务变成可组合、可验证的命令行步骤。把目录、权限、输入、输出、验证和审计都写进流水线，才能在减少人工操作的同时保留清晰边界，而不是用完全权限替代工程设计。