name: ez-cronjob
description: 修复 Clawdbot/Moltbot 中常见的定时任务故障 - 消息投递问题、工具超时、时区错误和模型回退问题。
author: Isaac Zarzuri
author-url: https://x.com/Yz7hmpm
version: 1.0.0
homepage: https://www.metacognitivo.com
repository: https://github.com/ProMadGenius/clawdbot-skills
metadata: {"agentskills":{"category":"troubleshooting","tags":["cron","scheduling","telegram","debugging","moltbot","clawdbot"]}}

定时任务可靠性指南

一份用于诊断和修复 Clawdbot/Moltbot 中定时任务问题的综合指南。本技能文档记录了通过生产环境调试总结出的常见故障模式及其解决方案。

何时使用本技能

在以下情况时使用本技能：
- 计划消息未送达
- 定时任务显示“错误”状态
- 消息在错误的时间到达（时区问题）
- 代理在使用 cron 工具时超时
- 回退模型忽略指令并意外调用工具

快速参考

黄金法则

为确保可靠投递，请始终一起使用以下标志：

clawdbot cron add \
  --name "my-job" \
  --cron "0 9 * * 1-5" \
  --tz "America/New_York" \
  --session isolated \
  --message "[INSTRUCTION: DO NOT USE ANY TOOLS] Your prompt here" \
  --deliver --channel telegram --to "CHAT_ID" \
  --best-effort-deliver

核心标志详解

问题 1：内部 cron 工具死锁

症状

• 代理调用 cron list 或 cron add 时超时（10秒）
• 错误：“工具执行超时”
• 网关日志显示 80 秒以上的响应时间

根本原因

内部 cron 工具在代理进程和网关之间造成死锁。

解决方案

切勿直接使用 cron 工具。 改用 exec（或 bash）：

# 正确 - 使用 exec 绕过死锁
exec: clawdbot cron list
exec: clawdbot cron add --name "reminder" --at "+5m" --message "Hello"

# 错误 - 导致超时
cron list        # 请勿使用
cron add ...     # 请勿使用

给 AI 代理的提示

如果你是正在阅读此文的 AI 代理：当用户要求你管理定时任务时，务必使用 exec/bash 工具来运行 clawdbot cron 命令。切勿直接调用 cron 工具。

问题 2：消息未送达

症状

• 任务显示“正常”状态，但消息从未到达
• 测试时工作正常，但按计划执行时失败
• 间歇性投递失败

根本原因

使用 --session main 或 --system-event 会导致当主会话中存在活跃对话时消息丢失。

解决方案

始终使用 --session isolated：

# 正确 - 隔离会话，保证投递
clawdbot cron add \
  --name "daily-standup" \
  --cron "0 9 * * 1-5" \
  --session isolated \
  --deliver --channel telegram --to "-100XXXXXXXXXX"

# 错误 - 消息可能丢失
clawdbot cron add \
  --name "daily-standup" \
  --session main \
  --system-event \
  ...

验证

创建任务后，进行测试：

# 立即运行任务以验证投递
clawdbot cron run <job-id>

问题 3：执行时间错误

症状

• 任务提前或延后 4-5 小时运行
• 计划显示正确时间，但实际执行时间有偏差
• 有时工作正常，有时失败

根本原因

缺少时区指定，默认使用 UTC。

解决方案

始终明确指定时区：

# 正确 - 明确指定时区
clawdbot cron add \
  --cron "0 9 * * 1-5" \
  --tz "America/New_York" \
  ...

# 错误 - 默认为 UTC
clawdbot cron add \
  --cron "0 9 * * 1-5" \
  ...

常用时区 ID

问题 4：回退模型忽略指令

症状

• 主模型工作正常
• 当回退模型激活时，代理意外调用工具
• 代理在不应该的情况下尝试使用 exec、read 或其他工具

根本原因

一些回退模型（尤其是较小/较快的模型）不像主模型那样严格遵循系统指令。

解决方案

将指令直接嵌入消息中：

# 正确 - 指令嵌入消息中
clawdbot cron add \
  --message "[INSTRUCTION: DO NOT USE ANY TOOLS. Respond with text only.] 

  Generate a motivational Monday message for the team."

# 错误 - 仅依赖系统提示
clawdbot cron add \
  --message "Generate a motivational Monday message for the team."

健壮的消息模板

[INSTRUCTION: DO NOT USE ANY TOOLS. Write your response directly.]

Your actual prompt here. Be specific about what you want.

问题 5：任务卡在错误状态

症状

• 任务状态显示“错误”
• 后续运行也失败
• 没有明确的错误信息

诊断

# 检查任务详情
clawdbot cron show <job-id>

# 检查最近日志
tail -100 /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i cron

# 检查网关错误
tail -50 ~/.clawdbot/logs/gateway.err.log

常见原因及修复方法

终极方案

如果所有方法都无效：

# 移除有问题的任务
clawdbot cron rm <job-id>

# 重启网关
clawdbot gateway restart

# 使用正确的标志重新创建
clawdbot cron add ... (使用所有推荐标志)

调试命令

查看所有任务

clawdbot cron list

检查特定任务

clawdbot cron show <job-id>

立即测试任务

clawdbot cron run <job-id>

检查日志

# 筛选今日日志中的 cron 相关条目
tail -200 /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i cron

# 网关错误日志
tail -100 ~/.clawdbot/logs/gateway.err.log

# 实时查看日志
tail -f /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep --line-buffered cron

重启网关

clawdbot gateway restart

完整工作示例

每日站会提醒（周一至周五，上午 9 点）

clawdbot cron add \
  --name "daily-standup-9am" \
  --cron "0 9 * * 1-5" \
  --tz "America/New_York" \
  --session isolated \
  --message "[INSTRUCTION: DO NOT USE ANY TOOLS. Write directly.]

Good morning team! Time for our daily standup.

Please share:
1. What did you accomplish yesterday?
2. What are you working on today?
3. Any blockers?

@alice @bob" \
  --deliver --channel telegram --to "-100XXXXXXXXXX" \
  --best-effort-deliver

一次性提醒（从现在起 20 分钟后）

clawdbot cron add \
  --name "quick-reminder" \
  --at "+20m" \
  --delete-after-run \
  --session isolated \
  --message "[INSTRUCTION: DO NOT USE ANY TOOLS.]

Reminder: Your meeting starts in 10 minutes!" \
  --deliver --channel telegram --to "-100XXXXXXXXXX" \
  --best-effort-deliver

每周报告（周五下午 5 点）

clawdbot cron add \
  --name "weekly-report-friday" \
  --cron "0 17 * * 5" \
  --tz "America/New_York" \
  --session isolated \
  --message "[INSTRUCTION: DO NOT USE ANY TOOLS.]

Happy Friday! Time to wrap up the week.

Please share your weekly highlights and any items carrying over to next week." \
  --deliver --channel telegram --to "-100XXXXXXXXXX" \
  --best-effort-deliver

新建定时任务检查清单

创建任何定时任务前，请确认：

• [ ] 使用 exec: clawdbot cron add（而非直接使用 cron 工具）
• [ ] 设置了 --session isolated
• [ ] 明确指定了 --tz "YOUR_TIMEZONE"
• [ ] 设置了 --deliver --channel CHANNEL --to "ID" 用于消息投递
• [ ] 设置了 --best-effort-deliver 以实现优雅降级
• [ ] 消息以 [INSTRUCTION: DO NOT USE ANY TOOLS] 开头
• [ ] 创建后使用 clawdbot cron run <id> 进行了测试

相关资源

• Clawdbot 定时任务文档
• 时区数据库
• Cron 表达式生成器

技能作者：Isaac Zarzuri。基于 Clawdbot/Moltbot 的生产环境调试经验。