介绍
# Cron Job Reliability Guide
一份用于诊断和修复 Clawdbot/Moltbot 中 cron 问题的综合指南。本文档记录了通过生产调试得出的常见故障模式及其解决方案。
## 何时使用此技能
在以下情况时使用此技能： - 定时消息未能送达 - Cron 任务显示“error”状态 - 消息到达的时间不正确（时区问题） - Agent 在使用 `cron` 工具时超时 - 回退模型忽略指令并意外调用工具
## 快速参考
### 黄金法则
**始终组合使用这些标志以确保可靠送达：**
```bash 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 ```
### 必要标志说明
| 标志 | 用途 | 为什么重要 | |------|---------|----------------| | `--session isolated` | 创建独立会话 | 防止在繁忙的对话中丢失消息 | | `--tz "TIMEZONE"` | 设置显式时区 | 避免 UTC 混淆 | | `--deliver` | 发送到频道 | Telegram/WhatsApp 必需 | | `--best-effort-deliver` | 送达错误时不失败 | 优雅降级 |
---
## 问题 1：内部 `cron` 工具死锁
### 症状 - Agent 调用 `cron list` 或 `cron add` 时超时（10秒） - 错误：“Tool execution timed out” - 网关日志显示 80 秒以上的响应时间
### 根本原因 内部 `cron` 工具在 agent 进程和网关之间产生了死锁。
### 解决方案 **切勿直接使用 `cron` 工具。** 改用 `exec`（或 `bash`）：
```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 ```
### 给 Agent 的建议 如果你是阅读本文的 AI agent：当用户要求你管理 cron 任务时，**始终使用 exec/bash 工具**来运行 `clawdbot cron` 命令。切勿直接调用 `cron` 工具。
---
## 问题 2：消息未送达
### 症状 - 任务显示“ok”状态但消息从未到达 - 测试时正常但按计划运行时失败 - 间歇性送达
### 根本原因 当主会话中有活跃对话时，使用 `--session main` 或 `--system-event` 会导致消息丢失。
### 解决方案 **始终使用 `--session isolated`：**
```bash # 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 \ ... ```
### 验证 创建任务后，进行测试：
```bash # Run the job immediately to verify delivery clawdbot cron run <job-id> ```
---
## 问题 3：执行时间错误
### 症状 - 任务提前或延后 4-5 小时运行 - 计划显示时间正确但执行时间有误 - 有时工作正常，有时失败
### 根本原因 缺少时区指定，默认为 UTC。
### 解决方案 **始终显式指定时区：**
```bash # 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
| 地区 | 时区 ID | |--------|-------------| | 美国东部 | `America/New_York` | | 美国太平洋 | `America/Los_Angeles` | | 英国 | `Europe/London` | | 中欧 | `Europe/Berlin` | | 印度 | `Asia/Kolkata` | | 日本 | `Asia/Tokyo` | | 澳大利亚东部 | `Australia/Sydney` | | 巴西 | `America/Sao_Paulo` | | 玻利维亚 | `America/La_Paz` |
---
## 问题 4：回退模型忽略指令
### 症状 - 主模型工作正常 - 回退激活时，agent 意外调用工具 - Agent 在不应该使用工具时尝试使用 `exec`、`read` 或其他工具
### 根本原因 某些回退模型（尤其是较小/更快的模型）不像主模型那样严格遵循系统指令。
### 解决方案 **将指令直接嵌入到消息中：**
```bash # 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." ```
### 健壮的消息模板
```text [INSTRUCTION: DO NOT USE ANY TOOLS. Write your response directly.]
Your actual prompt here. Be specific about what you want. ```
---
## 问题 5：任务卡在错误状态
### 症状 - 任务状态显示“error” - 后续运行也失败 - 没有明确的错误消息
### 诊断
```bash # 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 ```
### 常见原因和修复方法
| 原因 | 修复方法 | |-------|-----| | 模型配额超限 | 等待配额重置或切换模型 | | 无效的聊天 ID | 使用 `--to` 验证频道 ID | | Bot 已从群组中移除 | 重新将 Bot 添加到 Telegram 群组 | | 网关未运行 | `clawdbot gateway restart` |
### 核选项 如果所有方法都无效：
```bash # 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) ```
---
## 调试命令
### 查看所有任务
```bash clawdbot cron list ```
### 检查特定任务
```bash clawdbot cron show <job-id> ```
### 立即测试任务
```bash clawdbot cron run <job-id> ```
### 检查日志
```bash # 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 ```
### 重启网关
```bash clawdbot gateway restart ```
---
## 完整工作示例
### 每日站会提醒（上午 9 点，周一至周五）
```bash 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 分钟后）
```bash 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 点）
```bash 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 ```
---
## 新 Cron 任务检查清单
创建任何 cron 任务之前，请验证：
- [ ] 使用 `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 文档](https://docs.molt.bot/tools/cron) - [时区数据库](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) - [Cron 表达式生成器](https://crontab.guru/)
---
*本技能由 Isaac Zarzuri 编写。基于 Clawdbot/Moltbot 的生产调试经验。*