cron-model-migration

---
name: cron-model-migration
description: 'Safely change models for OpenClaw cron jobs without leaving behind session/model mismatch errors. Use when creating or editing cron jobs with `payload.model`, when moving a job between models/providers, when diagnosing `LiveSessionModelSwitchError`, or when deciding whether a cron should run in `sessionTarget: "isolated"`, `"current"`, `"main"`, or a custom persistent session.'
---

# Cron Model Migration

## Overview

Use this skill when a cron job needs a model change or when cron runs fail after a model change. The goal is simple: avoid reusing a session that is already bound to a different model.

## Core rule

Prefer **`sessionTarget: "isolated"`** for cron jobs that set `payload.model`.

Why:
- isolated jobs run dedicated agent turns instead of sharing the main session
- isolated runs are the safest place to override model/thinking
- persistent/shared sessions are where model-switch residue shows up most often

If a cron does **not** need shared conversation history, keep it isolated.

## Decision tree

### Case 1 — New cron job with a specific model

Create it as:
- `payload.kind = "agentTurn"`
- `sessionTarget = "isolated"`
- `payload.model = <target-model>`

Do **not** bind it to `current` or `session:xxx` unless you explicitly need persistent context across runs.

### Case 2 — Existing isolated cron, same session pattern, just changing model

Safe workflow:
1. Confirm the job is not actively running.
2. Disable the job.
3. Update `payload.model`.
4. Restart Gateway if the job has recently been running or already failed with a model-switch error.
5. Re-enable the job.
6. Force-run once and inspect the result.

If it still throws `LiveSessionModelSwitchError`, stop trying to patch it in place. Rebuild the job fresh.

### Case 3 — Existing cron bound to `current` or `session:xxx`

Treat this as **high risk** for model residue.

Best practice:
- create a **new job** instead of editing the old one in place
- move it to `sessionTarget: "isolated"` unless persistent context is truly required
- if persistent context is required, use a **new custom session id** instead of reusing the old one

Do not reuse a persistent session and expect model changes to be clean.

### Case 4 — Main-session cron

Avoid model overrides on main-session jobs unless there is a strong reason.

Why:
- main-session jobs share context with the main agent session
- changing model there can shift the shared session unexpectedly
- OpenClaw docs recommend model overrides primarily for isolated jobs

If the task needs a different model, split it into an isolated cron instead.

## Recommended migration workflow

Use this sequence for production changes:

1. **Inspect**
   - confirm `sessionTarget`
   - confirm `payload.kind`
   - confirm current `payload.model`
   - check recent run failures

2. **Classify**
   - isolated + stateless → update in place is usually fine
   - current/custom/main → prefer rebuild

3. **Apply**
   - small change: disable → update → restart → enable → force-run
   - risky change or prior switch error: create a new isolated job with the new model

4. **Verify**
   - run exactly once with `cron.run`
   - verify the run completed, not merely enqueued
   - verify delivery/output still works

5. **Cut over**
   - only remove the old job after the replacement job succeeds

## Anti-patterns

Avoid these:
- changing `payload.model` and immediately force-running repeatedly
- reusing `sessionTarget: "current"` for jobs that need model churn
- editing a persistent `session:xxx` job without changing the backing session id
- assuming `cron.run` enqueue success means the agent turn succeeded
- debugging only the prompt while ignoring session binding

## Troubleshooting `LiveSessionModelSwitchError`

When you see:
- `LiveSessionModelSwitchError: Live session model switch requested: ...`

Assume one of these first:
1. the job is reusing a live or persistent session already bound to another model
2. the job was edited in place after prior runs left session state behind
3. the job is using `current`, `main`, or a custom persistent session where override behavior is unsafe

Response order:
1. inspect job config
2. confirm `sessionTarget`
3. confirm whether the run is isolated or persistent
4. restart Gateway if stale execution state is plausible
5. if still failing, replace the job with a fresh isolated one

## Minimal safe templates

### Stateless background analysis

Use:
- `sessionTarget: "isolated"`
- `payload.kind: "agentTurn"`
- explicit `payload.model`
- optional `delivery.mode: "announce"` or `"none"`

### Persistent weekly summary that truly needs memory

Use:
- `sessionTarget: "session:<new-id>"`
- `payload.kind: "agentTurn"`
- explicit `payload.model`
- accept that model changes later should usually mean **creating a new session id/job**

## Practical rule of thumb

If you need to ask “can I safely switch this cron’s model in place?”, the default answer is:
- **yes** for isolated/stateless jobs, with one controlled validation run
- **no** for shared or persistent jobs; rebuild instead