OpenClaw Cron Health

Purpose

Use this skill to create or port a read-only cron health check for one OpenClaw instance. The deliverable is a small instance-local kit plus a manual setup pass, not a magic zero-config monitor.

The health check should answer:

• Which OpenClaw scheduled jobs are enabled, paused, stale, failing, or failing delivery
• Which system crons exist and whether their scripts or commands still exist
• Whether logs or safe validation commands prove jobs are running
• Whether recent logs show current failures
• Whether configured registry or callback documentation needs manual attention
• What remains actionable after the run

When To Use

Use this skill when the user asks to:

• set up an OpenClaw cron health report
• port a cron health-check routine to another OpenClaw server
• make cron monitoring deterministic or script-only
• audit OpenClaw scheduled jobs plus system crons
• prepare a reusable cron health-check kit or ClawHub skill

Do not use this skill for general host security hardening, uptime monitoring, application observability, or non-OpenClaw runtimes unless the user explicitly asks to include them as project-specific checks.

Mental Model

This is portable as a framework, not as a plug-and-play binary. Every OpenClaw instance can differ in scheduler metadata, service manager, cron layout, log locations, delivery targets, and project jobs. The skill provides the kit and the manual setup procedure; the agent must fill config values from the destination instance.

Service managers are not scheduler sources. Use OpenClaw scheduler metadata such as a safe cron list command, API output, or read-only jobs file as the source of truth for OpenClaw scheduled jobs.

This skill may touch the OpenClaw gateway only to read scheduler facts: cron inventory, last/next run metadata, delivery errors, and consecutive failure state. It must not manage, restart, or treat gateway runtime health as its core job.

Gateway runtime health belongs to a separate external monitor. If this health check is scheduled inside the OpenClaw gateway, it cannot alert when the gateway is down because the gateway must be alive to run the job. At most, an in-gateway run may include service state as optional diagnostic context.

Required Shape

Create a local, instance-specific package with this shape:

openclaw-cron-health/
├── config.json
├── openclaw_cron_health_check.py
└── README.local.md

Use bundled resources as the starting point:

• templates/cron-health-config.json for runtime configuration
• scripts/openclaw_cron_health_check.py for the deterministic checker
• references/setup-manual.md for the agent setup procedure
• references/report-format.md for report structure
• references/porting-checklist.md before enabling the schedule

Keep all destination-specific values in config.json. Do not bake chat IDs, cron IDs, server paths, registry paths, tokens, or project paths into the skill itself.

Runtime Rules

• Prefer a script-only OpenClaw scheduled job with no agent reasoning during routine execution.
• The script prints exactly one delivery-ready report to stdout and exits 0 for successful inspection runs, even when the report contains warnings.
• Empty stdout may mean no delivery on some script-only schedulers, so routine health reports should print unless configured as threshold-only alerts.
• Use absolute paths in generated config and local docs.
• Keep the health-check run read-only.
• Treat registry/callback reconciliation as report-only unless a separate maintenance workflow explicitly authorizes documentation writes.
• Never create, edit, pause, or delete real scheduled jobs during the health-check run.
• Never print secrets, raw environment variables, complete prompts, full config, or token-like strings.

Workflow

1. Read references/setup-manual.md.

   Follow it as the configuration procedure. Do not guess instance paths or delivery targets.

2. Identify the destination OpenClaw instance.

   Read local OpenClaw paths, scheduler storage, available OpenClaw scheduler list commands or read-only jobs files, target delivery channel, and project-specific scheduled jobs. Use only facts from that instance.

3. Generate the instance package.

   Copy the config and script templates into an instance-local directory. Fill config values conservatively. Leave optional sections empty unless there is local evidence for them.

4. Configure checks.

   In config.json, define:

   • OpenClaw job source: safe list command or read-only jobs file
   • logs to inspect
   • crontab command/file sources separately from run-parts directories
   • optional gateway service diagnostics only if explicitly useful; never as the primary purpose
   • known system jobs with expected log freshness
   • project scheduler validations with safe dry-run/status commands
   • delivery target and report preferences
   • redaction patterns

5. Validate manually before scheduling.

   Run the script once from the destination account. Confirm it can read configured files, redacts sensitive output, reports stale or missing proof as WARNING, and never marks ambiguous jobs OK.

6. Create the scheduled job.

   Create it as a deterministic script-only OpenClaw cron. Prefer delivery to the origin chat/topic when created from the desired destination, or use the instance's explicit target format.

7. Verify after creation.

   List the scheduled job and verify job name, schedule, next run, script path, delivery target, and script-only/no-agent mode. Run a force test only if the instance supports safe manual execution.

Classification Rules

Use these statuses consistently:

• CRITICAL: missing required script or binary, repeated current failures, required log missing, required service/process failed, enabled OpenClaw job has repeated errors, or a locally validated recurring job has no viable next run.
• WARNING: stale logs, 1-5 recent error lines, delivery error, ambiguous command parsing, no runtime proof, failed safe validation, unexpected paused job, expected OpenClaw job missing, or expected service/process not found.
• INFO: intentionally paused job, inventory-only item, optional service not installed, disabled timer without failure, one-shot completed job, or metadata unavailable from a read-only source.
• OK: required command exists, runtime proof is fresh, no recent errors, required service/process is healthy, and no current OpenClaw error or delivery state exists.

Never mark a job OK just because it exists.

System Cron Validation

Validate each non-paused system cron in three levels:

1. Script or command existence.

   Check script path, readable bit, executable bit when direct execution is expected, and binary availability. For shell-compound commands that cannot be safely parsed, mark existence as WARNING, not CRITICAL.

2. Runtime proof.

   Prefer fresh logs. If no logs exist, use a configured safe validation command, OpenClaw run metadata, systemd timer metadata, host service state, or another read-only proof. If none exists, mark WARNING.

3. Recent errors.

   Inspect recent relevant log lines for default error patterns such as error, fatal, exception, panic, ENOENT, EACCES, EPERM, non-zero exit codes, tracebacks, permission failures, and missing files. Redact and truncate before reporting.

OpenClaw Job Validation

For each enabled OpenClaw scheduled job, collect available metadata:

• id
• name
• schedule
• timezone or anchor
• last run time
• next run time, when exposed
• last status
• delivery error
• consecutive errors
• paused/enabled state
• script path or runtime mode when visible

List every enabled OpenClaw job in the report. Summarize paused jobs unless unexpected or relevant.

If the scheduler stores script paths, check that configured scripts exist. If metadata shape differs by OpenClaw version, parse conservatively. Missing nextRun from a read-only jobs file is INFO unless local metadata proves the job has no viable next run.

Optional Gateway Diagnostics

Do not make gateway runtime health the responsibility of this skill.

Gateway service checks are optional diagnostics. They may help explain odd cron metadata when the gateway is degraded, but they are not required for ordinary cron health reports.

If the user wants gateway-down monitoring, build a separate external monitor that runs outside the gateway, for example a systemd timer, host cron, OpenClawNurse, or uptime probe.

When optional diagnostics are explicitly configured, check only safe read-only commands, for example:

• systemctl --user is-active openclaw-gateway.service
• systemctl --user status openclaw-gateway.service --no-pager
• a project-specific status command

Inside an OpenClaw-scheduled run, report gateway service state as diagnostic context only. Do not treat it as proof that gateway-down alerting works.

Registry And Callback Documentation

Keep registry reconciliation report-only by default.

If enabled:

• Compare enabled OpenClaw scheduled jobs with configured registry docs.
• Detect missing registry entries for existing jobs.
• Detect stale entries for removed jobs.
• Detect system crons missing from the registry.
• Detect registry system entries no longer present in crontab.
• Report suggested documentation changes under Registry Notes.

The routine health check must not write registry or callback files. If writes are desired, use a separate maintenance task with lock, backup, and atomic replace.

Privacy

Apply redaction before printing any command output, log line, delivery error, config-derived value, last relevant line, or registry note.

Redact:

• token/API-key/secret/password/authorization assignments
• bearer tokens
• long token-like strings
• OpenAI-style sk- keys
• raw environment variables
• full config content
• full cron prompts or private task bodies

Truncate report lines so chat delivery remains readable.

Publishing Checklist

Before publishing this skill or an instance-specific derivative:

• No server-specific chat IDs, job IDs, paths, registry paths, project names, or tokens remain.
• The skill says OpenClaw only.
• Runtime config is separated from instructions.
• The script can run without non-stdlib Python dependencies.
• Template optional sections default to empty arrays, not placeholders that produce false CRITICAL reports.
• Run-parts directories are configured separately from crontab files.
• Registry reconciliation is report-only by default.
• The report format is stable and concise.
• The setup manual tells agents how to configure a destination instance.
• The porting checklist tells users to validate manually before enabling a schedule.