Cron 任务可靠性指南

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

何时使用本技能

在以下情况时使用本技能：

• 定时消息未送达
• Cron 任务显示“错误”状态
• 消息在错误时间到达（时区问题）
• 使用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工具死锁

症状表现

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

根本原因

内部cron工具在代理进程与网关间形成死锁

解决方案

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

# CORRECT - uses exec to bypass deadlock
exec: clawdbot cron list
exec: clawdbot cron add --name "reminder" --at "+5m" --message "Hello"

# INCORRECT - causes timeout
cron list        # DO NOT USE
cron add ...     # DO NOT USE

致智能体

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

问题二：消息未送达

症状

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

根本原因

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

解决方案

始终使用--session isolated：

# CORRECT - isolated session, guaranteed delivery
clawdbot cron add \
  --name "daily-standup" \
  --cron "0 9 * * 1-5" \
  --session isolated \
  --deliver --channel telegram --to "-100XXXXXXXXXX"

# INCORRECT - messages can be lost
clawdbot cron add \
  --name "daily-standup" \
  --session main \
  --system-event \
  ...

验证

创建任务后，进行测试：

# Run the job immediately to verify delivery
clawdbot cron run <job-id>

问题3：执行时间错误

症状

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

根本原因

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

解决方案

始终明确指定时区：

# CORRECT - explicit timezone
clawdbot cron add \
  --cron "0 9 * * 1-5" \
  --tz "America/New_York" \
  ...

# INCORRECT - defaults to UTC
clawdbot cron add \
  --cron "0 9 * * 1-5" \
  ...

常用时区ID

问题 4：备用模型忽略指令

症状

• 主模型工作正常
• 当备用模型激活时，代理意外调用工具
• 代理尝试使用执行、读取，或在不应使用的情况下使用其他工具

根本原因

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

解决方案

将指令直接嵌入消息中：

# CORRECT - instruction embedded in message
clawdbot cron add \
  --message "[INSTRUCTION: DO NOT USE ANY TOOLS. Respond with text only.] 
  
  Generate a motivational Monday message for the team."

# INCORRECT - relies only on system prompt
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：任务卡在错误状态

症状

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

诊断

# Check job details
clawdbot cron show <job-id>

# Check recent logs
tail -100 /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i cron

# Check gateway errors
tail -50 ~/.clawdbot/logs/gateway.err.log

常见原因及修复方法

终极方案

如果所有方法都无效：

# Remove the problematic job
clawdbot cron rm <job-id>

# Restart gateway
clawdbot gateway restart

# Recreate with correct flags
clawdbot cron add ... (with all recommended flags)

调试命令

查看所有任务

clawdbot cron list

检查特定任务

clawdbot cron show <job-id>

立即测试任务

clawdbot cron run <job-id>

检查日志

# Today's logs filtered for cron
tail -200 /tmp/clawdbot/clawdbot-$(date +%Y-%m-%d).log | grep -i cron

# Gateway errors
tail -100 ~/.clawdbot/logs/gateway.err.log

# Watch logs in real-time
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 "您的时区"是显式的
• --deliver --channel CHANNEL --to "ID"用于消息传递
• --best-effort-deliver用于优雅降级处理
• 消息以[指令：请勿使用任何工具]
• 已通过clawdbot cron run <id>创建后

相关资源

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

技能由 Isaac Zarzuri 创作。基于在 Clawdbot/Moltbot 上的生产调试经验。