Cron Job Reliability Guide

A comprehensive guide to diagnosing and fixing cron job issues in Clawdbot/Moltbot. This skill documents common failure patterns and their solutions, learned through production debugging.

When to Use This Skill

Use this skill when:

• Scheduled messages aren't being delivered
• Cron jobs show "error" status
• Messages arrive at wrong times (timezone issues)
• The agent times out when using the cron tool
• Fallback models ignore instructions and call tools unexpectedly

Quick Reference

The Golden Rule

Always use these flags together for reliable delivery:

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

Essential Flags Explained

Problem 1: Internal cron Tool Deadlock

Symptoms

• Agent times out (10s) when calling cron list or cron add
• Error: "Tool execution timed out"
• Gateway logs show 80s+ response times

Root Cause

The internal cron tool creates a deadlock between the agent process and gateway.

Solution

Never use the cron tool directly. Use exec (or bash) instead:

# 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

For Agents

If you're an AI agent reading this: when the user asks you to manage cron jobs, always use the exec/bash tool to run clawdbot cron commands. Never invoke the cron tool directly.

Problem 2: Messages Not Delivered

Symptoms

• Job shows "ok" status but message never arrives
• Works in testing but fails on schedule
• Intermittent delivery

Root Cause

Using --session main or --system-event causes messages to get lost when there's an active conversation in the main session.

Solution

Always use --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 \
  ...

Verification

After creating a job, test it:

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

Problem 3: Wrong Execution Time

Symptoms

• Job runs 4-5 hours early or late
• Schedule shows correct time but execution is off
• Works correctly sometimes, fails other times

Root Cause

Missing timezone specification defaults to UTC.

Solution

Always specify timezone explicitly:

# 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" \
  ...

Common Timezone IDs

Problem 4: Fallback Models Ignore Instructions

Symptoms

• Primary model works correctly
• When fallback activates, agent calls tools unexpectedly
• Agent tries to use exec, read, or other tools when it shouldn't

Root Cause

Some fallback models (especially smaller/faster ones) don't follow system instructions as strictly as primary models.

Solution

Embed instructions directly in the message:

# 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."

Robust Message Template

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

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

Problem 5: Job Stuck in Error State

Symptoms

• Job status shows "error"
• Subsequent runs also fail
• No clear error message

Diagnosis

# 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

Common Causes and Fixes

Nuclear Option

If nothing works:

# 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)

Debugging Commands

View All Jobs

clawdbot cron list

Inspect Specific Job

clawdbot cron show <job-id>

Test Job Immediately

clawdbot cron run <job-id>

Check Logs

# 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

Restart Gateway

clawdbot gateway restart

Complete Working Examples

Daily Standup Reminder (9 AM, Mon-Fri)

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

One-Shot Reminder (20 minutes from now)

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

Weekly Report (Friday 5 PM)

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

Checklist for New Cron Jobs

Before creating any cron job, verify:

• Using exec: clawdbot cron add (not the cron tool directly)
• --session isolated is set
• --tz "YOUR_TIMEZONE" is explicit
• --deliver --channel CHANNEL --to "ID" for message delivery
• --best-effort-deliver for graceful failures
• Message starts with [INSTRUCTION: DO NOT USE ANY TOOLS]
• Tested with clawdbot cron run <id> after creation

Related Resources

• Clawdbot Cron Documentation
• Timezone Database
• Cron Expression Generator

Skill authored by Isaac Zarzuri. Based on production debugging experience with Clawdbot/Moltbot.