Skills

# Managed System Jobs

Use this skill when a user asks an agent to create a system cron job that should run on its own and appear in LordClaw's Cron Jobs > System tab.

Prefer OpenClaw cron for ordinary agent-scheduled work. Use a managed system job when the task should run through the host scheduler instead of asking an agent or model to run each time.

## Registry

LordClaw reads managed system jobs from:

```text
~/.openclaw/state/managed-system-jobs.json
```

Create the parent directory when it is missing. Do not ask the user to edit this file by hand.

Minimum schema:

```json
{
  "version": 1,
  "jobs": [
    {
      "source": "launchd",
      "label": "co.example.project.worker",
      "name": "Example project worker"
    }
  ]
}
```

Supported entries:

- `source: "launchd"` with `label`: macOS LaunchAgent or LaunchDaemon.
- `source: "crontab"` with `commandIncludes`: user crontab entry with a stable marker, usually a wrapper script path.
- `name`: short LordClaw display name.

Preserve unknown fields when updating the registry.

## Write Rules

1. Read the existing registry if it exists.
2. Keep valid existing jobs.
3. Upsert by stable identity:
   - launchd: `source + label`
   - crontab: `source + commandIncludes`
4. Write JSON with 2-space indentation.
5. Write atomically: write a temporary file in the same directory, then rename it over `managed-system-jobs.json`.
6. Never delete unrelated registry entries unless the user explicitly asks to remove that managed job.

## macOS launchd

Use a LaunchAgent for user-level jobs. Use a LaunchDaemon only when root-level service behavior is actually needed.

LaunchAgent path:

```text
~/Library/LaunchAgents/<label>.plist
```

Recommended plist fields:

- `Label`
- `ProgramArguments`
- `WorkingDirectory` when the command depends on a project directory
- `StandardOutPath`
- `StandardErrorPath`
- one of `StartCalendarInterval`, `StartInterval`, `KeepAlive`, or `RunAtLoad`

After writing the plist, validate and load it:

```bash
plutil -lint ~/Library/LaunchAgents/<label>.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<label>.plist
launchctl print gui/$(id -u)/<label>
```

Register the job only after the plist validates and the intended label is visible to `launchctl`.

## Crontab

Prefer a wrapper script with a stable path over a long inline command. Register that wrapper path or marker with `commandIncludes`.

When editing crontab:

1. Read current crontab with `crontab -l`; treat "no crontab" as empty.
2. Preserve unrelated lines and comments.
3. Update only the matching managed line.
4. Install the whole result with `crontab <tempfile>`.
5. Re-read `crontab -l` and confirm the marker appears exactly once.

## Verification

Before reporting success:

- Confirm the host scheduler contains the job.
- Confirm the job command or plist points to the intended script and working directory.
- Confirm the registry contains the matching managed entry.
- If LordClaw is running on the same host, confirm Cron Jobs > System shows the job.

If the scheduler write succeeds but the registry write fails, say the job exists but will not appear in LordClaw until registration succeeds. Fix the registry before doing unrelated work.