# OpenClaw Scheduler [![CI](https://github.com/amittell/openclaw-scheduler/actions/workflows/ci.yml/badge.svg)](https://github.com/amittell/openclaw-scheduler/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Node](https://img.shields.io/badge/node-22%20%7C%2024%20%7C%2025%20%7C%2026-green)](https://nodejs.org) A durable continuity and governed-workflow sidecar for [OpenClaw](https://openclaw.ai) agents and shell workflows. Current OpenClaw already provides [SQLite cron state, command jobs, retries, and run history](https://docs.openclaw.ai/cli/cron), plus [background tasks](https://docs.openclaw.ai/automation/tasks), [Task Flow](https://docs.openclaw.ai/automation/taskflow), and [Lobster approval checkpoints](https://docs.openclaw.ai/tools/lobster). Use this scheduler when shell jobs must survive Gateway downtime, the scheduler needs a separate failure domain, workflows need direct conditional job graphs, or `@amittell/agentcli` needs its durable runtime target. This is an independent community project and is not affiliated with the OpenClaw project. It can coexist with native OpenClaw cron. Do not run the same job in both systems. **Release repo:** `github.com/amittell/openclaw-scheduler` **Development mirror:** `writhub.io/alexm/openclaw-scheduler` **Default location:** `~/.openclaw/scheduler/` **Service:** `ai.openclaw.scheduler` (macOS launchd: LaunchAgent or LaunchDaemon) **Runtime:** Node.js 22, 24, 25, or 26 (ESM), SQLite via `better-sqlite3`, cron parsing via `croner` **Schema:** version 28 **Tests:** run with `npm test` (legacy suite, isolated focused tests, docs, and agentcli integration when a checkout is present; hosted CI requires a pinned public checkout) **Platform:** macOS · Linux · Windows (WSL2) In practice, this gives you: - shell jobs that still work when the Gateway is unhealthy - a scheduler failure domain separate from the Gateway - AI jobs that stay isolated from your personal chats - conditional chains, fenced cancellation, atomic approvals, and transactional external delivery --- ## Table of Contents 1. [Why This Exists](#why-this-exists) 2. [Concrete Use Cases](#concrete-use-cases) 3. [When To Use It](#when-to-use-it) 4. [Choosing a Runtime](#choosing-a-runtime) 5. [Quick Start](#quick-start) 6. [Five-Minute Setup](#five-minute-setup) 7. [Starter Recipes](#starter-recipes) 8. [Common Migrations](#common-migrations) 9. [Platform Support](#platform-support) 10. [Architecture](#architecture) 11. [How Jobs Execute](#how-jobs-execute) 12. [Delivery Modes](#delivery-modes) 13. [Delivery Aliases](#delivery-aliases) 14. [Shell Jobs](#shell-jobs) 15. [HITL Approval Gates](#hitl-approval-gates) 16. [Idempotency](#idempotency) 17. [Context Retrieval](#context-retrieval) 18. [Task Tracker](#task-tracker) 19. [Resource Pools](#resource-pools) 20. [Workflow Chains](#workflow-chains) 21. [Retry Logic](#retry-logic) 22. [Chain Safety](#chain-safety) 23. [Inter-Agent Messaging](#inter-agent-messaging) 24. [Backup & Recovery](#backup--recovery) 25. [Agent Registry](#agent-registry) 26. [Database Schema](#database-schema) 27. [CLI Reference](#cli-reference) 28. [Configuration](#configuration) 29. [Service Management](#service-management) 30. [Error Handling & Backoff](#error-handling--backoff) 31. [Migration & History](#migration--history) 32. [Upgrading](#upgrading) 33. [Removing the Scheduler](#removing-the-scheduler) 34. [Best Practices](#best-practices) 35. [File Reference](#file-reference) 36. [Testing](#testing) 37. [Sub-agent Dispatch](#sub-agent-dispatch) 38. [Working with agentcli](#working-with-agentcli) 39. [Trust Architecture](#trust-architecture) 40. [Troubleshooting](#troubleshooting) 41. [Companion Scripts](#companion-scripts) --- ## Why This Exists OpenClaw's built-in cron and Task Flow are the right default for many automations. This project addresses a narrower operator need: continuity outside the Gateway process and one local runtime for conditional shell and agent graphs. The pain usually looks like this: - A shell script is operationally important, but it should keep running even if the gateway is unhealthy. - One step should trigger another, but only on success, only on failure, or only if the output contains a specific signal. - A risky action needs a human in the loop instead of firing immediately. - An agent needs to hand work to another agent or process, and you want that handoff tracked and auditable. `openclaw-scheduler` exists to solve those problems without replacing the native runtime for ordinary cron work. It provides jobs, runs, chains, shell execution, approvals, a delivery outbox, and message routing backed by a separate SQLite database. ## Concrete Use Cases These are the kinds of workflows this scheduler is meant for: - `metrics capture -> analysis -> approval -> report publish` You want each step tracked, retried if needed, and gated before the final action. - `shell ingest fails -> agent diagnoses failure -> operator approves remediation` The ingest should still run without the gateway, but the failure follow-up can use an agent. - `workspace audit -> diagnosis -> memory compression` The audit is a shell step, the diagnosis is an agent step, and the remediation should only run if the diagnosis actually recommends it. - `bot health check -> alert -> repair action` A shell check runs on schedule, an agent summarizes the issue, and a repair step waits for approval. The differentiator is not just "better cron". It is mixed shell + agent workflows with durable state and control over what happens after success, failure, timeout, or explicit signals in output. ## When To Use It Use it when you want: - shell jobs that do not depend on OpenClaw gateway availability - an independently operated scheduler and database - parent/child workflow chains - approval gates before risky steps - auditable inter-agent or agent-to-shell handoffs Do not use it merely to obtain run history, command jobs, or basic retries. Native OpenClaw provides those capabilities. If all you need is one scheduled command or agent turn, this is probably more system than you need. ## Choosing a Runtime > If you have never used OpenClaw's built-in cron, skip migration and go directly to [Five-Minute Setup](#five-minute-setup). | Requirement | Recommended owner | |-------------|-------------------| | One command or agent turn on a schedule | Native OpenClaw cron | | Native restart-safe flow or resumable approval checkpoint | OpenClaw Task Flow or Lobster | | Shell execution while the Gateway is unavailable | OpenClaw Scheduler | | Direct parent/child triggers on result or output content | OpenClaw Scheduler | | Declarative governed runbook manifest | `@amittell/agentcli` targeting OpenClaw Scheduler | --- ## Version 0.5.0 Runtime Safety - A singleton dispatcher lease and fencing token prevent a second dispatcher from taking ownership of live work. - Active runs carry dispatcher ownership. Only the owning fence can commit the terminal transition or trigger downstream work. - Cancellation is a durable request. Shell jobs terminate their tracked process group; agent jobs record and send the Gateway cancellation request. Check `runs get` or `status` for authoritative state. - Expired dispatch claims return to the pending queue only when no active run owns them. - Run completion, job state, and child dispatch creation commit atomically. - External delivery uses a transactional outbox that is separate from agent prompt messages. Completion ownership is scoped by run, multipart deliveries have independently retryable per-part checkpoints, and completion debt closes only after every part is actually delivered. Attachments retain size and SHA-256 metadata. - Approval decisions use atomic versioned transitions and cannot dispatch disabled, rejected, expired, or cancelled work. - Governance declarations are enforced at execution time. Unsupported sandbox, path, network, credential, trust, proof, or cost requirements fail closed. - Database schema and consolidation failures stop startup. `openclaw-scheduler doctor --json` reports schema, lease, queue, outbox, approval, and cancellation diagnostics. - AgentCLI handoff v4 binds the complete canonical execution artifact to every dispatch, approval, run, provider session, credential presentation, runtime event, and signed evidence record. Versions 1 through 3 remain supported. These controls do not make arbitrary side effects idempotent. Destructive commands must still detect prior completion and be safe to retry. --- ## Quick Start **New to the scheduler?** Start with [QUICK-START.md](QUICK-START.md) -- a focused guide covering installation, converting existing OpenClaw crons, and building your first workflow chain. For the full reference, use the npm-first path below and then jump straight to [Five-Minute Setup](#five-minute-setup). ### Option A: npm-first (publish/install flow) ```bash mkdir -p ~/.openclaw/scheduler npm install --ignore-scripts=false --prefix ~/.openclaw/scheduler openclaw-scheduler@latest npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler -- setup ``` This installs the package without cloning the repo. The launcher command maps to: - `openclaw-scheduler setup` → `setup.mjs` - `openclaw-scheduler start` → `dispatcher.js` - `openclaw-scheduler webhook-check` → `scripts/telegram-webhook-check.mjs` - `openclaw-scheduler ` → `cli.js` The explicit `--ignore-scripts=false` is required because `better-sqlite3` builds or installs its trusted native binding during the npm lifecycle. If a prior install used `ignore-scripts=true`, rerun the install command above or run `npm rebuild --ignore-scripts=false better-sqlite3` before starting. For npm installs, scheduler state defaults to `~/.openclaw/scheduler/` rather than `node_modules/openclaw-scheduler/`, so upgrades do not trample the database path. If your Node runtime changes later, rebuild the native SQLite binding before restarting the scheduler: ```bash cd ~/.openclaw/scheduler npm rebuild better-sqlite3 --ignore-scripts=false ``` This is commonly needed after a Homebrew Node upgrade on macOS or any major Node ABI change. ### macOS shell setup for ad hoc commands If you use `zsh` on macOS, put your minimal Homebrew PATH bootstrap in `~/.zshenv`, not only in `~/.zprofile` or `~/.zshrc`. Why: - `launchd` services do not depend on your interactive shell startup files - ad hoc commands like `ssh host 'node cli.js status'` run a non-interactive shell - non-interactive `zsh` reads `~/.zshenv`, but does not read `~/.zprofile` Recommended `~/.zshenv`: ```zsh # ~/.zshenv — sourced by all zsh instances, including non-interactive SSH commands if [ -x /opt/homebrew/bin/brew ]; then eval "$(/opt/homebrew/bin/brew shellenv)" fi export PATH="$HOME/.local/bin:$HOME/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" ``` If you load OpenClaw completions in `~/.zshrc`, initialize completions first so `compdef` is available: ```zsh autoload -Uz compinit compinit if [ -f "$HOME/.openclaw/completions/openclaw.zsh" ]; then source "$HOME/.openclaw/completions/openclaw.zsh" fi ``` Avoid pinning a versioned Node path like `/opt/homebrew/opt/node@22/bin` in shell startup files. Prefer the stable Homebrew symlink `/opt/homebrew/bin/node`, which survives normal `brew upgrade node`. ### Option B: source clone (dev/contributor flow) ```bash git clone https://github.com/amittell/openclaw-scheduler ~/.openclaw/scheduler cd ~/.openclaw/scheduler npm install npm test # should end with: 0 failed npm run lint # static checks npm run typecheck # exported API declarations npm run coverage # coverage summary + lcov report npm run verify:local # full local maintainer gate npm run verify:smoke # lightweight smoke gate used by GitHub Actions ``` GitHub Actions runs `npm run verify:smoke` on Linux and macOS across the supported Node.js lines. That gate includes lint, type checking, every repository test, documentation validation, and a package dry run. `npm run verify:local` adds coverage and is enforced again by `prepublishOnly`. Focused test files run sequentially with isolated databases. A dedicated required job separately checks the exact public handoff-v3 producer and the previous handoff-v2 producer. ### Option C: local npm pack (simulate the published package from source) Use this when you want to test the exact package layout end users get from npm without publishing to npmjs.org yet. ```bash git clone https://github.com/amittell/openclaw-scheduler /tmp/openclaw-scheduler cd /tmp/openclaw-scheduler npm ci npm run verify:local npm pack mkdir -p ~/.openclaw/packages/openclaw-scheduler npm install --ignore-scripts=false --prefix ~/.openclaw/packages/openclaw-scheduler --omit=dev --no-package-lock ./openclaw-scheduler-*.tgz ``` Point your service at `~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js`, and keep mutable state in `~/.openclaw/scheduler` via `SCHEDULER_HOME` and `SCHEDULER_DB`. The package also exports a small safe programmatic API surface for tooling: ```js import { db, jobs, runs, shellResults } from 'openclaw-scheduler'; ``` Then run the interactive setup wizard: ```bash npm exec openclaw-scheduler -- setup # or: node setup.mjs ``` The wizard will: - Run DB migrations - Append scheduler queue/inbox-consumer entries to your agent's `MEMORY.md` and `workspace-index.md` - Create **Inbox Consumer** + **Stuck Run Detector** scheduler jobs - Configure dispatcher auto-start service: - macOS: LaunchAgent (personal auto-login Mac) or LaunchDaemon (headless/pre-login startup) - Linux/WSL2: systemd user service (or PM2 fallback) After setup: ```bash npm exec openclaw-scheduler -- status # verify scheduler is running node scripts/stuck-run-detector.mjs # should print: No stale runs older than 15 minute(s). tail -5 /tmp/openclaw-scheduler.log # live logs ``` Dispatcher setup is covered in: - [INSTALL.md](INSTALL.md) (macOS launchd: LaunchAgent or LaunchDaemon) - [INSTALL-LINUX.md](INSTALL-LINUX.md) (Linux/WSL2 systemd + PM2 fallback) - [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md) (WSL2 setup path) For additional hosts, see [INSTALL-ADDITIONAL-HOST.md](INSTALL-ADDITIONAL-HOST.md). --- ## Five-Minute Setup This is the shortest path from "I installed it" to "I have a real job running." ### 1. Install and initialize ```bash mkdir -p ~/.openclaw/scheduler npm install --ignore-scripts=false --prefix ~/.openclaw/scheduler openclaw-scheduler@latest alias ocs='npm exec --prefix ~/.openclaw/scheduler openclaw-scheduler --' ocs setup ocs status ``` What this does: - installs the package into `~/.openclaw/scheduler` - creates or migrates `scheduler.db` - installs the scheduler service using the launchd mode you choose (`agent` or `daemon`) - creates the built-in helper jobs like `Inbox Consumer` and `Stuck Run Detector` If you plan to use the scheduler often, add the `ocs` alias to your shell profile. ### 2. Add your first real job This example runs a simple shell health check every 15 minutes. ```bash ocs jobs add '{ "name": "Disk Space Check", "schedule_cron": "*/15 * * * *", "session_target": "shell", "payload_message": "df -h /", "delivery_mode": "none", "run_timeout_ms": 120000, "origin": "system" }' ``` What it means in plain English: - `schedule_cron`: run every 15 minutes - `session_target: "shell"`: run a shell command directly, no AI needed - `payload_message`: the command to run - `delivery_mode: "none"`: do not send the output anywhere automatically - `origin: "system"`: this job was created by the system, not from a user chat ### 3. Run it now and inspect the result ```bash ocs jobs list # copy the job ID for "Disk Space Check" ocs jobs run ocs runs list 5 ``` If you want the full run record: ```bash ocs runs get ``` At that point you have a working scheduler install, a real job, and visible run history. Everything after this is layering on more power: AI jobs, delivery, retries, workflow chains, and approvals. --- ## Starter Recipes These are copy-paste examples for the most common first workflows. ### 1. Shell health check with failure alerts Use this when you want a script to run reliably even if the OpenClaw gateway is down. ```bash ocs jobs add '{ "name": "API Health Check", "schedule_cron": "*/15 * * * *", "session_target": "shell", "payload_message": "curl -fsS http://127.0.0.1:8080/health || exit 1", "delivery_mode": "announce", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 120000, "origin": "system" }' ``` Why this is useful: - it runs even if the gateway is unhealthy - it only announces on failure - every run is stored in history ### 2. Daily AI summary Use this when you want a scheduled agent report instead of a shell script. ```bash ocs jobs add '{ "name": "Daily Ops Summary", "schedule_cron": "0 9 * * *", "schedule_tz": "America/New_York", "session_target": "isolated", "payload_message": "Summarize the last 24 hours of important errors, deploys, and follow-ups in 5 bullet points.", "delivery_mode": "announce-always", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 300000, "origin": "system" }' ``` Why this is useful: - the agent runs in its own isolated session - delivery is retried durably and exhausted failures remain visible to operators - the run history stays separate from your personal chat threads ### 3. Approval-gated follow-up step Use this when a risky step should wait for a human before it runs. ```bash ocs jobs add '{ "name": "Delete Old Backups", "parent_id": "", "trigger_on": "success", "approval_required": 1, "approval_timeout_s": 3600, "approval_auto": "reject", "session_target": "shell", "payload_message": "find /backups -type f -mtime +14 -delete", "delivery_mode": "announce-always", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 120000 }' ``` Why this is useful: - the parent job can run automatically - the risky cleanup step pauses until someone approves it - the scheduler records who approved or rejected it Approve or reject later with: ```bash ocs approvals list --json ocs approvals approve --reason "Change window open" ocs approvals reject --reason "Not today" ``` --- ## Common Migrations If you already have cron jobs, OpenClaw cron entries, or shell scripts, this is the simplest way to think about the conversion. ### 1. OpenClaw built-in cron -> inspect, import, test, then disable duplicates The default importer reads the supported OpenClaw CLI rather than an internal storage file. It calls `openclaw cron list --json` and `openclaw cron get --json`: ```bash openclaw-scheduler migrate --dry-run --json > migration-report.json openclaw-scheduler migrate --json openclaw-scheduler jobs list --json ``` The dry run never opens, creates, or migrates the target scheduler database. Existing-ID duplicate checks therefore occur during the real import. Cron expressions and one-shot timestamps are preserved exactly. Intervals that five-field cron cannot represent exactly are rejected unless the operator explicitly passes `--allow-inexact-every`. A pre-SQLite export is opt-in: ```bash openclaw-scheduler migrate --legacy-json ~/.openclaw/cron/jobs.json --dry-run --json ``` After representative imported jobs complete successfully, disable only the corresponding native jobs: ```bash openclaw cron edit --disable ``` Rollback by stopping the scheduler, disabling its imported copies, and re-enabling the native jobs. Retain the scheduler database until rollback verification is complete. ### 2. Plain shell cron line -> `session_target: "shell"` If you have a normal cron line like: ```cron */5 * * * * /usr/local/bin/check-api.sh ``` Convert it to: ```bash ocs jobs add '{ "name": "API Check", "schedule_cron": "*/5 * * * *", "session_target": "shell", "payload_message": "/usr/local/bin/check-api.sh", "delivery_mode": "announce", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 120000, "origin": "system" }' ``` Choose `shell` when the task is deterministic and you do not need AI reasoning. ### 3. AI-ish cron job -> `session_target: "isolated"` If the old job was really “run a prompt every morning”, use an isolated agent job instead of a shell script: ```bash ocs jobs add '{ "name": "Daily Status Summary", "schedule_cron": "0 8 * * *", "schedule_tz": "America/New_York", "session_target": "isolated", "payload_message": "Summarize the most important errors, deploys, and follow-ups from the last 24 hours in 5 bullet points.", "delivery_mode": "announce-always", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 300000, "origin": "system" }' ``` Choose `isolated` when the job needs reasoning, writing, summarization, or tools. ### 4. Two cron jobs with manual ordering -> parent/child chain If your current workflow is: - run a backup - wait - run verification Model that as a chain instead of two unrelated cron entries: ```bash ocs jobs add '{ "name": "Nightly Backup", "schedule_cron": "0 2 * * *", "session_target": "shell", "payload_message": "/usr/local/bin/nightly-backup.sh", "delivery_mode": "announce", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 600000, "origin": "system" }' ``` Then create the follow-up: ```bash ocs jobs add '{ "name": "Verify Nightly Backup", "parent_id": "", "trigger_on": "success", "trigger_delay_s": 60, "session_target": "shell", "payload_message": "/usr/local/bin/verify-backup.sh", "delivery_mode": "announce", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 120000 }' ``` This is one of the biggest upgrades over plain cron: the second step now runs because the first step succeeded, not because the clock happened to reach another minute. ### 5. Risky follow-up -> add `approval_required` If the current process is “job runs, then a human decides whether to continue,” model that decision directly: ```bash ocs jobs add '{ "name": "Delete Temp Files", "parent_id": "", "trigger_on": "success", "approval_required": 1, "approval_timeout_s": 3600, "approval_auto": "reject", "session_target": "shell", "payload_message": "find /tmp/myapp -type f -mtime +7 -delete", "delivery_mode": "announce-always", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 120000 }' ``` That keeps the job automated, but only up to the point where human judgment is actually needed. ### Rule of thumb When converting existing work: - start with `shell` unless you clearly need AI reasoning - add delivery only if someone really needs to see the output - use chains when one step depends on another - use approvals when the next step would be annoying, expensive, or risky if it ran by mistake --- ## Platform Support | Platform | Service Manager | Shell Jobs | Status | |----------|----------------|------------|--------| | macOS | launchd (`agent` or `daemon`) | `/bin/zsh` | Tested | | Linux | systemd user service or PM2 fallback | `/bin/bash` | Supported | | Windows (WSL2) | systemd user service or PM2 fallback inside WSL2 | `/bin/bash` | Supported | | Windows (native or WSL1) | Not applicable | Not applicable | Not supported; use WSL2 | - **macOS:** Full guide in [INSTALL.md](INSTALL.md) - **Linux:** Full guide in [INSTALL-LINUX.md](INSTALL-LINUX.md) - **Windows:** Install WSL2, then follow [INSTALL-LINUX.md](INSTALL-LINUX.md). See [INSTALL-WINDOWS.md](INSTALL-WINDOWS.md) for WSL2 setup. Override the shell for shell jobs with the `SCHEDULER_SHELL=/path/to/shell` environment variable. --- ## Architecture The scheduler sits alongside the OpenClaw gateway as an independent process. Isolated targets use stable per-job sessions that remain separate from the user's main conversation. Main targets use the existing main session, and shell targets do not create an agent session. ``` ┌─────────────────────────────────────────────┐ │ Host Machine (e.g., scheduler-host.local) │ │ │ │ OpenClaw Gateway (:18789) │ │ ├─ Telegram / Discord / etc. │ │ ├─ Chat completions endpoint (/v1/...) │ │ ├─ Tool execution (exec, browser, k8s...) │ │ └─ Memory search │ │ │ │ Scheduler (launchd service) │ │ ├─ SQLite DB (scheduler.db) │ │ ├─ Job dispatch via chat completions │ │ ├─ Workflow chain engine │ │ ├─ Retry logic │ │ ├─ Shell job execution │ │ ├─ HITL approval gates │ │ ├─ Idempotency ledger │ │ ├─ Inter-agent message queue │ │ ├─ Task tracker │ │ └─ MinIO backup │ └─────────────────────────────────────────────┘ ``` ### Tick Loop ``` ┌──────────────────────────────────────────────────────────────┐ │ Dispatcher Loop (10s tick) │ │ │ │ 1. Gateway health check │ │ 2. Find due jobs → dispatch │ │ 3. Check running runs (stale/timeout detection) │ │ 4. HITL approval gate check │ │ 5. Message delivery + spawn handling │ │ 6. Task tracker dead-man's-switch │ │ 7. Expire old messages │ │ 8. Prune old runs + WAL checkpoint (hourly) │ │ 9. Backup to MinIO (every 5 min) │ └──────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌───────────────────┐ ┌──────────────────────┐ │ SQLite DB │ │ OpenClaw Gateway │ │ │ │ │ │ • jobs │ │ • /v1/chat/completions│ │ • runs │ │ • /tools/invoke │ │ • messages │ │ • /health │ │ • agents │ │ • system event CLI │ │ • approvals │ └──────────────────────┘ │ • task_tracker │ │ • idempotency_ledger│ │ • delivery_aliases│ │ • schema_migrations│ └───────────────────┘ ``` ### Session Types | Session | Created By | Lifetime | Used For | |---------|-----------|----------|----------| | User DM | Telegram message | Persistent per-peer | Your conversations | | Group chat | Group message | Persistent per-group | Team discussions | | Isolated job | Dispatcher via API | Persistent per job, reused across runs | Cron jobs, chain steps | | Main session | Dispatcher API, or `openclaw system event` for fire-and-forget | Existing main session | Jobs needing main context | | Shell | Dispatcher (direct) | Per-job (no session) | Cron scripts, backups, maintenance | | Sub-agent | `sessions_spawn` | Task-scoped | Delegated work | Isolated scheduler jobs cannot see user-chat history, but later runs of the same job reuse its warm per-job session and may retain that job's earlier context. Main-session jobs intentionally use the existing main conversation. --- ## How Jobs Execute ### Isolated Jobs (default) ``` Scheduler tick (every 10s) │ ├─ getDueJobs() → "Hourly Workspace Backup is due" ├─ hasRunningRun()? → skip if overlap_policy='skip' ├─ createRun() → status='running' ├─ setAgentStatus('main', 'busy') │ ├─ POST /v1/chat/completions │ session: agent::scheduler: (stable per job, isolated from main) │ model: openclaw:main │ message: [job prompt + any pending inbox messages] │ │ ← "Committed 3 files, pushed to origin" │ ├─ finishRun('ok', summary) ├─ setAgentStatus('main', 'idle') ├─ Deliver to Telegram? → delivery_mode + channel + target ├─ Queue result message for traceability ├─ Advance next_run_at to next cron fire └─ Trigger child jobs if any (workflow chain) ``` ### Main Session Jobs For jobs that need the main session context (rare), use `payload_kind: "systemEvent"`. Default, `execute`, or `plan` execution waits for the agent response and captures it for normal completion handling: ``` Dispatcher → POST /v1/chat/completions → wait for main-session response ``` Set `execution_intent: "fire-and-forget"` only when the scheduler should inject the event and return immediately without capturing the eventual response: ``` Dispatcher → exec: openclaw system event --text "..." --mode now ``` Handoff v4 main-session jobs use only the synchronous path because it carries the artifact, runtime-instance, and fresh capability-nonce binding through the Gateway request. The `openclaw system event` transport cannot carry that binding, so v4 fire-and-forget jobs fail validation. Earlier handoff versions keep the existing fire-and-forget behavior. ### Shell Jobs ``` Shell Job (session_target='shell') │ ├─ getDueJobs() → "Hourly Backup is due" ├─ createRun() → status='running' ├─ run "" via shell (platform default or SCHEDULER_SHELL) │ (no gateway required) │ ← exit 0: "Backup complete, 3 files" │ ├─ finishRun(exit===0 ? 'ok' : 'error') ├─ announce: post output if exit ≠ 0 ├─ announce-always: post output regardless └─ Trigger child jobs if any ``` ### Prompt Building Each isolated job prompt includes: 1. Header: `[scheduler: ]` 2. Pending inbox messages for the agent (up to 5) 3. Context from prior runs (if `context_retrieval` is set) 4. The job's `payload_message` --- ## Delivery Modes The scheduler delivers job output through the OpenClaw gateway's messaging system. All channels supported by the gateway work with the scheduler: **Telegram**, **Discord**, **WhatsApp**, **Signal**, **iMessage**, and **Slack**. Set `delivery_channel` to the channel name and `delivery_to` to the channel-specific target (chat ID, channel ID, phone number, handle, etc.). | Mode | When output is delivered | |------|-------------------------| | `none` | Never (background jobs) | | `announce` | Agent jobs: delivers when run status is not `ok`. Shell jobs: non-zero exit only. Silently skipped for `main` session jobs (use `announce-always` instead) | | `announce-always` | Always delivers output (LLM or shell), including `main` session jobs | > **Note:** non-exempt jobs using `announce` or `announce-always` are rejected at validation time when `delivery_to` is absent. Runtime delivery is written to a transactional outbox, separate from agent prompt messages. Outbox claims expire and recover safely. Multipart output is stored as independently retryable rows with deterministic `:part:i/N` idempotency keys. Durable enqueue is not a delivery receipt; run-scoped completion debt closes only after every part is delivered. Attachment rows retain size and SHA-256 metadata. > > Examples in this document use Telegram for delivery_channel since it is the > most common configuration. Replace with your channel of choice. --- ## Delivery Aliases Delivery aliases let you define named delivery targets (e.g., `@my_team`) instead of hard-coding channel/target pairs in every job. ```bash # Create a named alias openclaw-scheduler alias add my_team telegram -100200000000 # Use @alias in job (resolves at dispatch time) openclaw-scheduler jobs add '{ "name": "Alert", "delivery_mode": "announce", "delivery_to": "@my_team", ... }' # List aliases openclaw-scheduler alias list # Remove an alias openclaw-scheduler alias remove my_team ``` Aliases are resolved at dispatch time. If an alias is deleted, jobs fall back to suppressed delivery. --- ## Shell Jobs Shell jobs run a command directly on the host — no gateway or LLM required. Ideal for backups, scripts, maintenance tasks, and anything that doesn't need AI. ```bash openclaw-scheduler jobs add '{ "name": "Hourly Backup", "schedule_cron": "0 * * * *", "schedule_tz": "America/New_York", "session_target": "shell", "payload_message": "/path/to/backup.sh", "delivery_mode": "announce", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 600000, "origin": "system" }' ``` **Key properties:** - **No gateway dependency** — runs even when gateway is down - `payload_message` is the command to execute (shell string passed to the configured shell) - Output captured up to 1MB, with preview/offload budgets to keep large output out of the main run row - Shell runs persist structured failure context on `runs`: `shell_exit_code`, `shell_signal`, `shell_timed_out`, `shell_stdout`, `shell_stderr`, plus optional `shell_stdout_path` / `shell_stderr_path` when large output is offloaded - Failure-triggered agent children receive shell context with separate exit code, stdout, and stderr blocks - `run_timeout_ms` controls max execution time (required, no default) - Workflow chains work the same way — shell jobs can trigger children on success/failure - Shell jobs now honor `max_retries` before failure children fire, the same as isolated agent jobs - `openclaw-scheduler runs output stdout|stderr` retrieves stored or offloaded shell output on demand **With environment variables:** ```bash openclaw-scheduler jobs add '{ "name": "DB Dump", "schedule_cron": "0 3 * * *", "session_target": "shell", "payload_message": "PGPASSWORD=secret pg_dump mydb > /backups/mydb.sql && echo OK", "delivery_mode": "announce-always", "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 600000, "origin": "system" }' ``` --- ## HITL Approval Gates Jobs with `approval_required: 1` pause every dispatch before execution. The gate applies uniformly to root, manual, scheduled, one-shot, retry, and chain-triggered work. Every gated attempt is represented by a durable dispatch row and an `awaiting_approval` run. ```bash # Scheduled root job that requires a scoped operator approval openclaw-scheduler jobs add '{ "name": "Deploy to Prod", "schedule_cron": "0 10 * * 1-5", "approval_required": 1, "approval_risk_level": "high", "approval_approver_scope": "user:alex", "approval_timeout_s": 3600, "approval_auto": "reject", "session_target": "shell", "payload_kind": "shellCommand", "payload_message": "Deploy the application to production", "delivery_mode": "none", "origin": "system", "run_timeout_ms": 300000 }' ``` When triggered, the job creator receives the pending approval identifier, risk, scope, and CLI commands. ```bash openclaw-scheduler approvals list --json openclaw-scheduler approvals approve APPROVAL_ID --reason "Change window open" openclaw-scheduler approvals reject APPROVAL_ID --reason "Postponing until the next change window" ``` **Key notes:** - `approval_risk_level` is optional and accepts `low`, `medium`, or `high`. - `approval_approver_scope` accepts an unprefixed exact identity or `exact:`, `user:`, `uid:`, or `principal:` matching for the local OS account. Domain scopes are not supported. - AgentCLI handoff v4 exposes approval-scope enforcement as one coarse capability while its manifests may contain domain scopes. The scheduler therefore advertises `approval_scope_enforcement: false` so scoped agentcli manifests fail capability negotiation instead of being partially enforced. Direct scheduler jobs may still use the supported local scopes above. - The scheduler derives the approver from the invoking operating-system user and UID. CLI flags and environment variables cannot select another identity. - Prefer `approvals approve/reject APPROVAL_ID`; `jobs approve/reject JOB_ID` remains a legacy convenience for that job's current pending approval and cannot override approver identity. - Use `approvals list --json` to copy the complete approval UUID before making a decision. - `approval_auto: "approve"` is invalid with an approver scope. Scoped timeout resolution fails closed. - The approval snapshots risk, scope, and a canonical SHA-256 binding of the execution contract. Changing, disabling, or deleting the job cancels the pending approval instead of applying it to different work. - `approval_timeout_s` controls the auto-resolution deadline and `approval_auto` selects `"approve"` or `"reject"` for unscoped jobs. ### Declared output formats Set `output_format` to `json`, `ndjson`, or `text` when downstream work requires a validated result shape. Successful JSON output must parse as one JSON value; each nonblank NDJSON line must parse independently; text is stored on the normalized text path. The scheduler persists validity, byte count, SHA-256 digest, and either the parsed value or an artifact reference on the run. Malformed JSON or NDJSON remains a successful execution with `structured_output_valid: 0`, a `structured_output_warning`, and a null parsed value; success children may still run because transport success is distinct from output-shape validation. ### Post-success verification Any synchronous job can declare a separate local shell verification command that runs after its primary execution and structured-output parsing, but before terminal evidence, delivery, and child dispatch: ```json { "verify_shell": "test -f /srv/app/healthy", "verify_timeout_s": 30, "verify_on_failure": "error" } ``` `verify_on_failure` accepts `error` or `warn`. An error policy converts a failed verification to a terminal error and blocks success children; a warning policy preserves primary success and records the warning. Verification stores only status, timing, exit metadata, byte counts, and SHA-256 digests, never raw verification output. Fire-and-forget jobs cannot declare verification. --- ## Idempotency Control what happens when the dispatcher crashes mid-run. Despite the legacy field name `delivery_guarantee`, this setting governs execution replay, not external message-delivery confirmation. ```bash # Enable at-least-once: crashed runs replay on next startup openclaw-scheduler jobs update '{"delivery_guarantee":"at-least-once"}' # Default (at-most-once): no replay openclaw-scheduler jobs update '{"delivery_guarantee":"at-most-once"}' ``` **How it works:** - **`at-most-once`** (default): if dispatcher crashes mid-run, run is marked `crashed` and the schedule advances normally. The run is not replayed. - **`at-least-once`**: on startup, any `running` run from a crashed dispatcher is replayed with a new run. `replay_of` field tracks the original run ID for lineage. **Idempotent agents** can return `IDEMPOTENT_SKIP` in their response to acknowledge they've already processed this execution (detected via the idempotency ledger). The ledger also prevents double-dispatch in concurrent tick scenarios — each run acquires a lock before dispatch. --- ## Context Retrieval Inject prior run summaries into a job's prompt so the agent has awareness of recent outcomes. ```bash # Inject last 3 run summaries into job prompt openclaw-scheduler jobs update '{"context_retrieval":"recent","context_retrieval_limit":3}' # Hybrid: recent runs + TF-IDF search for semantically relevant summaries openclaw-scheduler jobs update '{"context_retrieval":"hybrid","context_retrieval_limit":5}' ``` **Modes:** | Mode | Description | |------|-------------| | `none` | No context injected (default) | | `recent` | Last N run summaries, newest first | | `hybrid` | Recent runs + TF-IDF similarity search against all prior summaries | Useful for health check jobs that should know about yesterday's failures, or audit jobs that build incrementally on prior work. --- ## Task Tracker The task tracker provides a dead-man's-switch for coordinating multi-agent sub-agent teams. Create a tracker, assign expected agents, and receive a summary when all agents complete (or time out). ```bash # Create a task group to monitor N sub-agents openclaw-scheduler tasks create '{ "name": "v2-release-team", "expected_agents": ["schema-agent","frontend-agent","docs-agent"], "timeout_s": 1800, "delivery_channel": "telegram", "delivery_to": "YOUR_CHAT_ID" }' # Monitor openclaw-scheduler tasks list openclaw-scheduler tasks status ``` Each agent in the team must send heartbeat updates. If an agent goes silent past its timeout, it's declared dead. When all agents complete or time out, a summary is delivered to the configured channel. --- ## Resource Pools Prevent concurrent execution across different jobs that share a resource. ```bash # Two jobs that must not run concurrently openclaw-scheduler jobs add '{"name":"DB Migration","resource_pool":"database",...}' openclaw-scheduler jobs add '{"name":"DB Backup","resource_pool":"database",...}' ``` If one job in a pool is currently running, all other pool members skip their tick (same behavior as `overlap_policy: 'skip'`, but cross-job rather than per-job). Pool membership is set via the `resource_pool` string field. --- ## Workflow Chains Jobs can be linked into parent → child chains. When a parent completes, its children fire automatically. ### Pattern 1: Chained Jobs ```bash # Parent: runs on cron openclaw-scheduler jobs add '{ "name": "Build App", "schedule_cron": "0 10 * * *", "payload_message": "Build the application", "run_timeout_ms": 300000, "origin": "system" }' # → id: "abc123..." # Child: fires when parent succeeds openclaw-scheduler jobs add '{ "name": "Deploy App", "payload_message": "Deploy to production", "parent_id": "abc123...", "trigger_on": "success", "run_timeout_ms": 300000 }' # Child: fires when parent fails openclaw-scheduler jobs add '{ "name": "Build Alert", "payload_message": "Build failed -- check logs", "parent_id": "abc123...", "trigger_on": "failure", "delivery_mode": "announce", "delivery_to": "YOUR_CHAT_ID", "run_timeout_ms": 300000 }' ``` **Trigger types:** - `success` — parent run status = `ok` - `failure` — parent run status = `error` or `timeout` - `complete` — any completion (success, failure, or timeout) - Child jobs are chain-triggered only. Use `trigger_delay_s` to delay a child run; one-shot `schedule_kind: "at"` is for root jobs only. ### Pattern 2: Output-Based Trigger Conditions ```bash # Only fire child if parent output contains "ALERT" openclaw-scheduler jobs add '{ "name": "Alert Handler", "parent_id": "", "trigger_on": "success", "trigger_condition": "contains:ALERT", "payload_message": "Handle the alert", "run_timeout_ms": 300000 }' # Regex condition openclaw-scheduler jobs add '{ "name": "Critical Error Handler", "parent_id": "", "trigger_on": "success", "trigger_condition": "regex:ERROR.*critical", "payload_message": "Handle critical error", "run_timeout_ms": 300000 }' ``` `regex:` conditions use RE2 syntax and linear-time matching. Backreferences, lookahead, and lookbehind are rejected. The full condition is limited to 1,024 characters, and regex evaluation fails closed when the parent output exceeds 65,536 UTF-8 bytes. Use `contains:` when a literal substring is sufficient. ### Pattern 3: Multi-Agent Workflows Chain jobs targeting different agents: ``` Build (agent: main, cron: 10am) └─ Deploy (agent: ops, trigger: success) └─ Health Check (agent: main, trigger: success, delay: 60s) ``` ```bash openclaw-scheduler jobs add '{ "name": "Deploy", "payload_message": "deploy", "agent_id": "ops", "parent_id": "", "trigger_on": "success", "run_timeout_ms": 300000 }' ``` ### Pattern 4: Delayed Triggers ```bash openclaw-scheduler jobs add '{ "name": "Post-Deploy Check", "payload_message": "Verify services healthy", "parent_id": "", "trigger_on": "success", "trigger_delay_s": 60, "run_timeout_ms": 300000 }' ``` ### Pattern 5: Runtime Spawning A running agent can create new jobs on the fly by sending a `spawn` message: ```json { "from_agent": "main", "to_agent": "scheduler", "kind": "spawn", "body": "{\"name\":\"Dynamic Task\",\"payload_message\":\"analyze results\",\"delete_after_run\":true,\"run_now\":true}" } ``` ### Visualizing Chains ```bash openclaw-scheduler jobs tree # Output (all root jobs and their chains): # Build App # └─ Deploy App [→success] (agent:ops) # └─ Build Alert [→failure] # └─ Health Check [→complete +60s] ``` --- ## Retry Logic Jobs can auto-retry before declaring failure and triggering failure children. ```bash openclaw-scheduler jobs add '{ "name": "Flaky Deploy", "schedule_cron": "0 10 * * *", "payload_message": "deploy to prod", "max_retries": 3, "run_timeout_ms": 300000, "origin": "system" }' ``` **How it works:** 1. Job fails → check `max_retries` 2. Retries remaining → schedule retry with exponential backoff (30s, 60s, 120s, ...) 3. Retry run tracks lineage: `retry_of` → failed run ID, `retry_count` incremented 4. All retries exhausted → trigger failure children + apply error backoff 5. Any retry succeeds → trigger success children, reset `consecutive_errors` **Key:** failure children don't fire until all retries are exhausted. This prevents false alerts on transient failures. This retry ladder now applies uniformly to shell jobs, isolated agent jobs, and main-session jobs that surface dispatch failures. | Field | Default | Description | |-------|---------|-------------| | `max_retries` | 0 | Max retry attempts (0 = no retry) | | `runs.retry_of` | null | ID of the failed run being retried | | `runs.retry_count` | 0 | Which attempt this is (0 = first try) | --- ## Chain Safety ### Max Chain Depth `MAX_CHAIN_DEPTH = 10` — enforced on: - `createJob` — can't add a child deeper than 10 levels - `updateJob` — can't move a job to create a chain deeper than 10 - `triggerChildren` — runtime safeguard stops dispatch at depth 10 ### Cycle Detection `detectCycle()` walks up the parent chain on both create and update. Catches: - Self-referential: A → A - Deep cycles: A → B → C → A - Throws with descriptive error message ### Chain Cancellation ```bash openclaw-scheduler jobs cancel # Requests cancellation for active runs on this job and its descendants ``` Cancellation is fenced against dispatcher ownership. Pending work is cancelled atomically. A running shell job receives process-group termination and cannot finalize or trigger children after cancellation wins. Agent work records and sends a Gateway cancellation request. Finished runs are unchanged. Poll `runs get`, `runs running`, or `status`; chat notifications are asynchronous and can be stale. --- ## Inter-Agent Messaging Agents exchange messages through the scheduler's queue. ### Features - **Priority:** 0 (normal), 1 (high), 2 (urgent) — inbox sorted by priority then time - **Threading:** `reply_to` links messages into conversations - **Read receipts:** pending → delivered → read (with timestamps) - **Broadcast:** `to_agent = 'broadcast'` reaches all agents - **TTL/Expiry:** `expires_at` auto-expires unread messages - **Metadata:** JSON blob for structured data - **Kinds:** `text`, `task`, `result`, `status`, `system`, `spawn`, `decision`, `constraint`, `fact`, `preference` - **Owner field:** `owner` tracks message originator for audit - **Job linking:** messages can reference `job_id` and `run_id` ### Delivery Messages are delivered inline with job prompts. When the dispatcher builds a prompt, it includes up to 5 pending messages for the target agent, marked as `delivered`. ### Usage ```bash # Send a message openclaw-scheduler msg send "message body" # Read inbox openclaw-scheduler msg inbox # Mark all read openclaw-scheduler msg readall ``` ### Signal Queue Consumer Example Use this when you want scripts to enqueue only actionable signals, then a single consumer job pushes those signals to Telegram. ```bash # 1) Enqueue a signal openclaw-scheduler msg send monitor-agent main "Found 3 critical errors in prod logs" # 2) Run the inbox consumer daemon (event-driven, watches SQLite WAL) # Delivers within ~250ms of a message landing in the DB. # No polling cron needed — the daemon watches for WAL changes. node scripts/inbox-consumer.mjs --watch --to YOUR_CHAT_ID --channel telegram # Or as a one-shot drain (useful for testing): node scripts/inbox-consumer.mjs --to YOUR_CHAT_ID --channel telegram ``` --- ## Backup & Recovery MinIO backups are disabled by default. Set `SCHEDULER_BACKUP=1` to enable. Requires `mc` (MinIO client) installed and configured with a `backupstore` alias. The scheduler can back up its SQLite database to MinIO automatically. ```bash # Manual snapshot node backup.js snapshot # Manual rollup (hourly aggregate) node backup.js rollup # Check backup status node backup.js status # Restore from snapshot node backup.js restore # Prune old backups node backup.js prune ``` **Configuration via environment:** | Variable | Default | Description | |----------|---------|-------------| | `SCHEDULER_BACKUP_MC_ALIAS` | `backupstore` | MinIO client alias | | `SCHEDULER_BACKUP_BUCKET` | `scheduler-backups` | MinIO bucket name | | `SCHEDULER_BACKUP_PREFIX` | `scheduler` | Path prefix within bucket | Requires `mc` (MinIO client) in PATH and a configured `backupstore` alias. **Built-in (when running as a background service):** - Snapshot every 5 minutes (`SCHEDULER_BACKUP_MS`) - Rollup on the first tick of each hour --- ## Agent Registry | Operation | Function | Description | |-----------|----------|-------------| | Register | `upsertAgent(id, opts)` | Create or update | | Get | `getAgent(id)` | Fetch by ID | | List | `listAgents()` | All agents | | Set status | `setAgentStatus(id, status, sessionKey)` | idle/busy/offline | | Touch | `touchAgent(id)` | Update last_seen_at | The dispatcher automatically manages agent status during dispatch (idle → busy → idle). ```bash openclaw-scheduler agents list openclaw-scheduler agents get openclaw-scheduler agents register [name] ``` --- ## Database Schema **Schema version:** 28 | **Mode:** WAL | **Foreign keys:** ON ### Tables | Table | Description | |-------|-------------| | `jobs` | Job definitions (schedule, payload, chain config, delivery) | | `runs` | Execution history (status, timing, summaries, retry lineage) | | `messages` | Inter-agent prompt queue (`pending`, `prompt_claimed`, delivered/read terminal states) | | `agents` | Agent registry (status, capabilities, last seen) | | `approvals` | Atomic, versioned HITL decisions and dispatch state | | `task_tracker` | Multi-agent task group definitions | | `task_tracker_agents` | Per-agent status within a task group | | `idempotency_ledger` | Dispatch deduplication and at-least-once tracking | | `delivery_aliases` | Named delivery targets (channel + target pairs) | | `job_dispatch_queue` | Leased durable dispatch claims and replay state | | `dispatcher_leases` | Singleton dispatcher ownership and fencing tokens | | `delivery_outbox` | Transactional external delivery queue with multipart group/part coordinates | | `delivery_attachments` | Durable attachment content/path and integrity metadata | | `completion_debts` | Run-scoped completion delivery ownership and recovery state | | `evidence_records` | Immutable, content-addressed SHA-256 evidence, one row per run | | `message_receipts` | Delivery receipt tracking for messages | | `team_tasks` | Team-scoped task definitions and status | | `team_mailbox_events` | Projected events from team mailbox activity | | `schema_migrations` | Baseline schema version log | ### Jobs (key columns) ``` id, name, enabled, schedule_kind, schedule_cron, schedule_at, schedule_tz, session_target, agent_id, payload_kind, payload_message, payload_model, payload_model_fallback, payload_thinking, execution_intent, execution_read_only, overlap_policy, run_timeout_ms, max_queued_dispatches, max_pending_approvals, max_trigger_fanout, output_store_limit_bytes, output_excerpt_limit_bytes, output_summary_limit_bytes, output_offload_threshold_bytes, max_retries, delivery_mode, delivery_channel, delivery_to, delivery_guarantee, delete_after_run, ttl_hours, parent_id, trigger_on, trigger_delay_s, trigger_condition, resource_pool, auth_profile, auth_profile_fallback, origin, source_channel, source_target, source_message_id, source_thread_id, approval_required, approval_timeout_s, approval_auto, approval_risk_level, approval_approver_scope, output_format, verify_shell, verify_timeout_s, verify_on_failure, context_retrieval, context_retrieval_limit, preferred_session_key, job_type, watchdog_target_label, watchdog_check_cmd, watchdog_timeout_min, watchdog_alert_channel, watchdog_alert_target, watchdog_self_destruct, watchdog_started_at, next_run_at, last_run_at, last_status, consecutive_errors, created_at, updated_at ``` ### Runs (key columns) ``` id, job_id, status, started_at, finished_at, duration_ms, last_heartbeat, session_key, session_id, summary, error_message, shell_exit_code, shell_signal, shell_timed_out, shell_stdout, shell_stderr, shell_stdout_path, shell_stderr_path, shell_stdout_bytes, shell_stderr_bytes, dispatched_at, run_timeout_ms, triggered_by_run, retry_of, retry_count, replay_of, delegation_validation, output_format, structured_output, structured_output_valid, structured_output_warning, structured_output_bytes, structured_output_sha256, structured_output_path, verification_result, approval_used ``` **Run statuses:** `pending`, `running`, `ok`, `error`, `timeout`, `skipped`, `cancelled`, `crashed`, `recovery_blocked`, `awaiting_approval`, `approved` ### Messages (key columns) ``` id, from_agent, to_agent, reply_to, kind, subject, body, metadata, priority, channel, owner, status, delivered_at, read_at, expires_at, created_at, job_id, run_id ``` ### Agents (10 columns) ``` id, name, status, last_seen_at, session_key, capabilities, delivery_channel, delivery_to, brand_name, created_at ``` --- ## CLI Reference ```bash # ── Jobs ────────────────────────────────────────── openclaw-scheduler jobs list # List all (supports --type ) openclaw-scheduler jobs list --include-handoff-artifacts --json # Validate and hydrate persisted v4 artifacts openclaw-scheduler jobs get # Full details as JSON openclaw-scheduler jobs add --file job.json # Inline JSON and --stdin are also supported openclaw-scheduler jobs update --stdin # Partial update from standard input openclaw-scheduler jobs validate --file job.json # Validate without DB initialization openclaw-scheduler jobs enable openclaw-scheduler jobs disable # NOTE: one-shot at-jobs with delete_after_run: true are auto-pruned after 24h (ordinary disabled cron jobs are kept indefinitely) openclaw-scheduler jobs delete # Cascades to runs openclaw-scheduler jobs tree # Visual chain hierarchy openclaw-scheduler jobs cancel # Cancel running chain # ── Runs ────────────────────────────────────────── openclaw-scheduler runs list [limit] # Run history openclaw-scheduler runs get # Full run details openclaw-scheduler runs output stdout # Stored/offloaded stdout or stderr openclaw-scheduler runs evidence # Verify and return immutable execution evidence openclaw-scheduler runs running # Active runs openclaw-scheduler runs stale [threshold-s] # Stale runs (default 90s) # ── Messages ────────────────────────────────────── openclaw-scheduler msg send openclaw-scheduler msg inbox [limit] openclaw-scheduler msg outbox [limit] openclaw-scheduler msg thread openclaw-scheduler msg ack [actor] [note] openclaw-scheduler msg receipts [limit] openclaw-scheduler msg team-inbox [limit] [member-id] [task-id] openclaw-scheduler msg read openclaw-scheduler msg readall openclaw-scheduler msg unread # ── Agents ──────────────────────────────────────── openclaw-scheduler agents list openclaw-scheduler agents get openclaw-scheduler agents register [name] # ── Approvals ───────────────────────────────────── openclaw-scheduler approvals list --json # Full pending approval IDs openclaw-scheduler approvals approve [--reason ...] # Approve by approval ID openclaw-scheduler approvals reject [--reason ...] # Reject by approval ID openclaw-scheduler jobs approve # Legacy current-gate lookup openclaw-scheduler jobs reject [reason] # Legacy current-gate lookup # ── Task Tracker ────────────────────────────────── openclaw-scheduler tasks create '' # Create task group openclaw-scheduler tasks list # Active task groups openclaw-scheduler tasks status # Detailed status openclaw-scheduler tasks history [limit] # Recently completed groups openclaw-scheduler tasks heartbeat