</Accordion>

</AccordionGroup>

### Command payloads

Use command payloads for deterministic scripts that should run inside the Gateway scheduler without starting a model-backed isolated agent turn. Command jobs execute on the Gateway host, capture stdout/stderr, record the run in cron history, and reuse the same `announce`, `webhook`, and `none` delivery modes as isolated jobs.

<Note>

Command cron is an operator-admin Gateway automation surface, not an agent

`tools.exec` call. Creating, updating, removing, or manually running cron jobs

requires `operator.admin`; scheduled command runs later execute inside the

Gateway process as that admin-authored automation. Agent exec policy such as

`tools.exec.mode`, approval prompts, and per-agent tool allowlists governs

model-visible exec tools, not command cron payloads.

</Note>

```bash

openclaw cron create "*/15 * * * *" \

--name "Queue depth probe" \

--command "scripts/check-queue.sh" \

--command-cwd "/srv/app" \

--announce \

--channel telegram \

--to "-1001234567890"

```

`--command <shell>` stores `argv: ["sh", "-lc", <shell>]`. Use `--command-argv '["node","scripts/report.mjs"]'` when you want exact argv execution without shell parsing. Optional `--command-env KEY=VALUE`, `--command-input`, `--timeout-seconds`, `--no-output-timeout-seconds`, and `--output-max-bytes` fields control the process environment, stdin, and output bounds.

If stdout is non-empty, that text is the delivered result. If stdout is empty and stderr is non-empty, stderr is delivered. If both streams are present, cron delivers a small `stdout:` / `stderr:` block. A zero exit code records the run as `ok`; non-zero exit, signal, timeout, or no-output timeout records `error` and can trigger failure alerts. A command that prints only `NO_REPLY` uses the normal cron silent-token suppression and posts nothing back to chat.

### Payload options for isolated jobs

<ParamField path="--message" type="string" required>

--webhook "https://example.invalid/openclaw/cron"

```

</Tab>

<Tab title="Command output">

```bash

openclaw cron create "*/15 * * * *" \

--name "Queue depth probe" \

--command "scripts/check-queue.sh" \

--command-cwd "/srv/app" \

--announce \

--channel telegram \

--to "-1001234567890"

```

</Tab>

</Tabs>

## Webhooks

--webhook "https://example.invalid/openclaw/cron"

```

Use `--command` for deterministic shell-style jobs that should run inside OpenClaw cron without starting an isolated agent/model run:

<Note>

Command cron jobs are admin-authored Gateway automation. Creating, editing,

removing, or manually running them requires `operator.admin`; the scheduled run

later executes in the Gateway process, not as an agent `tools.exec` tool call.

`tools.exec.*` and exec approvals still govern model-visible exec tools.

</Note>

```bash

openclaw cron create "*/15 * * * *" \

--name "Queue depth probe" \

--command "scripts/check-queue.sh" \

--command-cwd "/srv/app" \

--announce \

--channel telegram \

--to "-1001234567890"

```

`--command <shell>` stores `argv: ["sh", "-lc", <shell>]`. Use `--command-argv '["node","scripts/report.mjs"]'` for exact argv execution. Command jobs capture stdout/stderr, record normal cron history, and route output through the same `announce`, `webhook`, or `none` delivery modes as isolated jobs. A command that prints only `NO_REPLY` is suppressed.

## Sessions

`--session` accepts `main`, `isolated`, `current`, or `session:<id>`.

no reply payload is produced, so model/provider failures still increment error

counters and trigger failure notifications.

Command cron jobs do not start an isolated agent turn. A zero exit code records

`ok`; non-zero exit, signal, timeout, or no-output timeout records `error` and

can trigger the same failure notification path.

If an isolated run times out before the first model request, `openclaw cron show`

and `openclaw cron runs` include a phase-specific error such as

`setup timed out before runner start` or

`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.

Create a command job with exact argv, cwd, env, stdin, and output limits:

```bash

openclaw cron create "*/30 * * * *" \

--name "Position export" \

--command-argv '["node","scripts/export-position.mjs"]' \

--command-cwd "/srv/app" \

--command-env "NODE_ENV=production" \

--command-input '{"mode":"summary"}' \

--timeout-seconds 120 \

--no-output-timeout-seconds 30 \

--output-max-bytes 65536 \

--webhook "https://example.invalid/openclaw/cron"

```

## Common admin commands

Manual run and inspection:

).toBe(true);

});

it("accepts command cron payloads", () => {

expect(

validateCronAddParams({

...minimalAddParams,

sessionTarget: "isolated",

payload: {

kind: "command",

argv: ["sh", "-lc", "echo ok"],

cwd: "/srv/example",

env: { FOO: "bar" },

input: "stdin",

timeoutSeconds: 30,

noOutputTimeoutSeconds: 5,

outputMaxBytes: 4096,

},

}),

).toBe(true);

expect(

validateCronUpdateParams({

id: "job-1",

patch: {

payload: {

kind: "command",

argv: ["sh", "-lc", "echo updated"],

},

},

}),

).toBe(true);

});

it("rejects add params when required scheduling fields are missing", () => {

const { wakeMode: _wakeMode, ...withoutWakeMode } = minimalAddParams;

expect(validateCronAddParams(withoutWakeMode)).toBe(false);

);

}

/** Builds command payload variants while preserving create/patch argv optionality. */

function cronCommandPayloadSchema(params: { argv: TSchema }) {

return Type.Object(

{

kind: Type.Literal("command"),

argv: params.argv,

cwd: Type.Optional(Type.String({ minLength: 1 })),

env: Type.Optional(Type.Record(Type.String({ minLength: 1 }), Type.String())),

input: Type.Optional(Type.String()),

timeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),

noOutputTimeoutSeconds: Type.Optional(Type.Number({ minimum: 0 })),

outputMaxBytes: Type.Optional(Type.Integer({ minimum: 1 })),

},

{ additionalProperties: false },

);

}

/** Session target accepted by cron jobs. */

const CronSessionTargetSchema = Type.Union([

Type.Literal("main"),

message: NonEmptyString,

toolsAllow: Type.Array(Type.String()),

}),

cronCommandPayloadSchema({

argv: Type.Array(NonEmptyString, { minItems: 1 }),

}),

]);

/** Partial cron payload for job updates. */

message: Type.Optional(NonEmptyString),

toolsAllow: Type.Union([Type.Array(Type.String()), Type.Null()]),

}),

cronCommandPayloadSchema({

argv: Type.Optional(Type.Array(NonEmptyString, { minItems: 1 })),

}),

]);

/** Failure alert policy for repeated cron run failures. */

expect(params?.failureAlert).toBe(false);

});

it("rejects command payloads from the agent cron tool on add", async () => {

const tool = createTestCronTool();

await expect(

tool.execute("call-command-add", {

action: "add",

job: {

name: "command",

schedule: { at: new Date(123).toISOString() },

sessionTarget: "isolated",

payload: { kind: "command", argv: ["sh", "-lc", "echo ok"] },

},

}),

).rejects.toThrow("cron command payloads cannot be created or edited");

expect(callGatewayMock).not.toHaveBeenCalled();

});

it.each([

["delivery.channel", { channel: " ", to: "chat-1" }],

["delivery.to", { mode: "announce", channel: "telegram", to: " \t" }],

expect(params?.patch?.failureAlert).toBe(false);

});

it("rejects command payloads from the agent cron tool on update", async () => {

const tool = createTestCronTool();

await expect(

tool.execute("call-command-update", {

action: "update",

id: "job-4",

patch: {

payload: { kind: "command", argv: ["sh", "-lc", "echo ok"] },

},

}),

).rejects.toThrow("cron command payloads cannot be created or edited");

expect(callGatewayMock).not.toHaveBeenCalled();

});

it("recovers flattened payload patch params for update action", async () => {

callGatewayMock.mockResolvedValueOnce({ ok: true });

return text.slice(0, index).trim();

}

function assertNoCronCommandPayload(value: unknown): void {

if (!isRecord(value)) {

return;

}

const payload = isRecord(value.payload) ? value.payload : undefined;

if (payload?.kind === "command") {

throw new Error(

"cron command payloads cannot be created or edited through the agent cron tool; use the CLI or Gateway API.",

);

}

}

function truncateText(input: string, maxLen: number) {

if (input.length <= maxLen) {

return input;

throw new Error("job required");

}

const canonicalJob = canonicalizeCronToolObject(params.job as Record<string, unknown>);

assertNoCronCommandPayload(canonicalJob);

assertCronDeliveryInputNonBlankFields(canonicalJob.delivery);

const job =

normalizeCronJobCreate(canonicalJob, {

const canonicalPatch = canonicalizeCronToolObject(

params.patch as Record<string, unknown>,

);

assertNoCronCommandPayload(canonicalPatch);

assertCronDeliveryInputNonBlankFields(canonicalPatch.delivery);

const patch = normalizeCronJobPatch(canonicalPatch) ?? canonicalPatch;

if (recoveredFlatPatch && isEmptyRecoveredCronPatch(patch)) {