openclaw - 💡(How to fix) Fix Rename 'cron' subsystem to disambiguate from system cron

Summary

OpenClaw's internal scheduler is named cron (CLI: openclaw cron, tool: cron, config block: cron, state dir: ~/.openclaw/cron/, session keys: agent:<id>:cron:<job-id>:run:<session-id>). This name directly collides with Unix system cron, and the collision causes real, repeatable confusion for AI agents operating in OpenClaw environments.

Why this matters

When an agent (or a user) says "cron job" in a sentence, there is no way to tell whether they mean:

• Unix crontab(5) / /etc/cron.d/ / systemd timers — the operating system scheduler that runs as root or a system user with strict, deterministic timing
• OpenClaw's internal scheduler — an agentic scheduler that runs agent turns or system events and has soft timing (per project hearsay, jobs can fire up to ~30 minutes late and may be skipped/dropped under load)

These are fundamentally different schedulers with fundamentally different guarantees. Conflating them under one name has caused at least one debugging session where an agent searched system cron, /etc/cron.d/, systemd timers, and several user crontabs trying to find a job that lived in ~/.openclaw/cron/jobs.json the entire time — and concluded "no cron job exists" multiple times before stumbling onto the OpenClaw cron registry by inspecting state files directly. The agent had already used cron action=list and it returned an empty result because the default filter scoped to the current agent only.

Concrete failure modes

1. Timing assumptions silently drift. A user who says "I need this to run at exactly 9:30 AM ET" reasonably assumes system-cron precision when the agent files an OpenClaw cron job. The agent doesn't push back because the names match. The job fires at 9:47 AM instead, and a market-open trade misses the window.
2. Agents fail to locate jobs. "Find Ticker's cron jobs" → agent searches the wrong scheduler. cron action=list returns nothing because the default filter is by-agent and Ticker's jobs are registered under a different agent. The correct lookup (jq '.jobs[] | select(.agentId == \"ticker\")' ~/.openclaw/cron/jobs.json) requires knowing the file layout, not just the tool surface.
3. Documentation and skill files get ambiguous. Skills like `session-logs`, agent bootstrap context, and incident postmortems use "cron" without qualification. Readers have to infer context.
4. The cron tool's default behavior reinforces the confusion. cron action=list filters by the calling agent's id by default. That's reasonable scoping, but the name is so overloaded that the user/agent doesn't realize they're seeing a filtered view.

Proposed rename

Pick one of (in rough order of preference):

• scheduler — clearest, no overlap with any OS concept. CLI: openclaw scheduler ..., tool: scheduler, state dir: ~/.openclaw/scheduler/.
• taskq / tasks — works if scheduled tasks are conceptually unified with the existing tasks table/runtime. Risk: conflict with openclaw tasks (background task listing).
• agenda — distinctive, no overlap, but less self-documenting.

I lean scheduler because:

• Zero overlap with any other scheduling concept the agent might encounter
• Self-documents what the subsystem does
• Pluralizable (scheduler.jobs, scheduler add, etc.) without name clash

Migration path

1. Add scheduler as the new canonical name; keep cron as a documented alias for one major version
2. Deprecation warning on cron-prefixed CLI/tool/config use after the rename ships
3. Migrate ~/.openclaw/cron/ → ~/.openclaw/scheduler/ on first boot with a symlink fallback
4. Update agent bootstrap context, skills, and docs to use scheduler exclusively in new prose
5. Drop the cron alias after a stability window (one major version + one minor)

Out of scope for this issue

• Changing the timing semantics of the scheduler (soft vs strict timing is a separate conversation — see related ecosystem discussion about moving timing-critical jobs to system cron)
• Renaming the inbound message hook system, any plugin id with "cron" in it (handle in followups if needed)

Acceptance criteria

• New name (scheduler or alternative) lands in CLI, tool surface, config schema, state dir, session keys, and docs
• Old cron name remains a working alias with a deprecation warning for one major version
• Bootstrap context for agents is updated to use the new name in normative prose
• Migration path for existing ~/.openclaw/cron/ state directories is automatic and lossless

Context

Filed by NOVA on behalf of I)ruid (Dustin D. Trammell) on 2026-05-24, after a real debugging incident on the nova-workspace #6 SE workflow where this naming collision wasted Step 1 investigation time.