Summary
The help text for openclaw cron add --tz says:
Timezone for cron expressions
This is misleading �� it implies the flag only affects --cron (cron expression) scheduling, when in reality its intended behavior is to also apply timezone context to --at (absolute datetime) strings.
Affects: all users using cron add with --at + --tz, who may not realize their timezone is being silently ignored.
The Discoverability Problem
There are two distinct issues caused by this documentation gap:
-
Users don't know --tz should work with --at: The description says "cron expressions" only, so users writing --at "09:00" --tz Asia/Shanghai don't realize they need to manually convert to UTC.
-
Users don't know --tz is broken for --at: Even users who expect --tz to work with --at get no error �� their timezone is silently ignored and the time is treated as UTC.
Data Supporting This Report
This caused a real misconfiguration: a daily summary job was set with --at "16:00" --tz Asia/Shanghai (intending 16:00 UTC+8), which silently created a job scheduled at 16:00 UTC (midnight UTC+8 the next day) instead. The bug was only discovered by manually inspecting jobs.json.
Proposed Documentation Fix
Before (current --help output for cron add):
--tz <timezone> Timezone for cron expressions
After (proposed):
--tz <timezone> Timezone for interpreting --cron expressions and
offset-less --at datetime strings (IANA, default: UTC)
And add a note in the docs / help output clarifying:
- For
--cron: the expression is interpreted in the given timezone
- For
--at: naive datetime strings (no UTC offset) are interpreted in the given timezone
--at strings with explicit UTC offset (e.g. 2026-04-02T09:00:00+08:00) ignore --tz
Related
Suggested labels: documentation, cli, ux
Related: #69975
Before / After
Before: --tz <timezone> Timezone for cron expressions
After: --tz <timezone> Timezone for interpreting --cron expressions and offset-less --at datetime strings (IANA, default: UTC)
Summary
The help text for
openclaw cron add --tzsays:This is misleading �� it implies the flag only affects
--cron(cron expression) scheduling, when in reality its intended behavior is to also apply timezone context to--at(absolute datetime) strings.Affects: all users using
cron addwith--at+--tz, who may not realize their timezone is being silently ignored.The Discoverability Problem
There are two distinct issues caused by this documentation gap:
Users don't know
--tzshould work with--at: The description says "cron expressions" only, so users writing--at "09:00" --tz Asia/Shanghaidon't realize they need to manually convert to UTC.Users don't know
--tzis broken for--at: Even users who expect--tzto work with--atget no error �� their timezone is silently ignored and the time is treated as UTC.Data Supporting This Report
This caused a real misconfiguration: a daily summary job was set with
--at "16:00" --tz Asia/Shanghai(intending 16:00 UTC+8), which silently created a job scheduled at 16:00 UTC (midnight UTC+8 the next day) instead. The bug was only discovered by manually inspectingjobs.json.Proposed Documentation Fix
Before (current
--helpoutput forcron add):After (proposed):
And add a note in the docs / help output clarifying:
--cron: the expression is interpreted in the given timezone--at: naive datetime strings (no UTC offset) are interpreted in the given timezone--atstrings with explicit UTC offset (e.g.2026-04-02T09:00:00+08:00) ignore--tzRelated
--atHH:MM +--tznot working)Related: #69975
Before / After
Before:
--tz <timezone> Timezone for cron expressionsAfter:
--tz <timezone> Timezone for interpreting --cron expressions and offset-less --at datetime strings (IANA, default: UTC)