openclaw - 💡(How to fix) Fix docs+fix: script cron jobs have undocumented 10-min default timeout; timeoutSeconds not documented for script payload [1 comments, 2 participants]

Summary

cron jobs with payload.kind = "script" have a hardcoded default timeout of 600 seconds (10 minutes). This default is not documented anywhere. timeoutSeconds is listed in the docs only for agentTurn payloads, leaving script job authors with no guidance.

Source (compiled from src/cron/service/timeout-policy.ts)

const DEFAULT_JOB_TIMEOUT_MS = 10 * 60_000;        // script and systemEvent — 10 min
const AGENT_TURN_SAFETY_TIMEOUT_MS = 60 * 60_000;  // agentTurn — 60 min

The asymmetry is significant and undocumented: agentTurn jobs get a 60-minute safety ceiling by default; script jobs get only 10 minutes.

resolveCronJobTimeoutMs behavior

function resolveCronJobTimeoutMs(job) {
  const configuredTimeoutMs =
    (job.payload.kind === "agentTurn" || job.payload.kind === "script") &&
    typeof job.payload.timeoutSeconds === "number"
      ? Math.floor(job.payload.timeoutSeconds * 1000)
      : void 0;

  if (configuredTimeoutMs === void 0)
    return job.payload.kind === "agentTurn"
      ? AGENT_TURN_SAFETY_TIMEOUT_MS   // 60 min default
      : DEFAULT_JOB_TIMEOUT_MS;        // 10 min default

  return configuredTimeoutMs <= 0 ? void 0 : configuredTimeoutMs;  // 0 = unlimited
}

• timeoutSeconds does work on script payloads — no platform ceiling above it
• timeoutSeconds: 0 means no timeout (unlimited)
• Without it, script jobs silently hit 10 min and fail with "cron: job execution timed out"

What the docs say

The cron jobs reference lists timeoutSeconds under agentTurn fields only:

timeoutSeconds: optional timeout override

The script payload schema in the docs shows only command, args, env, cwd — no timeoutSeconds.

Impact

Any long-running script job (batch importers, data sync, PDF processing, etc.) silently fails after 10 minutes with consecutiveErrors accumulating. Authors have no documented way to fix it and may not realize the issue is a timeout since the error message is generic.

Requests

1. Add timeoutSeconds to the script payload docs — same treatment as agentTurn
2. Document the default timeout per payload kind (script = 10 min, agentTurn = 60 min)
3. Document timeoutSeconds: 0 = unlimited behavior
4. Consider raising DEFAULT_JOB_TIMEOUT_MS for script from 10 to 30–60 min — 10 min is too short for legitimate workloads
5. Add a global config knob (e.g. cron.defaultScriptTimeoutSeconds) for operators who want a different default without patching every job