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

--session isolated

--tz "TIMEZONE"

--deliver

--best-effort-deliver

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

Solution

Never use the

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

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

cron

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

--system-event

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

America/New_York

America/Los_Angeles

Europe/London

Europe/Berlin

Asia/Kolkata

Asia/Tokyo

Australia/Sydney

America/Sao_Paulo

America/La_Paz

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

--to

clawdbot gateway restart

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.