RFC 0007: Pluggable scheduler seam in gateway

[amittell]

This RFC proposes a narrow plugin-SDK seam that lets an external scheduler plugin own scheduled-job dispatch while the gateway keeps owning heartbeats and run-state ingestion. The built-in cron stays the default; when a scheduler plugin declares owns: "scheduled-jobs", the gateway disables its in-process cron at startup and routes job registration through the plugin runtime.

Why this RFC

Operators with workflows that need durability, retries, approvals, multi-step chains, or full run history reach for external schedulers (notably openclaw-scheduler, a SQLite-backed sibling service). Today those tools can only talk to the gateway through the public HTTP surface and cannot register scheduled work that the gateway considers first-class. The seam proposed here would let the same external runtime become the canonical scheduler so its runs surface in gateway status, hooks, and transcript mirroring.

Scope

• Three runtime functions: registerScheduledJob, cancelScheduledJob, listScheduledJobs.
• One discovery field: owns: "scheduled-jobs" on kind: scheduler manifests.
• Three run-state event shapes: onStart, onComplete, onError.
• Heartbeats stay in core, not behind this seam.
• No new compiled dependencies in the gateway.

Existence proof

The consumer side is already running. openclaw-scheduler has been deployed on two gateways (mac-mini.lan and rh-bot.lan) for several weeks, talking to OpenClaw only through the public HTTP surface. The skill is listed on ClawHub as durable-scheduler@1.0.0. What's missing is the seam.

If the shape proposed here is accepted, I'll carry the reference implementation as a follow-up PR against openclaw/openclaw. Drafting it now without an accepted seam shape would mean rewriting it against whatever the final contract looks like, which is why I'm leading with the RFC.

Notes

• A diagram of the discovery flow will go under rfcs/0006/ in a follow-up revision once the seam shape is settled.
• Draft because the runtime contract is the right place to take feedback before any code lands. Several unresolved questions in the RFC body are explicit requests for maintainer input.

[clawsweeper]

Codex review: needs changes before merge. Reviewed June 7, 2026, 9:21 PM ET / 01:21 UTC.

Summary
Adds rfcs/0007-pluggable-scheduler.md, a design RFC for a scheduler plugin kind, scheduled-job registration/list/cancel runtime APIs, run-state ingestion events, and startup fallback behavior.

Reproducibility: not applicable. this is a design RFC rather than a runtime bug report. The concrete review check is source/process conformance of the added Markdown file against current main.

Review metrics: 2 noteworthy metrics.

• RFC surface: 1 Markdown file added. The PR is design-only, so process conformance and API direction are the main review concerns.
• Lifecycle metadata: 2 required keys missing. Current main requires status and issue frontmatter for new RFCs before merge.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Add status: draft and blank issue to the RFC frontmatter.
• Resolve the scheduler plugin contract questions through maintainer RFC review.

Risk before merge

• [P1] Accepting this RFC would establish a new scheduler plugin kind, ownership token, runtime method set, startup handoff behavior, and run-state event contract that future implementations and external plugins would need to preserve or migrate carefully.
• [P1] The RFC intentionally leaves API-design questions open, so maintainer product/API approval is still needed before treating the seam as the accepted implementation direction.

Maintainer options:

1. Keep draft while the contract settles (recommended)
   Leave the RFC unmerged until maintainers explicitly approve or narrow the scheduler kind, ownership token, runtime methods, and run-state event contract.
2. Accept the compatibility contract
   Maintainers can accept the API risk if they want this RFC to become the compatibility target for later OpenClaw and external scheduler implementations.
3. Narrow the API before acceptance
   Revise the RFC to reduce or stage the plugin contract if maintainers do not want the full ownership/runtime/event surface accepted at once.

Next step before merge

• [P2] A repair worker can make the narrow frontmatter fix, while the scheduler plugin contract remains a maintainer-owned RFC decision.

Security
Cleared: The diff is a Markdown-only RFC and does not add executable code, dependencies, workflows, or secrets handling.

Review findings

• [P2] Add the required RFC lifecycle fields — rfcs/0007-pluggable-scheduler.md:1-7

Review details

Best possible solution:

Add the required draft lifecycle metadata, then keep the PR in RFC review until maintainers explicitly accept, narrow, or reject the scheduler plugin contract and create the implementation issue required by the RFC process.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a design RFC rather than a runtime bug report. The concrete review check is source/process conformance of the added Markdown file against current main.

Is this the best way to solve the issue?

Not yet merge-ready; the RFC path is appropriate for this kind of plugin SDK decision, but the file should match current lifecycle metadata and the scheduler contract still needs maintainer signoff.

Full review comments:

• [P2] Add the required RFC lifecycle fields — rfcs/0007-pluggable-scheduler.md:1-7
  Current README.md says new RFCs start with status: draft and a blank issue, but this new RFC frontmatter omits both keys. Add those fields before merge so the RFC lifecycle metadata stays machine-readable and consistent with the current process.
  Confidence: 0.95

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: not found in the target repository.

Codex review notes: model gpt-5.5, reasoning high; reviewed against e938e93198f4.

Label changes

Label justifications:

• P3: This is a design-only RFC with a narrow metadata fix and no immediate runtime change.
• merge-risk: 🚨 compatibility: Accepting the RFC would define a new plugin SDK contract and scheduler ownership behavior that later implementations would need to preserve or migrate.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR discussion includes redacted terminal output from two live gateways showing openclaw-scheduler running as a separate launchd service next to the gateway.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR discussion includes redacted terminal output from two live gateways showing openclaw-scheduler running as a separate launchd service next to the gateway.

Evidence reviewed

Acceptance criteria:

• [P1] git diff --check main...HEAD.
• [P1] sed -n '1,16p' rfcs/0007-pluggable-scheduler.md.

What I checked:

• Target repository policy check: No AGENTS.md exists inside the openclaw/rfcs repository root, so there was no target-authored AGENTS policy to apply. (e938e93198f4)
• Current RFC lifecycle requirement: README.md on current main says new RFCs open with status: draft, leave issue blank until accepted, and include those metadata keys in frontmatter. (README.md:85, e366ea9825a4)
• Template requires the same fields: The current template frontmatter includes status: draft and blank issue: between last_updated and rfc_pr. (rfcs/0000-template.md:7, e366ea9825a4)
• PR frontmatter mismatch: The added RFC frontmatter has title, authors, created, last_updated, and rfc_pr, but omits status and issue. (rfcs/0007-pluggable-scheduler.md:1, 62577772878a)
• Not already implemented on main: A current-main search found no scheduler/cron RFC covering this proposed scheduler ownership seam; existing hits are unrelated plugin-SDK and Doctor/feed RFCs. (e938e93198f4)
• Real behavior proof in discussion: The PR discussion includes redacted terminal output from two live gateway deployments showing openclaw-scheduler running as a separate launchd service next to the gateway.

Likely related people:

• kevinlin-openai: Authored the current RFC lifecycle and template guidance that governs the missing metadata check. (role: recent RFC process contributor; confidence: high; commits: e366ea9825a4, f4fdf38f4717; files: README.md, rfcs/0000-template.md)
• Omar Shahine: Authored the accepted approval prompt RFC, the nearest current-main RFC touching a plugin-SDK contract surface. (role: adjacent plugin-SDK RFC contributor; confidence: medium; commits: f346050b2878; files: rfcs/0005-approval-prompt-markdown.md)
• Gio Della-Libera: Recently authored and maintained the feeds RFC, which is adjacent to plugin and skill discovery/product direction in this RFC repository. (role: recent plugin/skills ecosystem RFC contributor; confidence: medium; commits: 1cd9e911af24, 2d0e47f03c1d, 92f480be5cd9; files: rfcs/0006-feeds.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[amittell]

@clawsweeper re-review

The previous review at 2026-06-01T02:55Z failed before completion ('Review failed before ClawSweeper could summarize the requested change'). Asking for a fresh attempt.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26842961201
• Updated: 2026-06-02T19:31:44.348Z

[amittell]

@clawsweeper re-review

Addressed P1: renumbered to rfcs/0007-pluggable-scheduler.md in commit 6257777 to resolve the id collision with rfcs/0006-feeds.md on main. The in-document rfcs/0006/ asset reference is also updated to rfcs/0007/. PR title updated to match.

P2 (plugin contract / maintainer signoff) is by-design — that's the RFC purpose, not a code issue.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27110674859
• Updated: 2026-06-08T01:21:58.590Z

[amittell]

On the "claimed external scheduler deployment" P1 proof gap:

Captured live deployment evidence from both gateways the RFC references. Both hosts are launchd-supervised; openclaw-scheduler runs as a separate service under a separate Label from the OpenClaw gateway, with a multi-day uptime, talking to the gateway only through the public HTTP / WebSocket surface (no shared in-process code).

$ ssh user@gateway-host 'launchctl print "gui/$(id -u)/ai.openclaw.scheduler" | grep -E "state|pid =|program ="'
        state = running
        program = /usr/bin/caffeinate
        pid = <scheduler-pid>
                state = active
                state = active

$ ssh user@gateway-host 'ps -eo pid,etime,command | grep -E "openclaw-scheduler/(dispatcher|inbox-consumer)" | grep -v grep'
<pid> 01-00:17:34 /opt/homebrew/bin/node --no-warnings ~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js
<pid> 01-00:17:34 /usr/bin/caffeinate -i /opt/homebrew/bin/node --no-warnings ~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js

$ ssh user@second-gateway-host 'launchctl print "gui/$(id -u)/ai.openclaw.scheduler" | grep -E "state|pid =|program ="'
        state = running
        program = /usr/bin/caffeinate
        pid = <scheduler-pid>
                state = active
                state = active

Observed:

• Two distinct gateways each run a separate ai.openclaw.scheduler launchd service alongside their ai.openclaw.gateway service.
• The dispatcher process is the published openclaw-scheduler npm package (packages/openclaw-scheduler/...dispatcher.js), running as a peer service, not in-process code.
• Uptime on the captured host is 1 day 17 minutes (multi-day continuous operation).
• The scheduler integrates with the gateway only through HTTP/WebSocket — there is no shared in-process code path — which is the exact pattern the RFC proposes formalizing through the plugin-SDK seam.

This is the consumer-side artifact the RFC's "existence proof" claim refers to. The RFC's purpose is to give that already-shipping out-of-process scheduler a first-class plugin-SDK seam so its scheduled runs surface in gateway status, hooks, and transcript mirroring; today they have to bridge through the public HTTP cron surface.

On P1 #1 ("blesses new plugin kind / future migration concern"): that's the explicit RFC purpose. The proposal is intentionally additive — built-in cron stays the default; the plugin kind only engages when an external scheduler plugin registers itself.

On P1 #3 ("API-design questions intentionally open"): all four open questions in the RFC are flagged in an "Unresolved questions" section so a maintainer decision can land before any implementation follows. That's the correct shape for an RFC discussion vehicle, not a blocker on the proposal itself.

[amittell]

@clawsweeper re-review

The requested redacted live deployment proof was added in #5 (comment). Please re-review against the current PR head and the added proof.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27110506079
• Updated: 2026-06-08T01:15:31.687Z