更新于

Codex 后台自动化任务设计

Codex自动化CLI 工具实战经验

把 Codex CLI 从”人在旁边看着跑”升级到”定时无人值守执行”，中间隔着的不只是一个 cron 表达式。少了人工确认这个安全阀之后，任务失败的代价、权限范围、幂等性都需要重新设计。本文基于实际跑通的后台自动化任务经验，讲清楚该注意什么。

关于 Codex 的项目级指令写法可以参考 Codex 项目级 AGENTS.md 编写指南；本文假设你已经有一份能用的 AGENTS.md，聚焦”怎么让它定时自己跑起来”。

一、非交互模式是前提

Codex CLI 的交互模式（对话式）不适合后台任务——它假设每一步都有人确认。后台自动化必须用非交互执行模式（codex exec 或等价的一次性运行方式），传入明确的任务指令，跑完就退出，不等待人工输入。

设计后台任务的第一步不是写 prompt，而是明确两件事：

  • 这次任务的边界是什么：允许改哪些文件、允许执行哪些命令、绝对不能碰哪些路径
  • 任务成功/失败的判定标准是什么：不能靠”看起来跑完了就算成功”，需要有明确的退出码或产出物校验

二、权限收敛：后台任务不该有交互模式下的权限

交互模式下，人可以随时叫停一个越界操作。后台模式没有这层保护，权限设计必须比交互模式更保守：

维度交互模式后台自动化模式
文件写入范围可以临时放宽，人工把关严格限定在任务声明的目录内
命令执行允许探索性命令只允许任务模板里白名单过的命令
网络访问按需开放默认关闭，除非任务明确需要
Git 操作可以让 Codex 直接 commit/push建议只 commit，push 由外层脚本在校验通过后统一做

最后一条尤其重要：把”生成内容”和”发布内容”拆成两个阶段，中间插一道自动化校验（lint、测试、schema 校验），校验不通过就不进入发布阶段。这个模式本身就是本站每日发文自动化在用的思路——Codex/Claude 负责产出和本地 commit，真正的合并和部署交给 CI 在校验通过后统一执行，而不是让执行任务的 CLI 进程直接拥有发布权限。

三、幂等设计：任务重跑不能产生重复副作用

后台任务大概率会因为各种原因被重复触发：cron 误触发、CI 重试、进程崩溃后被 supervisor 拉起。任务设计必须假设”这次运行可能不是第一次运行”：

  • 任务开始前先检查这次要做的事是否已经做过（比如本文写作场景里，选题脚本会跳过仓库里已存在的 slug）
  • 产出物命名要能唯一标识这次任务的输入，而不是用时间戳这种每次都不同的值，否则重跑会产生重复文件
  • 如果任务包含”调用外部 API 产生副作用”的步骤（发消息、下单、部署），这一步必须单独做幂等 key 校验，不能依赖”任务只会成功执行一次”的假设

四、失败兜底：明确失败时该停在哪一步

无人值守意味着没人在任务失败的瞬间介入。设计时要预先想清楚失败路径，而不是等真出问题了再补：

#!/bin/bash
set -euo pipefail

# 阶段 1：生成 —— 允许失败，失败则整个任务终止，不进入后续阶段
codex exec "按 AGENTS.md 规则完成本次任务" || {
  echo "生成阶段失败，任务终止，不做任何提交" >&2
  exit 1
}

# 阶段 2：校验 —— 生成的内容必须先过自动化校验
python3 scripts/validate.py || {
  echo "校验未通过，保留生成内容供人工检查，不 commit" >&2
  exit 1
}

# 阶段 3：本地提交 —— 校验通过才允许落地
git add -A && git commit -m "auto: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

# 阶段 4：推送到独立分支，不直接进 main —— 留给 CI 做最终把关
git push -u origin "auto/$(date -u +%Y-%m-%d)"

这个结构的核心原则是：每个阶段只信任上一阶段的校验结果，不信任”看起来应该没问题”。生成阶段失败不该留下半成品文件，校验阶段失败不该继续提交，提交阶段完成不代表可以直接合并到主分支。

五、可观测性：至少要能回答”昨晚跑了什么”

无人值守任务出问题时，排查依赖的是日志而不是记忆。最低限度需要记录：

  • 每次任务的开始/结束时间、退出码
  • 任务生成/修改了哪些文件（git diff --stat 的输出足够）
  • 如果调用了外部 API，记录调用次数和关键返参摘要（不要记录完整的敏感响应体）

这些日志不需要多复杂的系统，一个按日期归档的文本文件，配合任务脚本本身的 set -x 或显式 echo，就能覆盖大部分排查需求。真正出问题时，先看日志里任务停在了哪个阶段，再决定是重跑还是人工介入。

六、什么任务适合做成后台自动化，什么不适合

不是所有 Codex 任务都值得做成无人值守。适合的特征：任务边界清晰、失败代价可控、有明确的自动化校验标准（比如本文的 schema 校验 + 测试）。不适合的特征：任务需要主观判断（“这个设计好不好看”）、失败代价高且难以自动检测（涉及资金、用户通知类操作）、没有稳定的校验手段来判断产出是否合格。强行把后者自动化，往往是把”人工把关”这一步变相跳过了，风险没有消失，只是变得不可见。

七、相关阅读

如果你的 Codex 自动化任务需要稳定调用 OpenAI API，YoTradeApi 提供国内可直连的中转接入，减少定时任务因网络问题失败的概率。

相关阅读