| name | cron-jobs-writer |
| description | 安全写入 OpenClaw cron jobs.json。在写入前强制执行格式校验，确保 payload 与 sessionTarget 匹配，避免 JSON 解析失败导致 Gateway 无法启动。 |
| slug | cron-jobs-writer |
| version | 1.0.1 |
| displayName | 定时任务工具（Cron Jobs Writer） |
| summary | 安全写入 ~/.openclaw/cron/jobs.json，写入前强制校验，避免 Gateway 解析失败。支持 main/isolated 两种会话类型。 |
| tags | cron, openclaw, gateway, jobs, schedule |
Cron Jobs Writer — 安全写入 jobs.json
触发条件
以下任一情况触发本技能：
- 创建/修改：用户要求创建定时任务、修改 cron、添加提醒
- 排查/检修：用户反馈「定时任务看不到」「cron 不工作」「定时任务列表加载失败」，或 Gateway 日志出现 cron 相关错误（如
Failed to parse cron store）
写入或排查 ~/.openclaw/cron/jobs.json 前必须按本技能流程执行，否则可能导致 Gateway 解析失败、KeepAlive 反复重启。
0. 路径与生效（必读）
唯一正确路径：~/.openclaw/cron/jobs.json
- 不要读写
workspace/cron/jobs.json 或任何 workspace/ 下的 cron 文件
- Gateway 只加载
~/.openclaw/cron/jobs.json，写错路径等于没修
修改后必须重启：修改 jobs.json 后，必须执行 {{SKILL_DIR}}/scripts/restart-gateway.sh（pkill 彻底结束 Gateway 后 start，避免双实例），cron 模块才会重新加载配置。否则修改不生效。
写入流程（必须遵守）
flowchart TD
A[用户请求创建/修改 cron] --> B[读取当前 jobs.json]
B --> C[校验 JSON 可解析]
C --> D{格式正确?}
D -->|否| E[报告错误详情]
E --> F1{询问用户: 是否修复?}
F1 -->|是| G1[尝试修复 常见错误]
G1 --> H1[再次校验]
H1 --> D
F1 -->|否| G2[中止 不写入]
D -->|是| I[构造新 job 对象]
I --> J[校验 payload 规则]
J --> K{sessionTarget+payload 匹配?}
K -->|否| L[修正或报错]
K -->|是| M[合并到 jobs 数组]
M --> N[再次校验完整 JSON]
N --> O[写入文件]
O --> P[执行 restart-gateway.sh]
排查流程（cron 不工作 / 定时任务看不到时）
当用户反馈 cron 相关问题时，不要直接重启 Gateway。先执行：
bash {{SKILL_DIR}}/scripts/validate-jobs-json.sh ~/.openclaw/cron/jobs.json
- 若校验失败：按「1. 写入前必须校验」中的流程：报告错误 → 询问是否修复 → 修复后再次校验
- 若校验通过：jobs.json 格式正常，问题可能在其他（如 DeskClaw 客户端传
all 给 cron.list、Gateway 未启动等），可排查 Gateway 日志或建议用户重启
1. 写入前必须校验
在任何写入 jobs.json 的操作之前，先执行：
bash {{SKILL_DIR}}/scripts/validate-jobs-json.sh ~/.openclaw/cron/jobs.json
- 若校验失败：
- 向用户报告错误详情（JSON 解析失败位置、payload 不匹配的 job 等）
- 询问用户：「当前 jobs.json 存在格式问题，是否需要我帮你修复？」
- 若用户同意 → 尝试修复（见下方「修复校对」）→ 再次校验
- 若用户拒绝或无法修复 → 中止，不写入
- 若校验通过：再构造新 job 并合并
1.1 修复校对（校验失败时）
当用户同意修复时，按以下优先级尝试：
| 错误类型 | 修复方式 |
|---|
| JSON 解析失败（如漏逗号） | 用 json.load + json.dump 重新序列化，或手动补逗号 |
sessionTarget: "isolated" 但 payload.kind: "message" | 改为 kind: "agentTurn"，text 改为 message |
sessionTarget: "main" 但 payload.kind: "message" | 改为 kind: "systemEvent"，保持 text |
| 缺必填字段 | 按 schema 补全或标记为需用户确认 |
修复后必须再次运行校验脚本，通过后再继续。修复完成并校验通过后，执行 {{SKILL_DIR}}/scripts/restart-gateway.sh，否则 cron 不会加载新配置。
2. payload 规则速查
| sessionTarget | payload.kind | 提示内容字段 |
|---|
main | systemEvent | text |
isolated | agentTurn | message |
常见错误：
isolated 用 payload.kind: "message" → 会报 isolated job requires payload.kind=agentTurnagentTurn 用 text 而非 message → 必须用 message
3. JSON 追加规则
向 jobs 数组追加新 job 时：
- 确保前一元素末尾有逗号：
}, 后接 {，不能是 } 后直接 {
- 推荐：用 Python
json.load + json.dump 读写，避免手写 JSON 漏逗号
- 写入后再次运行校验脚本确认，然后执行
{{SKILL_DIR}}/scripts/restart-gateway.sh
4. 禁止事项
- 不要读写
workspace/cron/jobs.json，cron 配置只在 ~/.openclaw/cron/jobs.json
- 不要传
all 给 cron.list（Gateway 不支持该参数）
- 不要让
cron.runs 的 limit 超过 200
- 不要在 Gateway 运行时手动编辑 jobs.json（Gateway 会覆盖）
5. 参考
- 完整 schema、示例、isolated vs main 对照：
{{SKILL_DIR}}/references/schema.md
- 官方文档：OpenClaw Cron Jobs
