我第一次配置 Codex 自动化任务时，最直觉的想法是：定时任务嘛，当然用 Cron。

于是我配置了一个每天固定时间执行的任务：读取项目状态、整理当天变更、发送邮件。手动运行一切正常，到了定时触发却开始出问题：任务像是被触发了，日志也能看到执行痕迹，但邮件就是发不出去。

最开始我以为是提示词不稳定，后来怀疑是邮件工具授权失效，再后来去翻本地配置和会话索引，才发现问题不在“任务有没有触发”，而在于：

Cron 每次触发更像是拉起一个新的执行上下文，而新的上下文不一定拥有你手动会话里的工具权限、历史状态和工作目录关系。

这篇文章就是这次排障之后整理出的 Codex Automation 配置指南。它不只讲怎么写配置，更重点讲几个容易被忽略的工程事实：为什么 Cron 会让任务“失忆”，为什么我更推荐 heartbeat + target_thread_id，配置文件在哪里，以及怎么找到真正绑定的线程 ID。

---

1. 先分清：Codex 自动化不是普通服务器 Cron

传统 Cron 的心智模型很简单：到点执行一段脚本。

Codex Automation 的心智模型不一样。它触发的不是一段孤立脚本，而是一次 Codex 会话里的任务执行。这里至少有三层东西：

1. 触发方式：什么时候启动，常见是 cron 或 heartbeat。

2. 执行上下文：这次任务在哪个线程、哪个工作目录、哪个会话状态下继续。

3. 工具权限：能不能发邮件、读文件、访问连接器、调用外部服务。

很多问题不是出在第 1 层，而是出在第 2、3 层。

最典型的现象是：

• 手动运行成功，自动触发失败。

• 自动化记录显示任务跑过，但没有真正完成业务动作。

• 邮件、Gmail、文件、外部 API 这类工具调用在自动化里失败。

• 看提示词没问题，看 Cron 也没问题，但结果就是不稳定。

这种时候不要先改提示词，先看上下文。

---

2. Cron 的坑：它稳定触发，但不保证稳定上下文

Cron 最大的优点是直观：每天几点、每周几、每隔多久。

但对 Codex 这类“会话驱动”的自动化来说，Cron 也有一个天然缺点：它更偏向“按计划启动一次任务”，而不是“回到某个已验证的线程继续执行”。

这就是为什么同一个任务会出现下面这种割裂感：

手动会话：能读仓库、能调用邮件、能完成日报
Cron 触发：任务启动了，但邮件权限或上下文不完整

这不是 Cron 坏，也不是 Codex 一定不稳定，而是 Cron 的职责边界就在那里：它负责触发，不负责替你保证执行上下文完全等价。

如果你的任务是纯文本总结、简单分析、无外部工具调用，Cron 可以用。

但如果任务需要：

• 发送邮件

• 读取特定工作目录

• 复用某条历史会话里的判断

• 调用已授权的连接器或工具

• 保持长期任务状态

那我不建议直接裸用 Cron。更稳的做法是：heartbeat + target_thread_id。

---

3. 为什么我推荐 Heartbeat + target_thread_id

heartbeat 的优势不在于“看起来更高级”，而在于它的心智模型更接近：

在一个指定线程上持续工作，而不是每次重新开一条路。

再配合 target_thread_id，它就能把自动化任务绑定到一个明确的 Codex 线程上。这个线程可以提前手动跑通，确认工作目录、工具权限、邮件发送、项目上下文都正常，然后让自动化后续持续复用它。

我的推荐策略是：

需要稳定上下文和工具权限的任务：heartbeat + target_thread_id
一次性、无状态、无工具依赖的任务：cron

举个例子，像“每天晚上自动整理项目进展并发送邮件”这种任务，我更倾向这样落地：

1. 先开一条 Codex 线程，手动跑通完整流程。

2. 确认它能读项目、能总结、能发送邮件。

3. 找到这条线程的 thread_id。

4. 在自动化配置里使用 kind = "heartbeat"。

5. 把 target_thread_id 绑定到这条线程。

这样做的价值是：一旦任务失败，你知道它应该回到哪条线程、哪个上下文、哪个配置文件，而不是在一堆新会话里猜。

---

4. 配置文件到底在哪里

这是很多文章没写清楚的地方。Codex 的自动化配置不是只存在 UI 里，本地也有文件。

默认情况下，Codex 的本地状态目录通常在：

~/.codex

Windows 下通常对应：

C:\Users\<你的用户名>\.codex

如果你设置过 CODEX_HOME，则以 CODEX_HOME 指向的目录为准。

自动化任务配置通常在：

~/.codex/automations/<automation-id>/automation.toml

也就是说，一条自动化任务一般对应一个目录，目录下面有它自己的 automation.toml。

你真正需要重点看的不是 UI 上的名字，而是这个文件里的字段：

name = "daily-report"
status = "ACTIVE"
kind = "heartbeat"
target_thread_id = "019e07b4-64e4-7c21-90d9-1c5f3301ee7c"

其中最关键的是：

• kind：确认它到底是 cron 还是 heartbeat。

• status：确认是否启用。

• target_thread_id：确认它绑定到哪条线程。

• cwds 或工作目录字段：确认它跑在哪个项目目录。

---

5. target_thread_id 去哪里找

从会话索引里反查。

Codex 本地通常会有会话索引文件，例如：

~/.codex/session_index.jsonl

这个文件可以用来查最近会话、线程、运行记录之间的关系。排障时我会重点看：

• 这条自动化绑定的 thread_id 是否存在。

• 最近一次运行是否真的落到了这个线程。

• 自动化触发后是否出现 thread/read、thread/resume 相关失败。

如果你只看 UI，有时会被“显示状态”误导。真正排查时，本地文件更接近事实。

---

6. 我建议的稳定配置模板

下面是一个更适合“日报 + 邮件 + 固定项目上下文”的写法。字段名可能会随版本变化，核心思路不变。

name = "daily-project-report"
status = "ACTIVE"
kind = "heartbeat"
​
# 绑定已经手动跑通过的线程
target_thread_id = "你的对话线程ID"
​
# 固定工作目录，避免自动化跑到错误项目
cwds = ["C:/Users/your-name/work/project"]
​
# 如果当前版本支持周期规则，可在这里配置
rrule = "RRULE:FREQ=DAILY;BYHOUR=21;BYMINUTE=30;BYSECOND=0"

我会在提示词里再加三条防呆要求：

1. 先确认当前工作目录和目标项目是否匹配。
2. 发送邮件前输出本次摘要和收件人确认信息。
3. 同一天同一主题只发送一次，避免失败重试导致重复邮件。

不要小看这三条。自动化任务最怕的不是失败，而是“半成功”：总结做了两遍，邮件发了两封，日志还看不出哪次是最终结果。

---

7. 真实排障顺序：别一上来就改 Prompt

如果你的 Codex 自动化没有按预期执行，我建议按这个顺序查。

7.1 查触发方式

先打开 automation.toml，确认：

kind = "cron"

还是：

kind = "heartbeat"

如果是涉及邮件、外部工具、固定项目上下文的任务，看到 cron 时就要警惕：它可能每次都在一个不完整的新上下文里执行。

7.2 查绑定线程

确认是否存在：

target_thread_id = "..."

如果没有，就说明它可能没有明确绑定到你手动验证过的线程。

7.3 查工作目录

确认任务实际运行目录是不是你的项目目录。

自动化任务跑错目录时，经常不会立刻报错，只是“总结不到东西”或者“读到旧文件”。

7.4 查会话恢复

在日志或本地状态里看是否有类似：

thread/read
thread/resume
resume failed
stale path
mismatched path

Windows 上还要额外注意路径归一化问题。例如同一个文件可能被表示成：

C:\Users\...\rollout.jsonl
\\?\C:\Users\...\rollout.jsonl

看起来是同一个路径，但恢复线程时可能被判断为不一致。

7.5 查工具权限

如果失败点出现在邮件、Gmail、Drive、GitHub 这类工具调用上，优先判断：

当前自动化上下文是否拥有和手动会话一样的工具权限？

这一步比改提示词重要。

---

8. 几个最容易被忽略的坑

8.1 复制自动化后忘了改 target_thread_id

这是非常隐蔽的错误。

你以为自己复制了一条新任务，实际上它还绑着旧线程。结果新任务的行为完全受旧线程上下文影响，日志看起来又很难解释。

建议每次复制自动化后都检查：

name = "..."
target_thread_id = "..."
cwds = ["..."]

这三个字段必须一起看。

8.2 多个 heartbeat 绑到同一条线程

理论上能跑，不代表生产上应该这么做。

如果多个高频 heartbeat 都指向同一个 target_thread_id，你可能会遇到恢复竞争、重复执行、状态抖动。我的建议是：关键任务一条线程一个自动化，先稳定，再扩展。

8.3 只看 UI，不看本地文件

UI 适合快速查看状态，但排障时要回到文件。

至少看三处：

~/.codex/automations/<automation-id>/automation.toml
~/.codex/session_index.jsonl
~/.codex/logs 或 state 相关文件

8.4 没有幂等设计

自动化任务一定要假设会重试。

如果你的任务会发邮件、写日报、改文件、创建 issue，就必须设计幂等。比如日报任务可以用“日期 + 标题 + 项目名”作为唯一键，避免重复发送。

---

9. 上线前检查清单

我现在配置 Codex 自动化前，会固定过一遍这个清单：

• kind 是否符合任务类型。

• 需要工具权限的任务是否使用 heartbeat + target_thread_id。

• target_thread_id 是否来自一条已经手动验证成功的线程。

• 工作目录是否固定到目标项目。

• 自动化配置文件路径是否确认过。

• 邮件/外部工具是否在绑定线程里跑通过。

• 任务是否有幂等规则。

• 失败时是否能从日志定位到 automation_id、thread_id、run_id。

这套清单比“多写几句提示词”更有用。

结语

Codex Automation 真正难的地方，不是写一个定时表达式，而是搞清楚“任务每次醒来时，它到底是谁、在哪里、能做什么”。

我的最终经验是：

无状态任务，用 Cron。
需要上下文和工具权限的任务，用 heartbeat + target_thread_id。
排障时先看本地配置和线程绑定，再看提示词。

自动化不是让任务“到点运行”这么简单。可靠的自动化，是让任务每次醒来都能回到正确的位置，带着正确的权限，做正确的一件事。